Added: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/single/using-repositories.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/single/using-repositories.apt?rev=425708&view=auto ============================================================================== --- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/single/using-repositories.apt (added) +++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/examples/single/using-repositories.apt Wed Jul 26 04:34:20 2006 @@ -0,0 +1,125 @@ + --- + Using Repositories + --- + Edwin Punzalan + --- + 26-July-2006 + --- + +~~ Copyright 2006 The Apache Software Foundation. +~~ +~~ 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. + +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +Assembly Plugin - Using Repositories + +* Introduction + + The Assembly Plugin allows the inclusion of needed artifacts from your local + repository to the generated archive. They are copied into the assembly in a + directory similar to what's in your remote repository, complete with metadata + and the checksums. + + This example demonstrates the creation of repository artifacts in an assembly + so that the archive can easily be used to update an internal repository with + the artifacts used by your project. + +* The Assembly Descriptor + + A functional repository archive for your project can be created with: + ++----- +<assembly> + <id>repository</id> + <formats> + <format>jar</format> + </formats> + <repositories> + <repository> + <includeMetadata>true</includeMetadata> + <outputDirectory>maven2</outputDirectory> + </repository> + </repositories> +</assembly> ++----- + + The above descriptor tells the Assembly Plugin to create a repository-like + directory structure inside the <<<maven2>>> directory from within the + generated archive. Setting <<<includeMetadata>>> to <<<true>>> will make the + plugin to also copy metadata information into the generated archive. + +* The POM + + The pom.xml for your project is very similar to how you configure the Assembly + Plugin for other distribution types. + ++----- +<project> + [...] + <build> + [...] + <plugins> + [...] + <plugin> + <artifactId>maven-assembly-plugin</artifactId> + <configuration> + <descriptors> + <descriptor>src/assemble/repository.xml</descriptor> + </descriptors> + </configuration> + </plugin> + [...] +</project> ++----- + +* Generating The Assembly Archive + + The assembly archive is then created using: + ++----- +mvn assembly:assembly ++----- + + The generated archive can be extracted to an internal repository so users of + your project can download the dependencies from it. + +* Examining the Output + + When the Maven execution completes, the archive contents should be similar to: + ++----- +target/artifactId-version-repository.jar +`-- maven2 + |-- groupId + | |-- maven-metadata.xml + | |-- maven-metadata.xml.md5 + | |-- maven-metadata.xml.sha1 + | `-- artifactId + | |-- maven-metadata.xml + | |-- maven-metadata.xml.md5 + | |-- maven-metadata.xml.sha1 + | `-- version + | |-- artifactId-version.jar + | |-- artifactId-version.jar.md5 + | |-- artifactId-version.jar.sha1 + | |-- artifactId-version.pom + | |-- artifactId-version.pom.md5 + | |-- artifactId-version.pom.sha1 + | |-- maven-metadata.xml + | |-- maven-metadata.xml.md5 + | `-- maven-metadata.xml.sha1 + `-- groupId2 + `-- [...] ++-----
Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt?rev=425708&r1=425707&r2=425708&view=diff ============================================================================== --- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt (original) +++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/features.apt Wed Jul 26 04:34:20 2006 @@ -1,13 +1,28 @@ --- - Assembly Plugin - Features + Features --- John Casey --- 12-May-2006 -Assembly Plugin - Features +~~ Copyright 2006 The Apache Software Foundation. +~~ +~~ 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. + +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/guides/mini/guide-apt-format.html -* Assembly Plugin Features +Assembly Plugin - Features <NOTE: Features with no version information have been present since the first final release of the plugin.> Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt?rev=425708&r1=425707&r2=425708&view=diff ============================================================================== --- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt (original) +++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/index.apt Wed Jul 26 04:34:20 2006 @@ -1,42 +1,129 @@ --- - Assembly Plugin - Overview + Introduction --- John Casey + Edwin Punzalan --- - 12-May-2006 + 18 July 2006 -Assembly Plugin - Overview +~~ Copyright 2006 The Apache Software Foundation. +~~ +~~ 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. -* Introduction +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/guides/mini/guide-apt-format.html - 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 +Introduction - * {{{features.html}Features}} + Do you want to create a binary distribution from a Maven project that includes + supporting scripts, configuration files, and all runtime dependencies? You + need to use the Assembly Plugin to create a distribution for your project. - * {{{examples/index.html}Examples}} + This plugin generates "assemblies". It is the equivalent of the Maven 1 + distribution plug-in. This plugin provides the capability to create binary + and source distributions. These distributions (assemblies) are defined using + an assembly descriptor. You can write your own {{{assembly.html}descriptor}} + to create a custom assembly, or you can reuse one of the three + {{{descriptor-refs.html}pre-defined assemblies}}. - * {{{usage.html}Configuration and Usage}} + Currently it can create distributions in the following formats: - * {{{advanced-configuration.html}Advanced Configuration}} <<[TODO]>> - - * {{{assembly-descriptor-howto.apt}Descriptor How-To}} <<[TODO]>> + * zip - * {{{assembly.html}Descriptor Reference}} + * tar.bz - * {{{component.html}Reusable Descriptor Component Reference}} + * tar.gz2 - [] + * jar -* XML Schema Locations + To use the Assembly Plugin in Maven 2, you simply need to: - * {{{xsd/descriptor.xsd}Assembly Descriptor}} - - * {{{xsd/component.xsd}Reusable Assembly Component}} + * choose or write an assembly descriptor to use, - [] + * configure the Assembly Plugin in your project's pom.xml, and + * run "mvn assembly:assembly" on your project. + To write your own custom assembly, you will need to refer to the + {{{assembly.html}Assembly Descriptor Format}} reference. + + +What is an Assembly? + + An "assembly" is a group of files, directories, and dependencies that is + assembled into an archive format and distributed. For example, assume that + a Maven project defines a single JAR artifact that contains both a console + application and a Swing application. Such a project could define two + "assemblies" that bundle the application with a different set of supporting + scripts and dependency sets. One assembly would be the assembly for the + console application, and the other assembly could be a Swing application + bundled with a slightly different set of dependencies. + + The Assembly Plugin provides a descriptor format which allows you to define + an arbitrary assembly of files and directories from a project. For example, + if your Maven 2 project contains the directory "src/main/bin", you can + instruct the Assembly Plugin to copy the contents of this directory to the + "bin" directory of an assembly and to change the permissions of the files in + the "bin" directory to UNIX mode 755. The parameters for configuring this + behavior are supplied to the Assembly Plugin by way of the + {{{assembly.html}assembly descriptor}}. + + +The Maven Assembly Plugin + + 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. + + +* Goals Overview + + The Assembly Plugin has six goals: + + * {{{assembly-mojo.html}assembly:assembly}} Assembles an application bundle + or distribution based on an assembly descriptor into an archive of a chosen + format. Executed from the command-line. + + * {{{attached-mojo.html}assembly:attached}} Assembles an application bundle + or distribution from an assembly descriptor into an archive of a chosen + format. Executed within the Maven Lifecycle. + + * {{{directory-mojo.html}assembly:directory}} Assembles an application bundle + from an assembly descriptor or distribution into a directory. Executed from + the command-line. + + * {{{directory-inline-mojo.html}assembly:directory-inline}} Assembles an + application bundle or distribution into a directory. Executed within the Maven + Lifecycle. + + * {{{unpack-mojo.html}assembly:unpack}} Assembles an application bundle or + distribution from an assembly descriptor into an archive of a chosen format + but with the dependencies unpacked inside the archive. + + * {{{single-mojo.html}assembly:single}} An assembly mojo created as a + work-around for lifecycle issues until addressed in the Maven 2.1 release. + + +* Examples + + To provide you with better understanding on some usages of the Assembly + Plugin, you can take a look into the examples which can be found + {{{examples/index.html}here}}. Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt?rev=425708&r1=425707&r2=425708&view=diff ============================================================================== --- maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt (original) +++ maven/plugins/trunk/maven-assembly-plugin/src/site/apt/usage.apt Wed Jul 26 04:34:20 2006 @@ -1,10 +1,27 @@ --- - Assembly Plugin - Configuration and Usage + Configuration and Usage --- John Casey --- 12-May-2006 +~~ Copyright 2006 The Apache Software Foundation. +~~ +~~ 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. + +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/guides/mini/guide-apt-format.html + Assembly Plugin - Configuration and Usage * Introduction @@ -14,19 +31,19 @@ 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 + 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 + 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 + advantage of one of the Assembly Plugin's prefabricated descriptors, as follows: +---+ @@ -49,12 +66,14 @@ </project> +---+ - Note that the assembly plugin allows you to specify multiple + 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: + Alternatively, 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> @@ -63,9 +82,6 @@ [...] <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> @@ -81,7 +97,7 @@ <<<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 + in the Assembly Plugin. For more information, see the {{{examples/index.html}examples section}} or the {{{plugin-info.html}plugin parameter documentation}}. @@ -93,7 +109,7 @@ 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 + 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. @@ -105,7 +121,7 @@ <<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 + phase. Because many assemblies will contain 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 @@ -172,7 +188,7 @@ 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 + 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 @@ -302,12 +318,12 @@ * Advanced Configuration - As you've no doubt noticed, the assembly plugin can be a very useful way to + 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 + 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 @@ -344,7 +360,7 @@ Main-Class: org.sample.App +---+ - For more information on advanced configuration for the assembly plugin, see + For more information on advanced configuration for the Assembly Plugin, see the {{{#resources}Resources}} section. ** GOTCHA! @@ -353,16 +369,16 @@ <<<directory-inline>>> - <<do not>> support the <<<\<archive\>>>> configuration element. -* {resources}Resources +* {Resources} [[1]] For more information on writing your own assembly descriptor, read the - {{{assembly-descriptor-howto.apt}Assembly Descriptor How-To}} + {{{assembly.html}Assembly Descriptor}} - [[2]] For more information about the <<<maven-jar-plugin>>>, - {{{/plugins/maven-jar-plugin}look here}}. + [[2]] For more information about the <<<maven-jar-plugin>>>, look + {{{/plugins/maven-jar-plugin}here}}. [[3]] For more information on advanced <<<maven-assembly-plugin>>> - configuration, {{{advanced-configuration.html}look here}}. + configuration, see the {{{examples/index.html}examples}}. [] Added: maven/plugins/trunk/maven-assembly-plugin/src/site/fml/faq.fml URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/fml/faq.fml?rev=425708&view=auto ============================================================================== --- maven/plugins/trunk/maven-assembly-plugin/src/site/fml/faq.fml (added) +++ maven/plugins/trunk/maven-assembly-plugin/src/site/fml/faq.fml Wed Jul 26 04:34:20 2006 @@ -0,0 +1,34 @@ +<?xml version="1.0"?> + +<!-- + ~ Copyright 2006 The Apache Software Foundation. + ~ + ~ 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. + --> + +<faqs id="FAQ" title="Frequently Asked Questions"> + <part id="General"> + <faq id="deploy"> + <question>If the Assembly Plugin is ran during the package phase, do my assemblies get deployed during the deploy phase?</question> + <answer> + <p>Yes. The assemblies created by the Assembly Plugin is attached to your project so it gets deployed too.</p> + </answer> + </faq> + <faq id="classifier"> + <question>Can I use an artifact created by the assembly plugin as a dependency?</question> + <answer> + <p>Yes. You can refer to it using the id of the assembly as the dependency classifier.</p> + </answer> + </faq> + </part> +</faqs> Modified: maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml URL: http://svn.apache.org/viewvc/maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml?rev=425708&r1=425707&r2=425708&view=diff ============================================================================== --- maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml (original) +++ maven/plugins/trunk/maven-assembly-plugin/src/site/site.xml Wed Jul 26 04:34:20 2006 @@ -1,22 +1,20 @@ <?xml version="1.0" encoding="ISO-8859-1"?> <!-- -/* - * Copyright 2001-2005 The Apache Software Foundation. - * - * 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. - */ ---> + ~ Copyright 2006 The Apache Software Foundation. + ~ + ~ 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. + --> <project name="Maven Assembly Plugin"> <bannerLeft> @@ -33,12 +31,29 @@ </links> <menu name="Overview"> - <item name="Introduction" href="introduction.html"/> - <item name="How to Use" href="howto.html"/> - <item name="Examples" href="examples/index.html"/> + <item name="Introduction" href="index.html"/> + <item name="Usage" href="usage.html"/> + <item name="Features" href="features.html"/> <item name="Descriptor Format" href="assembly.html"/> + <item name="Component Format" href="component.html"/> <item name="Predefined Descriptors" href="descriptor-refs.html"/> + <item name="FAQ" href="faq.html"/> </menu> + + <menu name="Examples"> + <item name="Examples Index" href="examples/index.html"/> + <item name="Single Projects" collapse="false" href="examples/simple/index.html"> + <item name="Filtering Some Distribution Files" href="examples/simple/filtering-some-distribution-files.html"/> + <item name="Using Component Descriptors" href="examples/simple/using-components.html"/> + <item name="Using Repositories" href="examples/simple/using-repositories.html"/> + </item> + <item name="Multimodule Projects" collapse="false" href="examples/multimodule/index.html"> + <item name="Include Module Artifacts" href="examples/multimodule/module-binary-inclusion-simple.html"/> + <item name="Include Module Sources" href="examples/multimodule/module-source-inclusion-simple.html"/> + </item> + </menu> + ${reports} + </body> </project>
