第六十四章. Ivy发布（新）

这种使用 Ivy 格式发布的功能是由“ivy-publish”插件提供的。
The ability to publish in the Ivy format is provided by the “ivy-publish” plugin.

“publishing”在project上创建了一个名为“publishing” 的PublishingExtension类型的扩展。这个扩展提供了两个容器，一个叫publications，一个叫repositories。“ivy-publish”适用于IvyPublication publications 和 IvyArtifactRepository repositories。
The “publishing” plugin creates an extension on the project named “publishing” of type PublishingExtension. This extension provides a container of named publications and a container of named repositories. The “ivy-publish” plugin works with IvyPublication publications and IvyArtifactRepository repositories.

apply plugin: 'ivy-publish'

应用“ivy-publish”插件将会执行以下操作：
Applying the “ivy-publish” plugin does the following:

Publication对象描述了要创建的发布内容的结构和配置。Publications是通过任务发布到仓库的，发布对象的配置明确地决定了要发布的内容。一个项目的所有publications都会在PublishingExtension.getPublications()容器中定义，每一个publication在项目中都具有唯一名称。
Publication objects describe the structure/configuration of a publication to be created. Publications are published to repositories via tasks, and the configuration of the publication object determines exactly what is published. All of the publications of a project are defined in the PublishingExtension.getPublications() container. Each publication has a unique name within the project.

要使“ivy-publish”插件起作用，必须将一个 IvyPublication 添加到publications集合里。这个publications决定了实际要发布的工件，以及在关联的Ivy模块描述符文件中包含的详细信息。通过添加组件，自定义工件以及直接修改生成的模块描述符文件，可以配置一个publication。
For the “ivy-publish” plugin to have any effect, a IvyPublication must be added to the set of publications. This publication determines which artifacts are actually published as well as the details included in the associated Ivy module descriptor file. A publication can be configured by adding components, customizing artifacts, and by modifying the generated module descriptor file directly.

publications {
        ivyJava(IvyPublication) {
            from components.java
        }
    }

task sourceJar(type: Jar) {
        from sourceSets.main.java
        classifier "source"
    }
    publishing {
        publications {
            ivy(IvyPublication) {
                from components.java
                artifact(sourceJar) {
                    type "source"
                    conf "runtime"
                }
            }
        }
    }

publishing {
        publications {
            ivy(IvyPublication) {
                organisation 'org.gradle.sample'
                module 'project1-sample'
                revision '1.1'
                descriptor.status = 'milestone'

                from components.java
            }
        }
    }

publications {
        ivyCustom(IvyPublication) {
            descriptor.withXml {
                asNode().info[0].appendNode('description', 'A demonstration of ivy descriptor customization')
            }
        }
    }

task apiJar(type: Jar) {
        baseName "publishing-api"
        from sourceSets.main.output
        exclude '**/impl/**'
    }
    publishing {
        publications {
            impl(IvyPublication) {
                organisation 'org.gradle.sample.impl'
                module 'project2-impl'
                revision '1.1'

                from components.java
            }
            api(IvyPublication) {
                organisation 'org.gradle.sample'
                module 'project2-api'
                revision '2'
            }
        }
    }

要发布的内容会被发布到仓库中。要发布到的仓库由 PublishingExtension.getRepositories() 容器定义。
Publications are published to repositories. The repositories to publish to are defined by the PublishingExtension.getRepositories() container.

repositories {
        ivy {
            url "$buildDir/repo" // change to point to your repo, e.g. http://my.org/repo
        }
    }

声明发布仓库的 DSL 和声明依赖仓库的 DSL （RepositoryHandler）是一样的。然而，在 Ivy 发布的场景中，只能通过 ivy() 方法创建的仓库才可以作为发布的目标地方。比如，你不能把一个 IvyPublication 发布到一个 Maven 仓库中。
The DSL used to declare repositories for publishing is the same DSL that is used to declare repositories for dependencies (RepositoryHandler). However, in the context of Ivy publication only the repositories created by the ivy() methods can be used as publication destinations. You cannot publish an IvyPublication to a Maven repository for example.

对每一个在 publishing.publications 和 publishing.repositories 容器中分别组合的IvyPublication 和 IvyArtifactRepository，“ivy-publish” 插件自动为它们创建了一个 PublishToIvyRepository 任务。
The “ivy-publish” plugin automatically creates a PublishToIvyRepository task for each IvyPublication and IvyArtifactRepository combination in the publishing.publications and publishing.repositories containers respectively.

这个创建的任务使用“publish«发布名称»PublicationTo«仓库名称»Repository”的方式来命名。所以在这个例子中，添加了一个 PublishToIvyRepository 任务，并命名为“publishIvyJavaPublicationToIvyRepository”。
The created task is named using the pattern "publish«NAME OF PUBLICATION»PublicationTo«NAME OF REPOSITORY»Repository". So in this example a single PublishToIvyRepository task is be added, named 'publishIvyJavaPublicationToIvyRepository'.

apply plugin: 'java'
apply plugin: 'ivy-publish'

group = 'org.gradle.sample'
version = '1.0'

publishing {
    publications {
        ivyJava(IvyPublication) {
            from components.java
        }
    }
    repositories {
        ivy {
            url "$buildDir/repo" // change to point to your repo, e.g. http://my.org/repo
        }
    }
}

> gradle publishIvyJavaPublicationToIvyRepository
:generateDescriptorFileForIvyJavaPublication
:compileJava UP-TO-DATE
:processResources UP-TO-DATE
:classes UP-TO-DATE
:jar
:publishIvyJavaPublicationToIvyRepository

BUILD SUCCESSFUL

Total time: 1 secs

> gradle publish
:generateDescriptorFileForIvyJavaPublication
:compileJava UP-TO-DATE
:processResources UP-TO-DATE
:classes UP-TO-DATE
:jar
:publishIvyJavaPublicationToIvyRepository
:publish

BUILD SUCCESSFUL

Total time: 1 secs

有时候，我们需要在不发布模块到 Ivy 仓库的情况下，生成 Ivy 模块描述符文件（通常是ivy.xml）。由于描述符文件的生成是由一个单独的任务执行的，所以要实现它就很简单。
At times it is useful to generate the Ivy module descriptor file (normally ivy.xml) without publishing your module to an Ivy repository. Since descriptor file generation is performed by a separate task, this is very easy to do.

“ivy-publish”插件自动为每个注册的IvyPublication连接了一个GenerateIvyDescriptor任务。这个任务的名称基于发布内容的名称：“generateDescriptorFileFor«发布内容名称»Publication”。所以在上面的例子中，要发布的内容被命名为“IvyJava”，对应的任务则将被命名为“generateDescriptorFileForIvyJavaPublication”。
The “ivy-publish” plugin automatically wires in one GenerateIvyDescriptor task for each registered IvyPublication. This task is given a name based on the name of the publication: "generateDescriptorFileFor«NAME OF PUBLICATION»Publication". So in the example above where the publication is named "ivyJava", the task will be named "generateDescriptorFileForIvyJavaPublication".

通过设置生成任务上的 destination 属性，你可以指定生成的 Ivy 文件的位置。默认情况下，该文件会生成到 build/publications/«发布内容的名称»/ivy.xml中。
You can specify where the generated Ivy file will be located by setting the destination property on the generate task. By default this file is generated to build/publications/«NAME OF PUBLICATION»/ivy.xml.

model {
    tasks.generateDescriptorFileForIvyCustomPublication {
        destination = file("$buildDir/generated-ivy.xml")
    }
}

> gradle generateDescriptorFileForIvyCustomPublication
:generateDescriptorFileForIvyCustomPublication

BUILD SUCCESSFUL

Total time: 1 secs

以下示例演示了多项目构建的发布。每个项目都发布一个 Java 组件和一个已配置的其他源码工件，而该描述符文件自定义为包含每个项目的项目描述。
The following example demonstrates publishing with a multi-project build. Each project publishes a java component and a configured additional source artifact. The descriptor file is customized to include the project description for each project.

subprojects {
    apply plugin: 'java'
    apply plugin: 'ivy-publish'

    version = '1.0'
    group = 'org.gradle.sample'

    repositories {
        mavenCentral()
}
    }
    task sourceJar(type: Jar) {
        from sourceSets.main.java
        classifier "source"
    }
}

project(":project1") {
    description = "The first project"

    dependencies {
       compile 'junit:junit:4.11', project(':project2')
    }
}

project(":project2") {
    description = "The second project"

    dependencies {
       compile 'commons-collections:commons-collections:3.1'
    }
}

subprojects {
    publishing {
        repositories {
            ivy {
                url "${rootProject.buildDir}/repo" // change to point to your repo, e.g. http://my.org/repo
            }
        }
        publications {
            ivy(IvyPublication) {
                from components.java
                artifact(sourceJar) {
                    type "source"
                    conf "runtime"
                }
                descriptor.withXml {
                    asNode().info[0].appendNode('description', description)
                }
            }
        }
    }
}

结果是将为每个项目发表以下工件︰
The result is that the following artifacts will be published for each project:

当project1发布时，生成的模块描述符（即ivy.xml文件）将类似于……
When project1 is published, the module descriptor (i.e. the ivy.xml file) that is produced will look like…

        
<ivy-module version="2.0">
  <info organisation="org.gradle.sample" module="project1" revision="1.0" status="integration" publication="«PUBLICATION-TIME-STAMP»">
    <description>The first project</description>
  </info>
  <configurations>
    <conf name="default" visibility="public" extends="runtime"/>
    <conf name="runtime" visibility="public"/>
  </configurations>
  <publications>
    <artifact name="project1" type="jar" ext="jar" conf="runtime"/>
    <artifact name="project1" type="source" ext="jar" conf="runtime" m:classifier="source" xmlns:m="http://ant.apache.org/ivy/maven"/>
  </publications>
  <dependencies>
    <dependency org="junit" name="junit" rev="4.11" conf="runtime-&gt;default"/>
    <dependency org="org.gradle.sample" name="project2" rev="1.0" conf="runtime-&gt;default"/>
  </dependencies>
</ivy-module>

“ivy-publish”插件的功能，如上所述是不完整的，因为该功能仍然在孵化中。在即将发布的 Gradle 版本中，这个功能将扩展到包括（但不限于）：
The “ivy-publish” plugin functionality as described above is incomplete, as the feature is still incubating. Over the coming Gradle releases, the functionality will be expanded to include (but not limited to):