/*
* Copyright 2012 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.
*/
package org.gradle.api.publish.ivy;
import org.gradle.api.Action;
import org.gradle.api.Incubating;
import org.gradle.api.component.SoftwareComponent;
import org.gradle.internal.HasInternalProtocol;
import org.gradle.api.publish.Publication;
/**
* A {@code IvyPublication} is the representation/configuration of how Gradle should publish something in Ivy format, to an Ivy repository.
*
* You directly add a named Ivy Publication the project's {@code publishing.publications} container by providing {@link IvyPublication} as the type.
* <pre>
* publishing {
* publications {
* myPublicationName(IvyPublication) {
* // Configure the publication here
* }
* }
* }
* </pre>
*
* <p>
* The Ivy module identifying attributes of the publication are mapped as follows:
* <ul>
* <li>{@code module} - {@code project.name}</li>
* <li>{@code organisation} - {@code project.group}</li>
* <li>{@code revision} - {@code project.version}</li>
* <li>{@code status} - {@code project.status}</li>
* </ul>
* </p>
*
* <p>
* For certain common use cases, it's often sufficient to specify the component to publish, using ({@link #from(org.gradle.api.component.SoftwareComponent)}.
* The published component is used to determine which artifacts to publish, and which configurations and dependencies should be listed in the generated ivy descriptor file.
* </p><p>
* You can add configurations to the generated ivy descriptor file, by supplying a Closure to the {@link #configurations(org.gradle.api.Action)} method.
* </p><p>
* To add additional artifacts to the set published, use the {@link #artifact(Object)} and {@link #artifact(Object, org.gradle.api.Action)} methods.
* You can also completely replace the set of published artifacts using {@link #setArtifacts(Iterable)}.
* Together, these methods give you full control over the artifacts to be published.
* </p><p>
* For any other tweaks to the publication, it is possible to modify the generated Ivy descriptor file prior to publication. This is done using
* the {@link IvyModuleDescriptorSpec#withXml(org.gradle.api.Action)} method, normally via a Closure passed to the {@link #descriptor(org.gradle.api.Action)} method.
* </p>
* <h4>Example of publishing a java component with an added source jar and custom module description</h4>
*
* <pre autoTested="true">
* apply plugin: "java"
* apply plugin: "ivy-publish"
*
* task sourceJar(type: Jar) {
* from sourceSets.main.allJava
* }
*
* publishing {
* publications {
* myPublication(IvyPublication) {
* from components.java
* artifact(sourceJar) {
* type "source"
* extension "src.jar"
* conf "runtime"
* }
* descriptor.withXml {
* asNode().info[0].appendNode("description", "custom-description")
* }
* }
* }
* }
* </pre>
*
* @since 1.3
*/
@Incubating
@HasInternalProtocol
public interface IvyPublication extends Publication {
/**
* The module descriptor that will be published.
* <p>
*
* @return The module descriptor that will be published.
*/
IvyModuleDescriptorSpec getDescriptor();
/**
* Configures the descriptor that will be published.
* <p>
* The descriptor XML can be modified by using the {@link IvyModuleDescriptorSpec#withXml(org.gradle.api.Action)} method.
*
* @param configure The configuration action.
*/
void descriptor(Action<? super IvyModuleDescriptorSpec> configure);
/**
* Provides the software component that should be published.
*
* <ul>
* <li>Any artifacts declared by the component will be included in the publication.</li>
* <li>The dependencies declared by the component will be included in the published meta-data.</li>
* </ul>
*
* Currently 2 types of component are supported: 'components.java' (added by the JavaPlugin) and 'components.web' (added by the WarPlugin).
* For any individual IvyPublication, only a single component can be provided in this way.
*
* The following example demonstrates how to publish the 'java' component to a ivy repository.
* <pre autoTested="true">
* apply plugin: "java"
* apply plugin: "ivy-publish"
*
* publishing {
* publications {
* ivy(IvyPublication) {
* from components.java
* }
* }
* }
* </pre>
*
* @param component The software component to publish.
*/
void from(SoftwareComponent component);
/**
* Defines some {@link IvyConfiguration}s that should be included in the published ivy module descriptor file.
*
* The following example demonstrates how to add a "testCompile" configuration, and a "testRuntime" configuration that extends it.
* <pre autoTested="true">
* apply plugin: "java"
* apply plugin: "ivy-publish"
*
* publishing {
* publications {
* ivy(IvyPublication) {
* configurations {
* testCompile {}
* testRuntime {
* extend "testCompile"
* }
* }
* }
* }
* }
* </pre>
*
* @param config An action or closure to configure the values of the constructed {@link IvyConfiguration}.
*/
void configurations(Action<? super IvyConfigurationContainer> config);
/**
* Returns the complete set of configurations for this publication.
* @return the configurations
*/
IvyConfigurationContainer getConfigurations();
/**
* Creates a custom {@link IvyArtifact} to be included in the publication.
*
* The <code>artifact</code> method can take a variety of input:
* <ul>
* <li>A {@link org.gradle.api.artifacts.PublishArtifact} instance. Name, type, extension and classifier values are taken from the supplied instance.</li>
* <li>An {@link org.gradle.api.tasks.bundling.AbstractArchiveTask} instance. Name, type, extension and classifier values are taken from the supplied instance.</li>
* <li>Anything that can be resolved to a {@link java.io.File} via the {@link org.gradle.api.Project#file(Object)} method.
* Name, extension and classifier values are interpolated from the file name.</li>
* <li>A {@link java.util.Map} that contains a 'source' entry that can be resolved as any of the other input types, including file.
* This map can contain additional attributes to further configure the constructed artifact.</li>
* </ul>
*
* The following example demonstrates the addition of various custom artifacts.
* <pre autoTested="true">
* apply plugin: "ivy-publish"
*
* task sourceJar(type: Jar) {
* classifier "source"
* }
*
* task genDocs {
* doLast {
* // Generate 'my-docs-file.htm'
* }
* }
*
* publishing {
* publications {
* ivy(IvyPublication) {
* artifact sourceJar // Publish the output of the sourceJar task
* artifact 'my-file-name.jar' // Publish a file created outside of the build
* artifact source: 'my-docs-file.htm', classifier: 'docs', extension: 'html', builtBy: genDocs // Publish a file generated by the 'genDocs' task
* }
* }
* }
* </pre>
*
* @param source The source of the artifact content.
*/
IvyArtifact artifact(Object source);
/**
* Creates an {@link IvyArtifact} to be included in the publication, which is configured by the associated action.
*
* The first parameter is used to create a custom artifact and add it to the publication, as per {@link #artifact(Object)}.
* The created {@link IvyArtifact} is then configured using the supplied action.
* This method also accepts the configure action as a closure argument, by type coercion.
*
* <pre autoTested="true">
* apply plugin: "ivy-publish"
*
* task sourceJar(type: Jar) {
* classifier "source"
* }
* task genDocs {
* doLast {
* // Generate 'my-docs-file.htm'
* }
* }
*
* publishing {
* publications {
* ivy(IvyPublication) {
* artifact(sourceJar) {
* // These values will be used instead of the values from the task. The task values will not be updated.
* classifier "src"
* extension "zip"
* conf "runtime->default"
* }
* artifact("my-docs-file.htm") {
* type "documentation"
* extension "html"
* builtBy genDocs
* }
* }
* }
* }
* </pre>
*
* @param source The source of the artifact.
* @param config An action to configure the values of the constructed {@link IvyArtifact}.
*/
IvyArtifact artifact(Object source, Action<? super IvyArtifact> config);
/**
* The complete set of artifacts for this publication.
*
* <p>
* Setting this property will clear any previously added artifacts and create artifacts from the specified sources.
* Each supplied source is interpreted as per {@link #artifact(Object)}.
*
* For example, to exclude the dependencies declared by a component and instead use a custom set of artifacts:
* <pre autoTested="true">
* apply plugin: "java"
* apply plugin: "ivy-publish"
*
* task sourceJar(type: Jar) {
* classifier "source"
* }
*
* publishing {
* publications {
* ivy(IvyPublication) {
* from components.java
* artifacts = ["my-custom-jar.jar", sourceJar]
* }
* }
* }
* </pre>
*
* @return the artifacts.
*/
IvyArtifactSet getArtifacts();
/**
* Sets the artifacts for this publication. Each supplied value is interpreted as per {@link #artifact(Object)}.
*
* @param sources The set of artifacts for this publication.
*/
void setArtifacts(Iterable<?> sources);
/**
* Returns the organisation for this publication.
*/
String getOrganisation();
/**
* Sets the organisation for this publication.
*/
void setOrganisation(String organisation);
/**
* Returns the module for this publication.
*/
String getModule();
/**
* Sets the module for this publication.
*/
void setModule(String module);
/**
* Returns the revision for this publication.
*/
String getRevision();
/**
* Sets the revision for this publication.
*/
void setRevision(String revision);
}