第52章 アーティファクトの公開

This chapter is about how you declare the outgoing artifacts of your project, and how to work with them (e.g. upload them). We define the artifacts of the projects as the files the project provides to the outside world. This might be a library or a ZIP distribution or any other file. A project can publish as many artifacts as it wants.

この章では、プロジェクトが公開するアーティファクト(成果物)の定義方法と取り扱い(アップロードする方法など)について解説します。ここでいうプロジェクトのアーティファクトとは、外部の世界へ提供するファイルのことを指します。ライブラリやZIPの配布物かもしれませんし、なにか他のファイルかもしれません。一つのプロジェクトから、いくつでも好きなだけアーティファクトを公開することができます。

Like dependencies, artifacts are grouped by configurations. In fact, a configuration can contain both artifacts and dependencies at the same time.

依存関係と同じように、アーティファクトもコンフィギュレーションによってグループ化されます。実際、コンフィギュレーションにはアーティファクトと依存関係、両方を同時に含めることもできます。

For each configuration in your project, Gradle provides the tasks uploadConfigurationName and buildConfigurationName. ^[26] Execution of these tasks will build or upload the artifacts belonging to the respective configuration.

Gradleは、プロジェクト内のすべてのコンフィギュレーションに対して、uploadコンフィグレーション名 タスクとbuildコンフィグレーション名 タスクを提供します。 ^[27] これらのタスクを実行すると、対象のコンフィギュレーションに属しているアーティファクトをビルドしたり、アップロードしたりできます。

表23.5「Javaプラグイン - 依存関係のコンフィギュレーションJava plugin - dependency configurations」 shows the configurations added by the Java plugin. Two of the configurations are relevant for the usage with artifacts. The archives configuration is the standard configuration to assign your artifacts to. The Java plugin automatically assigns the default jar to this configuration. We will talk more about the runtime configuration in 「プロジェクトライブラリについての追記事項More about project libraries」. As with dependencies, you can declare as many custom configurations as you like and assign artifacts to them.

表23.5「Javaプラグイン - 依存関係のコンフィギュレーションJava plugin - dependency configurations」に、Javaプラグインが追加するコンフィギュレーションの一覧を載せています。これらのうち、アーティファクトを使うに当たって関係があるものは次の二つです。archivesコンフィギュレーションは、プロジェクトのアーティファクトを含めるための標準のコンフィギュレーションです。Javaプラグインは、デフォルトのjarを自動的にこのコンフィギュレーションに追加します。「プロジェクトライブラリについての追記事項More about project libraries」では、runtimeコンフィギュレーションについて詳しく解説します。また、アーティファクトを追加するための独自コンフィギュレーションも、依存関係のコンフィギュレーションと同じようにいくつでも宣言して追加できます。

We have said that there is a specific upload task for each configuration. But before you can do an upload, you have to configure the upload task and define where to publish the artifacts to. The repositories you have defined (as described in 「リポジトリ Repositories」) are not automatically used for uploading. In fact, some of those repositories only allow downloading artifacts, not uploading. Here is an example of how you can configure the upload task of a configuration:

先ほど、すべてのコンフィギュレーションにアップロード用のタスクが作成されることを説明しました。しかし、実際にアーティファクトをアップロードするには、どこに公開するかを設定する必要があります。プロジェクトに定義したリポジトリ(「リポジトリ Repositories」)が、勝手にアップロードに使用されることはありません。実際、それらのリポジトリには、ダウンロードしか許していないものもあるでしょう。次の例は、アップロードタスクの設定方法を示すものです。

repositories {
    flatDir {
        name "fileRepo"
        dirs "repo"
    }
}

uploadArchives {
    repositories {
        add project.repositories.fileRepo
        ivy {
            credentials {
                username "username"
                password "pw"
            }
            url "http://repo.mycompany.com"
        }
    }
}

As you can see, you can either use a reference to an existing repository or create a new repository. As described in 「Ivyリゾルバについて More about Ivy resolvers」, you can use all the Ivy resolvers suitable for the purpose of uploading.

この例のように、定義済みのリポジトリを参照することもできますし、新しくリポジトリ定義を作って追加することもできます。「Ivyリゾルバについて More about Ivy resolvers」のときと同じように、アップロードでもすべてのIvyリポジトリリゾルバを使うことができます。

If an upload repository is defined with multiple patterns, Gradle must choose a pattern to use for uploading each file. By default, Gradle will upload to the pattern defined by the url parameter, combined with the optional layout parameter. If no url parameter is supplied, then Gradle will use the first defined artifactPattern for uploading, or the first defined ivyPattern for uploading Ivy files, if this is set.

アップロード先のリポジトリ定義に複数のレイアウトパターンが含まれている場合、どのパターンに従ってファイルをアップロードするか決定しなければなりません。 デフォルトでは、Gradleはurlパラメーターを参照します。layoutが定義されていれば、それも併せて使用します。 urlパラメーターが未定義の場合は、定義されているartifactPatternのうち最初のものがアップロードに使用され、また、定義されているivyPatternのうち最初のものがivyファイルのアップロードに使用されます。

Uploading to a Maven repository is described in 「Mavenリポジトリとの相互作用Interacting with Maven repositories」.

Mavenリポジトリへのアップロードについては、「Mavenリポジトリとの相互作用Interacting with Maven repositories」をご参照ください。

If your project is supposed to be used as a library, you need to define what are the artifacts of this library and what are the dependencies of these artifacts. The Java plugin adds a runtime configuration for this purpose, with the implicit assumption that the runtime dependencies are the dependencies of the artifact you want to publish. Of course this is fully customizable. You can add your own custom configuration or let the existing configurations extend from other configurations. You might have a different group of artifacts which have a different set of dependencies. This mechanism is very powerful and flexible.

プロジェクトがライブラリとして使用される場合、そのライブラリのアーティファクトは何か、アーティファクトが依存しているライブラリは何か、定義しておく必要があります。Javaプラグインは、この目的のためにruntimeというコンフィギュレーションを追加します。これは、公開したいアーティファクトはruntime依存関係に依存しているはずだ、という暗黙的な仮定の上での仕様ですが、もちろんこのあたりの設定は完全にカスタマイズ可能です。独自のコンフィギュレーションを作成してもいいし、既存のコンフィギュレーションの継承元を変えてもいいでしょう。別の依存関係をもつ別のアーティファクトを加えることもできます。このメカニズムは非常に強力で、柔軟性豊かなものです。

If someone wants to use your project as a library, she simply needs to declare which configuration of the dependency to depend on. A Gradle dependency offers the configuration property to declare this. If this is not specified, the default configuration is used (see 「依存するコンフィギュレーションの指定 Dependency configurations」). Using your project as a library can either happen from within a multi-project build or by retrieving your project from a repository. In the latter case, an ivy.xml descriptor in the repository is supposed to contain all the necessary information. If you work with Maven repositories you don't have the flexibility as described above. For how to publish to a Maven repository, see the section 「Mavenリポジトリとの相互作用Interacting with Maven repositories」.

誰かがあなたのプロジェクトをライブラリとして使いたいとしましょう。そのときすべきことは、あなたのプロジェクトの内、どのコンフィグレーションに依存するのか指定することだけです。Gradleの依存関係定義では、configurationというプロパティを指定できるようになっています。もしこのプロパティが指定されていなければ、defaultコンフィギュレーションが使用されます(「依存するコンフィギュレーションの指定 Dependency configurations」をご参照ください)。 あるプロジェクトがライブラリとして使われるのには、二つのケースがあります。マルチプロジェクトの中からライブラリとして参照される場合と、リポジトリからプロジェクトを取得する場合です。後者のケースでは、リポジトリにあるivy.xmlが必要な情報を全て含めることになっていますので、Mavenリポジトリを使う場合は先ほど述べたような柔軟性は持てません。Mavenリポジトリへライブラリを公開する方法については、「Mavenリポジトリとの相互作用Interacting with Maven repositories」をご覧ください。