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 &lt;include&gt; 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 &lt;exclude&gt; 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"