⚠

This chapter describes the original publishing mechanism available in Gradle 1.0, which has since been superseded by an alternative model. The approach detailed in this chapter — based on Upload tasks — is deprecated and should not be used in new builds. We cover it in order to help users work with and update existing builds that use it.

Introduction

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.

Artifacts and configurations

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 when the base plugin is applied. Execution of these tasks will build or upload the artifacts belonging to the respective configuration.

This listing 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 further on. As with dependencies, you can declare as many custom configurations as you like and assign artifacts to them.

Declaring artifacts

Archive task artifacts

You can use an archive task to define an artifact:

Example 1. Defining an artifact using an archive task
build.gradle
task myJar(type: Jar)

artifacts {
    archives myJar
}
build.gradle.kts
val myJar by tasks.registering(Jar::class)

artifacts {
    add("archives", myJar)
}

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.

File artifacts

You can also use a file to define an artifact:

Example 2. Defining an artifact using a file
build.gradle
def someFile = file("$buildDir/somefile.txt")

artifacts {
    archives someFile
}
build.gradle.kts
val someFile = file("$buildDir/somefile.txt")

artifacts {
    add("archives", someFile)
}

Gradle will figure out the properties of the artifact based on the name of the file. You can customize these properties:

Example 3. Customizing an artifact
build.gradle
task myTask(type:  MyTaskType) {
    destFile = file("$buildDir/somefile.txt")
}

artifacts {
    archives(myTask.destFile) {
        name 'my-artifact'
        type 'text'
        builtBy myTask
    }
}
build.gradle.kts
val myTask by tasks.registering(MyTaskType::class) {
    destFile = file("$buildDir/somefile.txt")
}

artifacts {
    add("archives", myTask.map { it -> it.destFile }) {
        name = "my-artifact"
        type = "text"
        builtBy(myTask)
    }
}

There is a map-based syntax for defining an artifact using a file. The map must include a file entry that defines the file. The map may include other artifact properties:

Example 4. Map syntax for defining an artifact using a file
build.gradle
task generate(type:  MyTaskType) {
    destFile = file("$buildDir/somefile.txt")
}

artifacts {
    archives file: generate.destFile, name: 'my-artifact', type: 'text', builtBy: generate
}
build.gradle.kts
val generate by tasks.registering(MyTaskType::class) {
    destFile = file("$buildDir/somefile.txt")
}

artifacts {
    add("archives",
        mapOf("file" to generate.get().destFile, "name" to "my-artifact", "type" to "text", "builtBy" to generate))
}

Publishing artifacts

We have said that there is a specific upload task for each configuration. 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 Declaring 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:

Example 5. Configuration of the upload task
build.gradle
repositories {
    flatDir {
        name "fileRepo"
        dirs "repo"
    }
}

uploadArchives {
    repositories {
        add project.repositories.fileRepo
        ivy {
            credentials {
                username "username"
                password "pw"
            }
            url "http://repo.mycompany.com"
        }
    }
}
build.gradle.kts
repositories {
    flatDir {
        name = "fileRepo"
        dirs("repo")
    }
}

tasks.named<Upload>("uploadArchives") {
    repositories {
        add(project.repositories["fileRepo"])
        ivy {
            credentials {
                username = "username"
                password = "pw"
            }
            url = uri("http://repo.mycompany.com")
        }
    }
}

As you can see, you can either use a reference to an existing repository or create a new repository.

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.

Uploading to a Maven repository is described in this section.

More about project libraries

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.

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 What are 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 Uploading to Maven repositories.