This chapter is about how you declare what are the 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 want to provide to the outside world. This can be a library or a distribution or any other file. Usually artifacts are archives, but not necessarily. In the Maven world a project can provide only one artifact. With Gradle a project can provide as many artifacts as needed.
Like dependencies, artifacts are grouped by configurations. In fact, a configuration can contain both, artifacts and dependencies, at the same time. To assign an artifact to a configuration, you can write:
Example 36.1. Assignment of an artifact to a configuration
build.gradle
task myJar(type: Jar) artifacts { archives myJar }
What do you gain by assigning an artifact to a configuration? For each configuration (also for the custom
ones added by you) Gradle provides the tasks upload[ConfigurationName]
and
build[ConfigurationName]
.
[15]
Execution of these tasks will build or upload the artifacts belonging to
the respective configuration.
Table Table 20.5, “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 default
configuration in Section 36.4, “More about project libraries”.
As with dependencies, you can declare as many custom configurations as you like and assign artifacts to them.
It is important to note that the custom archives you are creating as part of your build are not automatically assigned to any configuration. You have to explicitly do this assignment.
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 upload. The repositories you have defined (as described in Section 35.5, “Repositories”) are not automatically used for uploading. In fact, some of those repositories allow only for artifacts downloading. Here is an example how you can configure the upload task of a configuration:
Example 36.2. Configuration of the upload task
build.gradle
repositories { flatDir(name: 'fileRepo', dirs: "$projectDir/repo") } uploadArchives { uploadDescriptor = false repositories { add project.repositories.fileRepo add(new org.apache.ivy.plugins.resolver.SshResolver()) { name = 'sshRepo' user = 'username' userPassword = 'pw' host = "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 Section 35.5.6, “More about Ivy resolvers”, you can use all the Ivy resolvers suitable for the purpose of uploading.
Uploading to a Maven repository is described in Section 37.6, “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 default
configuration for
this purpose. This configuration extends both the archives
and the runtime
configuration,
with the implicit assumption that the runtime
dependencies are the dependencies of the archives
configuration. Of course this is fully customizable. You can add your own custom configuration or let the the
existing configurations extends from other configurations. You might have different group of artifacts which have
a different set of dependencies. This mechanism is very powerful and flexible.
If someone wants to use your project as a library, she simply needs to declare on 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 Section 35.3.10, “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 neccesary 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 Section 37.6, “Interacting with Maven repositories”.
[15] To be exact, the Base plugin provides those tasks. The BasePlugin is automatically applied, if you use the Java plugin.