You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by jd...@apache.org on 2006/05/15 17:13:35 UTC
svn commit: r406650 - in /maven/plugins/trunk/maven-assembly-plugin: pom.xml
src/main/mdo/descriptor.mdo src/site/apt/descriptor-refs.apt
src/site/apt/descriptor.apt src/site/apt/features.apt
src/site/apt/index.apt src/site/apt/usage.apt
Author: jdcasey
Date: Mon May 15 08:13:33 2006
New Revision: 406650
URL: http://svn.apache.org/viewcvs?rev=406650&view=rev
Log:
Adding documentation...not quite ready to publish yet.
Added:
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/descriptor-refs.apt
- copied unchanged from r406638, maven/plugins/trunk/maven-assembly-plugin/src/site/apt/descriptor.apt
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt (with props)
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt (with props)
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt (with props)
Removed:
maven/plugins/trunk/maven-assembly-plugin/src/site/apt/descriptor.apt
Modified:
maven/plugins/trunk/maven-assembly-plugin/pom.xml
maven/plugins/trunk/maven-assembly-plugin/src/main/mdo/descriptor.mdo
Modified: maven/plugins/trunk/maven-assembly-plugin/pom.xml
URL: http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-assembly-plugin/pom.xml?rev=406650&r1=406649&r2=406650&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/pom.xml (original)
+++ maven/plugins/trunk/maven-assembly-plugin/pom.xml Mon May 15 08:13:33 2006
@@ -43,6 +43,30 @@
<version>1.0.0</version>
</configuration>
</execution>
+ <execution>
+ <id>descriptor-site</id>
+ <phase>pre-site</phase>
+ <goals>
+ <goal>xdoc</goal>
+ <goal>xsd</goal>
+ </goals>
+ <configuration>
+ <model>src/main/mdo/descriptor.mdo</model>
+ <version>1.0.0</version>
+ </configuration>
+ </execution>
+ <execution>
+ <id>component-site</id>
+ <phase>pre-site</phase>
+ <goals>
+ <goal>xdoc</goal>
+ <goal>xsd</goal>
+ </goals>
+ <configuration>
+ <model>src/main/mdo/component.mdo</model>
+ <version>1.0.0</version>
+ </configuration>
+ </execution>
</executions>
</plugin>
</plugins>
Modified: maven/plugins/trunk/maven-assembly-plugin/src/main/mdo/descriptor.mdo
URL: http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-assembly-plugin/src/main/mdo/descriptor.mdo?rev=406650&r1=406649&r2=406650&view=diff
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/main/mdo/descriptor.mdo (original)
+++ maven/plugins/trunk/maven-assembly-plugin/src/main/mdo/descriptor.mdo Mon May 15 08:13:33 2006
@@ -404,8 +404,10 @@
<name>includes</name>
<version>1.0.0</version>
<description>
- This is a list of <include> elements, each containing a module reference of the type groupId:artifactId.
+ <![CDATA[
+ This is a list of <include/> elements, each containing a module reference of the type groupId:artifactId.
Modules matching these elements will be included in this set.
+ ]]>
</description>
<association>
<type>String</type>
@@ -416,8 +418,10 @@
<name>excludes</name>
<version>1.0.0</version>
<description>
- This is a list of <exclude> elements, each containing a module reference of the type groupId:artifactId.
+ <![CDATA[
+ This is a list of <exclude/> elements, each containing a module reference of the type groupId:artifactId.
Modules matching these elements will be excluded from this set.
+ ]]>
</description>
<association>
<type>String</type>
Added: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt
URL: http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt?rev=406650&view=auto
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt (added)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt Mon May 15 08:13:33 2006
@@ -0,0 +1,45 @@
+ ---
+ Assembly Plugin - Features
+ ---
+ John Casey
+ ---
+ 12-May-2006
+
+Assembly Plugin - Features
+
+* Assembly Plugin Features
+
+ <NOTE: Features with no version information have been present since the first final release of the plugin.>
+
+ * Inclusion of dependencies, modules <[2.1]>, file-sets, and individual files
+
+ * Inclusion of project website documentation <[2.1]>
+
+ * Flexible directory structures for assembly elements
+
+ * All assembly inclusions controlled by include/exclude pattern sets
+
+ * Option to unpack artifact files into the assembly
+
+ * Project modules can be included as source files or in binary form <[2.1]>
+
+ * Reusable assembly-descriptor components <[2.1]>
+
+ * Supported archive formats include: tar.gz, tar.bz2, zip, jar
+
+ * Directory-only assemblies
+
+ * Filtering and line-ending conversion for file-sets and individual files
+
+ * Directory and file attributes (<modes>) <[2.1]>
+
+ * Artifact filename mapping with expression support <[2.1]>
+
+ * Descriptor interpolation using current project and other assembly descriptor information <[2.1]>
+
+ * Embedded Maven repository creation with artifact version alignment <[2.1]>
+
+ * Security / signature information stripped from embedded artifacts prior to inclusion <[2.1]>
+
+ []
+
Propchange: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Added: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt
URL: http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt?rev=406650&view=auto
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt (added)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt Mon May 15 08:13:33 2006
@@ -0,0 +1,42 @@
+ ---
+ Assembly Plugin - Overview
+ ---
+ John Casey
+ ---
+ 12-May-2006
+
+Assembly Plugin - Overview
+
+* Introduction
+
+ The assembly plugin for Maven 2.0 is primarily intended to allow users to aggregate the project output along with its dependencies, modules, site documentation, and other files into a single distributable archive.
+
+ Your project build can build distribution assemblies easily, using one of the convenient, prefabricated assembly descriptors. These descriptors handle many common operations, such as packaging a project's artifact along with its dependencies in a single jar. Alternatively, your project can provide its own descriptor and assume a much higher level of control over how dependencies, modules, file-sets, and individual files are packaged in the assembly.
+
+* Table of Contents
+
+ * {{{features.html}Features}}
+
+ * {{{examples/index.html}Examples}}
+
+ * {{{usage.html}Configuration and Usage}}
+
+ * {{{advanced-configuration.html}Advanced Configuration}} <<[TODO]>>
+
+ * {{{assembly-descriptor-howto.apt}Descriptor How-To}} <<[TODO]>>
+
+ * {{{assembly.html}Descriptor Reference}}
+
+ * {{{component.html}Reusable Descriptor Component Reference}}
+
+ []
+
+* XML Schema Locations
+
+ * {{{xsd/descriptor.xsd}Assembly Descriptor}}
+
+ * {{{xsd/component.xsd}Reusable Assembly Component}}
+
+ []
+
+
Propchange: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"
Added: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt
URL: http://svn.apache.org/viewcvs/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt?rev=406650&view=auto
==============================================================================
--- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt (added)
+++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt Mon May 15 08:13:33 2006
@@ -0,0 +1,369 @@
+ ---
+ Assembly Plugin - Configuration and Usage
+ ---
+ John Casey
+ ---
+ 12-May-2006
+
+Assembly Plugin - Configuration and Usage
+
+* Introduction
+
+ This document is intended to provide instructions for using the
+ maven-assembly-plugin. In order for this discussion to be useful, it's
+ critical to cover two topics: configuration of the plugin - both inside the
+ POM and, where possible, from the command line - and the different execution
+ styles. For the sake of clarity, we'll cover configuration before execution.
+
+* Configuring the Assembly Plugin
+
+ Getting started with the assembly plugin is pretty simple. If you're using one
+ of the prefabricated assembly descriptors, you just tell it which one; if
+ you're using a custom assembly descriptor, you give it the path to the
+ descriptor. Note that a single invocation of the assembly plugin can actually
+ produce assemblies from multiple descriptors, allowing you maximum flexibility
+ to customize the suite of binaries your project produces.
+
+ For example, imagine that our project produces a jar. If we want to create an
+ assembly binary that includes our project's dependencies, we can take
+ advantage of one of the assembly plugin's prefabricated descriptors, as
+ follows:
+
++---+
+<project>
+ [...]
+ <build>
+ [...]
+ <plugins>
+ <plugin>
+ <!-- NOTE: We don't need a groupId specification because the group is
+ org.apache.maven.plugins ...which is assumed by default.
+ -->
+ <artifactId>maven-assembly-plugin</artifactId>
+ <configuration>
+ <descriptorRefs>
+ <descriptorRef>jar-with-dependencies</descriptorRef>
+ </descriptorRefs>
+ </configuration>
+ [...]
+</project>
++---+
+
+ Note that the assembly plugin allows you to specify multiple
+ <<<descriptorRefs>>> at once, to produce multiple types of assemblies in a
+ single invocation.
+
+ Alternatively, if we've created a custom assembly descriptor called
+ <<<src.xml>>> in the <<<src/assembly>>> directory (see the {{{#resources}Resources}} section for more information), we can tell the assembly plugin to use it instead:
+
++---+
+<project>
+ [...]
+ <build>
+ [...]
+ <plugins>
+ <plugin>
+ <!-- NOTE: We don't need a groupId specification because the group is
+ org.apache.maven.plugins ...which is assumed by default.
+ -->
+ <artifactId>maven-assembly-plugin</artifactId>
+ <configuration>
+ <descriptors>
+ <descriptor>src/assembly/src.xml</descriptor>
+ </descriptors>
+ </configuration>
+ [...]
+</project>
++---+
+
+ Again, note that we could specify multiple custom assembly descriptors here.
+ Additionally, it's possible to specify a mixture of <<<descriptors>>> and
+ <<<descriptorRefs>>> within the same configuration.
+
+ <<NOTE:>> Many other configuration options are available for the various mojos
+ in the assembly plugin. For more information, see the
+ {{{examples/index.html}examples section}} or the {{{plugin-info.html}plugin
+ parameter documentation}}.
+
+* Executing: Building an Assembly
+
+ Once you've configured the various <<<descriptors>>> and <<<descriptorRefs>>>
+ for the assemblies you want the project to produce, it's time to determine how
+ you want to build them.
+
+ Currently, there are two basic approaches to building assemblies: as a
+ dedicated build action, or bound to a phase of the normal build lifecycle.
+ Beyond this, it's also possible to have the assembly plugin simply create an
+ assembly directory for any given <<<descriptor>>> or <<<descriptorRef>>>,
+ instead of creating archives.
+
+** Building an Assembly as a Standalone Process
+
+ First, let's examine how we can build an assembly directly, as a process
+ separate from the normal build lifecycle. In this case, assemblies won't be
+ produced when the normal build is executed, only in special circumstances.
+
+ <<NOTE:>> Invoking the <<<assembly>>> and <<<directory>>> mojos will cause
+ Maven to build the project using the normal lifecycle, up to the <<<package>>>
+ phase. Because many assemblies will contains compiled classes and other
+ binaries, it's reasonable to assume that the package phase will be required to
+ ensure those binaries exist and have been tested. The main advantage of
+ producing an assembly in this way is to avoid producing it as part of your
+ normal build process. In some cases, you may only want to create an assembly
+ periodically; these mojos provide two ways to accomplish that goal.
+
+*** Normal Assemblies
+
+ You can build an assembly directly by executing:
+
++---+
+mvn assembly:assembly
++---+
+
+ When this build completes, you should see a file in the target directory with
+ a name similar to the following:
+
++---+
+target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar
++---+
+
+ Notice the artifact classifier, between the end of the version and the
+ beginning of the file extension, <<<jar-with-dependencies>>>. This is the
+ <<<id>>> of the assembly descriptor used to create this artifact.
+
+*** Assembly Directories
+
+ You can construct an assembly directory directly from the command line by
+ executing:
+
++---+
+mvn assembly:directory
++---+
+
+ When completed, you should see a directory structure similar to this:
+
++---+
+target
+|-- sample-1.0-SNAPSHOT-jar-with-dependencies
+| |-- META-INF
+| | |-- MANIFEST.MF
+| | `-- maven
+| | `-- org.sample
+| | `-- sample
+| | |-- pom.properties
+| | `-- pom.xml
+| |-- junit
+[...]
+| | `-- TestRunner.class
+| |-- junit3.8.1
+| |-- org
+| | `-- sample
+| | `-- App.class
+| `-- stylesheet.css
++---+
+
+** Building an Assembly as Part of the Build Lifecycle
+
+ If you need to ensure that assemblies are produced whenever your project
+ builds, or when a particular profile is activated (also useful for configuring
+ other plugins during this special process), then the following two mojos are
+ probably what you're looking for. The <<<attached>>> and
+ <<<directory-inline>>> mojos are functional counterparts of the mojos
+ discussed above, except that they are meant to bind into the default build
+ lifecycle.
+
+ The <<<assembly>>> mojo forces a <<<package>>>-phase build to execute, in
+ order to guarantee the availability of project binaries. Unfortunately, this
+ currently means that binding the <<<assembly>>> mojo to the default lifecycle
+ will cause Maven to execute the build twice - once for the main process, and
+ once again in a forked lifecycle which is spawned by the <<<assembly>>> mojo
+ itself.
+
+ By contrast, the <<<attached>>> mojo assumes that the build has already
+ produced project binaries or whatever else it needs prior to building the
+ assembly itself. Because they depend on correct binding to the lifecycle in
+ order to gain access to the files required by your project assembly, the
+ <<<attached>>> and <<<directory-inline>>> mojos require the user to have much
+ more intimate knowledge of the build process.
+
+*** Normal Assemblies
+
+ To bind the <<<attached>>> mojo to a project's build lifecycle, you can add
+ this configuration (assuming you're using the <<<jar-with-dependencies>>>
+ prefabricated descriptor):
+
++---+
+<project>
+ [...]
+ <build>
+ [...]
+ <plugins>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <configuration>
+ <descriptorRefs>
+ <descriptorRef>jar-with-dependencies</descriptorRef>
+ </descriptorRefs>
+ </configuration>
+ <executions>
+ <execution>
+ <id>make-assembly</id> <!-- this is used for inheritance merges -->
+ <phase>packaging</phase> <!-- append to the packaging phase. -->
+ <goals>
+ <goal>attached</goal> <!-- goals == mojos -->
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ [...]
+</project>
++---+
+
+ Then, to create a project assembly, simple execute the normal <<<package>>>
+ phase from the default lifecycle:
+
++---+
+mvn package
++---+
+
+ When this build completes, you should see a file in the target directory with
+ a name similar to the following:
+
++---+
+target/sample-1.0-SNAPSHOT-jar-with-dependencies.jar
++---+
+
+ Notice the artifact classifier, between the end of the version and the
+ beginning of the file extension, <<<jar-with-dependencies>>>. This is the
+ <<<id>>> of the assembly descriptor used to create this artifact.
+
+*** Assembly Directories
+
+ If instead you want to bind the <<<directory-inline>>> mojo to a project's
+ build lifecycle - so you can construct a directory containing your assembly -
+ you can add this configuration (assuming you're using the
+ <<<jar-with-dependencies>>> prefabricated descriptor):
+
++---+
+<project>
+ [...]
+ <build>
+ [...]
+ <plugins>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <configuration>
+ <descriptorRefs>
+ <descriptorRef>jar-with-dependencies</descriptorRef>
+ </descriptorRefs>
+ </configuration>
+ <executions>
+ <execution>
+ <id>make-assembly</id> <!-- this is used for inheritance merges -->
+ <phase>packaging</phase> <!-- append to the packaging phase. -->
+ <goals>
+ <goal>directory-inline</goal> <!-- goals == mojos -->
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ [...]
+</project>
++---+
+
+ Then, to create a project assembly, simple execute the normal <<<package>>>
+ phase from the default lifecycle:
+
++---+
+mvn package
++---+
+
+ When completed, you should see a directory structure similar to this:
+
++---+
+target
+|-- sample-1.0-SNAPSHOT-jar-with-dependencies
+| |-- META-INF
+| | |-- MANIFEST.MF
+| | `-- maven
+| | `-- org.sample
+| | `-- sample
+| | |-- pom.properties
+| | `-- pom.xml
+| |-- junit
+[...]
+| | `-- TestRunner.class
+| |-- junit3.8.1
+| |-- org
+| | `-- sample
+| | `-- App.class
+| `-- stylesheet.css
++---+
+
+* Advanced Configuration
+
+ As you've no doubt noticed, the assembly plugin can be a very useful way to
+ create a self-contained binary artifact for your project, among many other
+ things. However, once you've created this self-contained jar, you will
+ probably want the ability to execute it using the <<<-jar>>> JVM switch.
+
+ To accommodate this, the assembly plugin supports configuration of an
+ <<<\<archive\>>>> element which is identical to that supported by the
+ <<<maven-jar-plugin>>> (see {{{#resources}Resources}}). Using this
+ configuration, it's easy to configure the <<<Main-Class>>> attribute of the
+ jar manifest:
+
++---+
+<project>
+ [...]
+ <build>
+ [...]
+ <plugins>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <configuration>
+ [...]
+ <archive>
+ <manifest>
+ <mainClass>org.sample.App</mainClass>
+ </manifest>
+ </archive>
+ </configuration>
+ [...]
+ </plugin>
+ [...]
+</project>
++---+
+
+ If we add this configuration to the <<<attached>>> mojo example above and
+ rebuild, we will see an entry like this in the META-INF/MANIFEST.MF file of
+ the resulting jar:
+
++---+
+[...]
+Main-Class: org.sample.App
++---+
+
+ For more information on advanced configuration for the assembly plugin, see
+ the {{{#resources}Resources}} section.
+
+** GOTCHA!
+
+ At this point, the directory-oriented mojos - <<<directory>>> and
+ <<<directory-inline>>> - <<do not>> support the <<<\<archive\>>>>
+ configuration element.
+
+* {resources}Resources
+
+ [[1]] For more information on writing your own assembly descriptor, read the
+ {{{assembly-descriptor-howto.apt}Assembly Descriptor How-To}}
+
+ [[2]] For more information about the <<<maven-jar-plugin>>>,
+ {{{/plugins/maven-jar-plugin}look here}}.
+
+ [[3]] For more information on advanced <<<maven-assembly-plugin>>>
+ configuration, {{{advanced-configuration.html}look here}}.
+
+ []
+
+
Propchange: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt
------------------------------------------------------------------------------
svn:keywords = "Author Date Id Revision"