<!--
  ~ 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_dependencies_tutorial" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Artifact Basics</title>

    <note>
        <para>This chapter is currently under construction.</para>
        <para>For all the details of artifact handling see <xref linkend="artifact_management"/>.</para>
    </note>

    <para>This chapter introduces some of the basics of artifact handling in Gradle.</para>

    <section id="sec:artifact_configurations">
        <title>Artifact configurations</title>
        <para>Artifacts are grouped into <firstterm>configurations</firstterm>. A configuration is simply a set of files
            with a name. You can use them to declare the external dependencies your project has, or to declare the
            artifacts which your project publishes.</para>
        <para>To define a configuration:</para>
        <sample id="defineConfiguration" dir="userguide/artifacts/defineConfiguration" title="Definition of a configuration">
            <sourcefile file="build.gradle" snippet="define-configuration"/>
        </sample>
        <para>To access a configuration:</para>
        <sample id="defineConfiguration" dir="userguide/artifacts/defineConfiguration" title="Accessing a configuration">
            <sourcefile file="build.gradle" snippet="lookup-configuration"/>
        </sample>
        <para>To configure a configuration:</para>
        <sample id="defineConfiguration" dir="userguide/artifacts/defineConfiguration" title="Configuration of a configuration">
            <sourcefile file="build.gradle" snippet="configure-configuration"/>
        </sample>
    </section>

    <section>
        <title>Repositories</title>
        <para>Artifacts are stored in <firstterm>repositories</firstterm>.</para>
        <para>To use maven central repository:</para>
        <sample id="defineRepository" dir="userguide/artifacts/defineRepository" title="Usage of Maven central repository">
            <sourcefile file="build.gradle" snippet="maven-central"/>
        </sample>
        <para>To use a local directory:</para>
        <sample id="defineRepository" dir="userguide/artifacts/defineRepository" title="Usage of a local directory">
            <sourcefile file="build.gradle" snippet="flat-dir"/>
        </sample>
        <para>You can also use any Ivy resolver. You can have multiple repositories.</para>
        <para>To access a repository:</para>
        <sample id="defineRepository" dir="userguide/artifacts/defineRepository" title="Accessing a repository">
            <sourcefile file="build.gradle" snippet="lookup-resolver"/>
        </sample>
        <para>To configure a repository:</para>
        <sample id="defineRepository" dir="userguide/artifacts/defineRepository" title="Configuration of a repository">
            <sourcefile file="build.gradle" snippet="configure-resolver"/>
        </sample>
    </section>

    <section>
        <title>External dependencies</title>
        <para>To define an external dependency, you add a dependency to a configuration:</para>
        <sample id="externalDependencies" dir="userguide/artifacts/externalDependencies" title="Definition of an external dependency">
            <sourcefile file="build.gradle" snippet="define-dependency"/>
        </sample>
        <para><literal>group</literal> and <literal>version</literal> are optional</para>
        <para>TBD - configuring an external dependency</para>
        <para>To use the external dependencies of a configuration:</para>
        <sample id="externalDependencies" dir="userguide/artifacts/externalDependencies"  title="Usage of external dependency of a configuration">
            <sourcefile file="build.gradle" snippet="use-configuration"/>
            <output args="-q listJars"/>
        </sample>
    </section>

    <section>
        <title>Artifact publishing</title>
        <para>TBD</para>
    </section>

    <section>
        <title>API</title>
        <para>Configurations are contained in a <apilink class="org.gradle.api.artifacts.ConfigurationContainer"/>.
            Each configuration implements the <apilink class="org.gradle.api.artifacts.Configuration"/>.</para>
    </section>
</chapter>
