<!--
  ~ Copyright 2009 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->
<chapter id="artifact_management" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Artifact Management</title>
    <section>
        <title>Introduction</title>
        <para>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.
        </para>
    </section>
    <section id="artifacts_and_configurations">
        <title>Artifacts and configurations</title>
        <para>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:
        </para>
        <sample id="assignArtifact" dir="userguide/artifacts/uploading" title="Assignment of an artifact to a configuration">
            <sourcefile file="build.gradle" snippet="assign-artifact"/>
        </sample>
        <para>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 <code>upload[ConfigurationName]</code> and
        <code>build[ConfigurationName]</code>.
        <footnote><para>To be exact, the Base plugin provides those tasks. The BasePlugin is automatically applied, if you use
        the Java plugin.</para></footnote>
        Execution of these tasks will build or upload the artifacts belonging to
        the respective configuration.
        </para>
        <para>Table <xref linkend="tab:configurations"/> shows the configurations added by the Java plugin. Two of the
        configurations are relevant for the usage with artifacts. The <code>archives</code> 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 <code>default</code> configuration in <xref linkend="project_libraries"/>.
            As with dependencies, you can declare as many custom configurations as you like and assign artifacts to them.
        </para>
        <para>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.</para>
    </section>
    <section>
        <title>Uploading artifacts</title>
        <para>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 <xref linkend="sec: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:
        </para>
        <sample id="uploading" dir="userguide/artifacts/uploading" title="Configuration of the upload task">
            <sourcefile file="build.gradle" snippet="uploading"/>
        </sample>
        <para>As you can see, you can either use a reference to an existing repository or create a new repository.
        As described in <xref linkend="sub:more_about_ivy_resolvers"/>, you can use all the Ivy resolvers suitable
        for the purpose of uploading.</para>
        <para>Uploading to a Maven repository is described in <xref linkend="uploading_to_maven_repositories"/>.</para>
    </section>
    <section id="project_libraries">
        <title>More about project libraries</title>
        <para>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 <code>default</code> configuration for
            this purpose. This configuration extends both the <code>archives</code> and the <code>runtime</code> configuration,
            with the implicit assumption that the <code>runtime</code> dependencies are the dependencies of the <code>archives</code>
            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.
            </para>
        <para>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 <code>configuration</code> property to declare this. If this
            is not specified, the <code>default</code> configuration is used (see <xref linkend="sec: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 <xref linkend="uploading_to_maven_repositories"/>.
        </para>
    </section>
</chapter>
