diff --git a/src/site/markdown/advanced-descriptor-topics.md.vm b/src/site/markdown/advanced-descriptor-topics.md.vm index f3ff71b8..c5082120 100644 --- a/src/site/markdown/advanced-descriptor-topics.md.vm +++ b/src/site/markdown/advanced-descriptor-topics.md.vm @@ -26,39 +26,48 @@ under the License. # Advanced Assembly-Descriptor Topics -Quick Note on All `includes` and `excludes` Patterns ----------------------------------------------------- +## Quick Note on All `includes` and `excludes` Patterns `excludes` take priority over `includes`. -Archive file resolution ------------------------ +## Archive file resolution -If two or more elements (e.g., file, fileSet) select different sources for the same file for archiving, only one of the source files will be archived. +If two or more elements (for example, file, fileSet) select different sources for the same file for archiving, only one of the source files will be archived. -As per version 2.5.2 of the assembly plugin, the first phase to add the file to the archive "wins". The filtering is done solely based on name inside the archive, so the same source file can be added under different output names. The order of the phases is as follows: 1) FileItem 2) FileSets 3) ModuleSet 4) DepenedencySet. +As of version 2.5.2 of the assembly plugin, the first phase to add the file to the archive "wins". +The filtering is done solely based on name inside the archive, so the same source file can be added under different output names. +The order of the phases is as follows: -Elements of the same type will be processed in the order they appear in the descriptors. If you need to "overwrite" a file included by a previous set, the only way to do this is to exclude that file from the earlier set. +1. FileItem +2. FileSets +3. ModuleSet +4. DependencySet. -Note that this behaviour was slightly different in earlier versions of the assembly plugin. +Elements of the same type are processed in the order they appear in the descriptors. +If you need to overwrite a file included by a previous set, exclude that file from the earlier set. -Advanced Artifact-Matching in `includes` and `excludes` -------------------------------------------------------- +This behavior was different in earlier versions of the assembly plugin. -When using `dependencySet` or `moduleSet`, the `` and `` sections actually apply to artifacts, not filenames. This can be a good thing, since you don't have to know the artifact's filename in the local repository. However, explicitly specifying the full artifact ID (consisting of groupId, artifactId, version, type, and classifier) for each artifact to be included or excluded can lead to very a verbose descriptor. Starting with version 2.2, the assembly plugin addresses the clumsiness of explicit artifact identification through the use of wildcard patterns. +## Advanced Artifact-Matching in `includes` and `excludes` -The following easy rules should be applied when specifying artifact-matching patterns: +When using `dependencySet` or `moduleSet`, the `` and `` sections apply to artifacts, not filenames. +You do not have to know the artifact's filename in the local repository. However, explicitly specifying the full artifact ID +(consisting of groupId, artifactId, version, type, and classifier) for each artifact to be included or excluded can lead to a verbose descriptor. +Starting with version 2.2, the assembly plugin addresses this issue through the use of wildcard patterns. + +Apply these rules when specifying artifact-matching patterns: 1. Artifacts are matched by a set of identifier strings. In the following strings, `type` is `'jar'` by default, and `classifier` is omitted if null. - `groupId:artifactId:type:classifier` ( `artifact.getDependencyConflictId()` ) - `groupId:artifactId` ( `ArtifactUtils.versionlessKey( artifact )` ) - `groupId:artifactId:type:classifier:version` ( `artifact.getId()` ) -1. Any `'*'` character in an include/exclude pattern will result in the pattern being split, and the sub-patterns being matched within the three artifact identifiers mentioned above, using `String.indexOf(..)`. +1. Any `'*'` character in an include/exclude pattern will result in the pattern split. The sub-patterns are matched within the three artifact identifiers mentioned above, using `String.indexOf(..)`. 1. When no `'*'` is present in an include/exclude pattern, the pattern will only match if the **entire** pattern equals one of the three artifact identifiers above, using the `String.equals(..)` method. -1. In case you missed it above, artifact-identification fields are separated by colons (`':'`) in the matching strings. So, a wildcard pattern that matches any artifact of type `'war'` might be specified as `*:war`. +1. Artifact-identification fields are separated by colons (`':'`) in the matching strings. So, a wildcard pattern that matches any artifact of type `'war'` might be specified as `*:war`. + #[[### Example: Include all dependencies of type `'war'`]]# -In this example, we'll configure a `dependencySet` so it only includes those `war` dependencies. +In this example, we configure a `dependencySet` so it only includes those `war` dependencies. ```xml ``` -Including Subversion Metadata Directories in a FileSet ------------------------------------------------------- +## Including Subversion Metadata Directories in a FileSet -For most use cases, it's important to avoid adding metadata files from your source-control system, such as Subversion's `.svn` directories. Such metadata can increase the size of the resulting assembly vastly. By default, the assembly plugin will exclude metadata files for most common source-control systems from the `fileSet`s specified in the descriptor. +In most cases, it is important to avoid adding metadata files from the source-control system, such as Subversion's `.svn` directories. +Such metadata can increase the size of the resulting assembly. By default, the assembly plugin excludes metadata files for most common source-control systems +from the `fileSet`s specified in the descriptor. -On the other hand, what if you _wanted_ to include Subversion metadata directories? Starting with version 2.2, the assembly plugin offers the `useDefaultExcludes` option on all `fileSet` elements, in order to accommodate this use case. +If you want to include Subversion metadata directories, use the `useDefaultExcludes` option on all `fileSet` elements. #[[### Example: Bundle project sources for a developer-quickstart pack]]# -In this example, let's examine what happens if you have a large project in source control. This project contains a large number of sizable files that haven't changed since the day they were added, in the early stages of the project's lifetime. You want to enable potential developers to get started quickly, without checking out hundreds of 10-megabyte files first. +In this example, consider what happens if you have a large project in source control. +This project contains a large number of sizable files that have not changed since the day they were added. +You want to enable developers to get started quickly, without checking out hundreds of 10-megabyte files first. -The compression incorporated with many archiving formats can offer an advantage here. If we create a project assembly, including Subversion metadata directories, developers should be able to download the assembly artifact and expand it, then simply type `svn up`. +The compression incorporated with many archiving formats can offer an advantage. +If we create a project assembly including Subversion metadata directories, developers can download the assembly artifact and expand it. +Then they can simply type `svn up`. ```xml ``` -_NOTE: You'll notice that we're excluding all target directories; these are a form of "calculated" and otherwise transient data, and generally shouldn't be included in archives, unless your goal is to create project binaries or similar._ +_NOTE: We exclude all target directories. These are calculated and otherwise transient data. +They generally should not be included in archives. -Using Regular Expressions to Exclude Files ------------------------------------------- +## Using Regular Expressions to Exclude Files -Sometimes, you may find you need to specify an extremely fine-grained inclusion or exclusion pattern for a `fileSet`. In these cases, you have the option of specifying your pattern in the form of a regular expression by using the `%regex[...]` syntax. +Sometimes you need to specify an extremely fine-grained inclusion or exclusion pattern for a `fileSet`. +In these cases, you can specify the pattern using the `%regex[...]` syntax. -_Note:_ For completeness, the default pattern type - Ant-style patterns - can also be specified using the new `%ant[...]` syntax. This will allow room for future expansion of `fileSet` patterns, including the option to change the default pattern syntax someday. +_Note:_ For completeness, the default pattern type (Ant-style patterns) can also be specified using the `%ant[...]` syntax. +This allows room for future expansion of `fileSet` patterns, including the option to change the default pattern syntax someday. _Note:_ The same syntax is also supported for include patterns. #[[### Example: Including directories named `target` in the `src` directory]]# -In this example, we want to produce a buildable source distribution of a Maven project hierarchy. Obviously, each project's `target` directory is a temporary workspace for the build process, so we want to exclude these directories. However, if one or more of the projects also includes a subdirectory named `target` in the `src` directory structure - perhaps as part of a Java package name - we want to make sure the files in this directory are included in the assembly. +In this example, we want to produce a buildable source distribution of a Maven project hierarchy. +Each project's `target` directory is a temporary workspace for the build process, so we want to exclude these directories. +However, if one or more of the projects includes a subdirectory named `target` in the `src` directory structure (perhaps as part of a Java package name), +we want to make sure the files in this directory are included in the assembly. ```xml @@ -169,21 +190,27 @@ In this example, we want to produce a buildable source distribution of a Maven p ``` -The above `fileSet` uses a somewhat obscure feature of regular expressions called _negative lookahead_, which means our exclude pattern will only match paths that contain the word `target` but **don't** contain `src`. Effectively, any `target` directory within the `src` directory structure will be preserved in the assembly. +The above `fileSet` uses a feature of regular expressions called *negative lookahead*. +This means the exclude pattern only matches paths that contain the word `target` but **do not** contain `src`. +Effectively, any `target` directory within the `src` directory structure will be preserved in the assembly. -Using Strict-Filtering to Catch Obsolete Patterns or Incorrect Builds ---------------------------------------------------------------------- +## Using Strict-Filtering to Catch Obsolete Patterns or Incorrect Builds -At times, you want to build in a set of sanity checks when creating your assembly, to ensure that what goes into the assembly artifact is what you intended. One way you can do this is by enabling `useStrictFiltering` on your `dependencySets`. +You can build sanity checks when creating an assembly. This ensures that what goes into the assembly artifact is what you intended. +One way to do this is by enabling `useStrictFiltering` on your `dependencySets`. -`useStrictFiltering` is a flag that tells the assembly plugin to track each include/exclude pattern to make sure it's used during creation of the assembly. This way, if the assembly-descriptor author intended for a particular artifact to be present, he can add an include/exclude pattern to the descriptor to ensure that artifact is present, and then set the `useStrictFiltering` flag. If the pattern isn't used to match at least one artifact during assembly creation, the build will fail and the user will receive a message notifying him of the unused patterns. +`useStrictFiltering` is a flag that tells the assembly plugin to track each include/exclude pattern. +It checks that each pattern is used during creation of the assembly. +If the assembly-descriptor author intended for a particular artifact to be present, they can add an include/exclude pattern to the descriptor. +Then they can set the `useStrictFiltering` flag. If the pattern is not used to match at least one artifact during assembly creation, the build fails. +The user will receive a message notifying him of the unused patterns. #[[### Example:]]# ```xml + xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} https://maven.apache.org/xsd/assembly-${mdoVersion}.xsd"> [...] @@ -197,30 +224,37 @@ At times, you want to build in a set of sanity checks when creating your assembl ``` -If **commons-logging** artifact will not present on the project dependencies list, the assembly plugin should refuse to build this assembly. +If the **commons-logging** artifact is not present on the project dependencies list, the assembly plugin refuses to build this assembly. -Using an Alternative Assembly Base Directory --------------------------------------------- +## Using an Alternative Assembly Base Directory -In many cases, assemblies should have all files arranged under one assembly base directory. This way, a user who expands the assembly will have all of the contents collected in a nice, neat directory structure, rather than spread throughout the current working directory. This is achieved using the `includeBaseDirectory` flag, and this flag is set to `true` by default, which will result in the project's `artifactId-version` being used as the assembly base directory. +In many cases, assemblies must have all files arranged under one assembly base directory. This way, a user who expands the assembly has +all of the contents collected in a neat directory structure. This is achieved using the `includeBaseDirectory` flag +This flag is set to `true` by default, which results in the project's `artifactId-version` used as the assembly base directory. -However, in some special cases you may want to use a different directory name for the root of your assembly. Starting in the 2.2 version of the assembly plugin, this use case is addressed using the `baseDirectory` element of the assembly descriptor. With this element, you can use POM expressions and static strings to specify the name of the assembly root directory. +In some special cases, you want to use a different directory name for the root of your assembly. +This need is addressed using the `baseDirectory` element of the assembly descriptor +With this element, you can use POM expressions and static strings to specify the name of the assembly root directory. #[[### Example: Eclipse-style invariable directory name for the Maven assembly]]# -In this example, let's explore what would happen if we wanted Maven to use the Eclipse approach for naming the root directory in its distribution assemblies. This way, instead of expanding the distribution to find a new `maven-2.0.4` directory, you'd find a `maven` directory. Additionally, consider that the distribution assembly is currently built from the `maven-core` project, which means we shouldn't use the `artifactId` as part of the assembly root directory. +In this example, consider what would happen if we want Maven to use the Eclipse approach for naming the root directory in its distribution assemblies. +This way, instead of expanding the distribution to find a new `maven-2.0.4` directory, you would find a `maven` directory. +Also, consider that the distribution assembly is currently built from the `maven-core` project, which means we must not use the `artifactId` +as part of the assembly root directory. ```xml + xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} https://maven.apache.org/xsd/assembly-${mdoVersion}.xsd"> [...] maven [...] ``` -Now, imagine that the distribution assembly were created in the top-level `maven` project. Now, we _can_ use the `artifactId`, and probably should, just to minimize the maintenance of these files. +Now, imagine that the distribution assembly is created in the top-level `maven` project. +We can use the `artifactId` to minimize the maintenance of these files. ```xml ``` -Advanced ModuleSet Topics -------------------------- +## Advanced ModuleSet Topics -One of the most complex sections of the assembly descriptor is the `moduleSets` section. In fact, so many improvements have been made to this section that we feel it warrants its own _"Advanced Topics"_ page. +The `moduleSets` section is one of the most complex sections of the assembly descriptor. Many improvements have been made to this section. +We have dedicated a separate page to it. - Go to [Advanced Module-Set Topics](./advanced-module-set-topics.html). diff --git a/src/site/markdown/advanced-module-set-topics.md.vm b/src/site/markdown/advanced-module-set-topics.md.vm index c318e93a..e35f5421 100644 --- a/src/site/markdown/advanced-module-set-topics.md.vm +++ b/src/site/markdown/advanced-module-set-topics.md.vm @@ -26,19 +26,19 @@ under the License. # Advanced Module-Set Topics -Quick Note ----------- +## Quick Note -Some of the topics in this document refer to more general topics or improvements in the assembly descriptor as a whole. For more information, see the [Advanced Assembly-Descriptor Topics](./advanced-descriptor-topics.html) page. +Some of the topics in this document refer to more general topics or improvements in the assembly descriptor. For more information, see the [Advanced Assembly-Descriptor Topics](./advanced-descriptor-topics.html) page. -Including and Excluding Modules using a ModuleSet -------------------------------------------------- +## Including and Excluding Modules using a ModuleSet -As you are no doubt aware, Maven introduces advanced handling of multimodule builds. These are builds which contain multiple, often interrelated projects. In these builds, project hierarchy is established through use of the `modules` section of the POM, where parent POMs specify their children in a `modules` section. Other relationships, like interdependency, also exist within multimodule builds; however, these are beyond the scope of this document. +Maven introduces advanced handling of multimodule builds. These are builds which contain multiple, often interrelated projects. In these builds, project hierarchy is established through +the `modules` section of the POM. Parent POMs specify their children in a `modules` section. +Other relationships, like interdependency, also exist within multimodule builds. These are beyond the scope of this document. -When constructing an assembly from any parent-level project in a multimodule build, it's possible to process this parent-POM's descendent modules, and include them in some form within the resulting assembly artifact. By default, the entire module hierarchy below the current project is available for inclusion or exclusion. Also, include/exclude patterns for modules are matched using the artifact-matching rules explained in the **Advanced Assembly-Descriptor Topics** document. +When constructing an assembly from any parent-level project in a multimodule build, it is possible to process this parent-POM's descendent modules. You can include them in some form within the resulting assembly artifact. By default, the entire module hierarchy below the current project is available for inclusion or exclusion. Include/exclude patterns for modules are matched using the artifact-matching rules explained in the **Advanced Assembly-Descriptor Topics** document. -The following examples describe how to select certain modules in the project hierarchy using basic artifact includes/excludes. It does **not** describe what to do with the selected modules; to learn about the actions available for selected modules, see [including module sources](#Including_Module_Sources) and [including module binaries](#Including_Module_Binaries) below. For other, more advanced module-handling options, read on! +The following examples describe how to select certain modules in the project hierarchy using basic artifact includes/excludes. They do **not** describe what to do with the selected modules. To learn about the actions available for selected modules, see [including module sources](#Including_Module_Sources) and [including module binaries](#Including_Module_Binaries) below. #[[### Example: Select one from a set of child projects]]# @@ -71,7 +71,8 @@ We can select **just** the child1 module using the following `moduleSet`: ``` -_NOTE: It's important to remember that, if the child1 project itself had children, those children would not be included just because the child1 project was included. Each module is matched separately._ +_NOTE: Remember that if the child1 project itself had children, those children would not be included just because the child1 project was included. +Each module is matched separately._ @@ -79,10 +80,10 @@ _NOTE: It's important to remember that, if the child1 project itself had childre -Quick Note on `outputFileNameMapping` within ModuleSets -------------------------------------------------------- +## Quick Note on `outputFileNameMapping` within ModuleSets -When used from within a `moduleSet`, all `outputFileNameMapping` configurations with expressions like `${esc.d}{artifactId}` _extract information from the artifact in question._ +When used from within a `moduleSet`, all `outputFileNameMapping` configurations with expressions like `${esc.d}{artifactId}` +extract information from the artifact in question. #[[### Example: Setting `outputFileNameMapping` from `moduleSet/binaries`]]# @@ -101,20 +102,28 @@ The following `outputFileNameMapping`: ${module.groupId}-${module.artifactId}-${module.version}.${module.extension} ``` -Will result in a file called `org.test-project-1.0.jar` being created within the assembly. +results in a file called `org.test-project-1.0.jar` created within the assembly. -_NOTE: The expression_ `${esc.d}{module.extension}` _is mapped to the file extension supplied by the ArtifactHandler for the type_ `jar`. _It's important to remember that the file extension_ **need not be .jar**_._ +_NOTE: The expression_ `${esc.d}{module.extension}` is mapped to the file extension supplied by the ArtifactHandler for the type_ `jar`. +_It is important to remember that the file extension need not be .jar._ -Including Module Sources -------------------------------------------------------------- + -Once you've selected certain modules to be included in the assembly, you have to determine what you want included from each module. This usually depends on the purpose of the assembly. For instance, if you're building a binary assembly, for use in a runtime context, you probably want to include module binaries only (see the [Including_Module_Binaries](#Including_Module_Binaries) section below). However, if your assembly is meant to include project sources, either as a reference or to allow users to build your project (or for some other reason altogether), then you're probably interested in the `sources` section of the `moduleSet`. +## Including Module Sources -Processing module sources is a fileSet-based activity. That is, sources are included or excluded based on file-matching patterns, or explicit `fileSet` subsections. **For backward compatibility only**, the `` section itself supports `includes` and `excludes` that can help determine which files from a module's directory should be processed. Starting in version 2.2 of the assembly plugin, the `` section supports a `` subsection, which is the preferred way of selecting module-source files for processing. +Once you have selected certain modules to be included in the assembly, you must determine what you want to includ from each module. +This usually depends on the purpose of the assembly. For instance, if you are building a binary assembly for use in a runtime context, you probably want to include module binaries only (see the [Including_Module_Binaries](#Including_Module_Binaries) section below). If your assembly is meant to include project sources, either as a reference or to allow users to build your project, you are probably interested in the `sources` section of the `moduleSet`. + +Processing module sources is a fileSet-based activity. Sources are included or excluded based on file-matching patterns, or explicit `fileSet` subsections. +**For backward compatibility only**, the `` section itself supports `includes` and `excludes`. +These can help determine which files from a module's directory must be processed. +Starting in version 2.2 of the assembly plugin, the `` section supports a `` subsection. +This is the preferred way of selecting module-source files for processing. #[[### Example: including the `src` directory from each selected module]]# -In this example, we'll explore how to include the `src` directory **only** for each module selected by the moduleSet. This is useful to provide a source reference for your project to users. +In this example, we explore how to include the `src` directory **only** for each module selected by the moduleSet. +This is useful to provide a source reference for your project to users. ```xml ``` -_NOTE: We exclude the target directory, since this is assumed to be temporary storage for files produced during the course of a Maven build. Permanent project files are not meant to reside here..._ +_NOTE: We exclude the target directory. This is assumed to be temporary storage for files produced during the course of a Maven build. +Permanent project files should not reside here._ #[[### Consolidating All Module Sources into a Single Directory Structure]]# -Normally, each module processed by the assembly plugin is placed within its own directory structure inside the assembly root directory. For module sources, the default name of this module-specific directory is the module's `artifactId`. +Normally, each module processed by the assembly plugin is placed within its own directory structure inside the assembly root directory. +For module sources, the default name of this module-specific directory is the module's `artifactId`. -However, in some cases you may want to consolidate module sources into the same directory structure, based in the assembly root directory. To do this, simply set the `includeModuleDirectory` flag to `false`. +In some cases, you want to consolidate module sources into the same directory structure, based in the assembly root directory. +To do this, set the `includeModuleDirectory` flag to `false`. #[[#### Example: Copy all module sources into a single `src` directory]]# -When providing a source reference to users, you may want to produce a single, consolidated source directory containing all of the source files from your multimodule hierarchy. +When providing a source reference to users, you might want to produce a single, consolidated source directory containing all of the source +files from the multimodule hierarchy. ```xml ``` -Including Module Binaries ---------------------------------------------------------------- + + +## Including Module Binaries -**WARNING!** Using the `binaries` section of a `moduleSet` definition involves some tricky considerations that are a result of the way Maven sorts and executes project builds within a multimodule context. Please read [this FAQ entry](./faq.html#module-binaries) if you decide to use them. +**WARNING!** Using the `binaries` section of a `moduleSet` is tricky. This is a result of the way Maven sorts and executes project builds within a multimodule context. +Read [this FAQ entry](./faq.html#module-binaries) if you decide to use them. -In cases where your assembly artifact is meant to be used in a runtime context, you'll most likely want to include the binaries from any modules processed by the assembly plugin. This can be as simple as adding the module's jar artifact to your assembly archive; or, it can involve selectively including the dependencies of that module in addition to the module's own jar. +If your assembly artifact is meant to be used in a runtime context, you most likely want to include the binaries from any modules processed by the assembly plugin. +This can be as simple as adding the module's jar artifact to your assembly archive. It can also involve selectively including the dependencies of that module in addition to the module's own jar. -At any rate, processing module binaries is an artifact-based activity. Accordingly, selection of the appropriate artifacts for a given module follows the artifact inclusion rules explained in the **Advanced Assembly-Descriptor Topics** document. +Processing module binaries is an artifact-based activity. Selecting the appropriate artifacts for a given module follows the artifact inclusion rules explained in the **Advanced Assembly-Descriptor Topics** document. -Once you've selected _which_ artifacts should be processed for a particular module, you have several options for _how_ to process them. In its simplest form, the `binaries` section of a `moduleSet` has many of the same characteristics as a `dependencySet`. That is, you have the option to specify an `outputDirectory`, and you can choose whether to unpack the artifact(s) - the default action will unpack them. +Once you have selected which artifacts must be processed for a particular module, you have several options for how to process them. In its simplest form, the `binaries` section of a `moduleSet` has many of the same characteristics as a `dependencySet`. You have the option to specify an `outputDirectory`, and you can choose whether to unpack the artifact(s). The default action will unpack them. #[[### Processing a Module's Attachment Artifacts]]# -Sometimes it's important to have the option to add artifacts from a module that are not the main project artifact. Such artifacts might include javadocs, project sources, or even other assembly artifacts. +Sometimes it is important to have the option to add artifacts from a module that are not the main project artifact. +Such artifacts can include javadocs, project sources, or even other assembly artifacts. #[[#### Example: Including other assemblies within the current assembly]]# @@ -322,11 +346,15 @@ Suppose we have the following project structure: + app-site ``` -Further, suppose that the assembly plugin is currently executing at the `application` level, but that another assembly archive has been created previously for the `app-site` project. This other assembly archive is a zip file containing the project website. We want to include a copy of this website in the application distribution assembly, which we are creating now. +Further, suppose that the assembly plugin is currently executing at the `application` level. +Another assembly archive has been created previously for the `app-site` project. +This other assembly archive is a zip file containing the project website. +We want to include a copy of this website in the application distribution assembly which we are creating now. Finally, suppose that the website-attachment has a classifier of `site` taken from the assemblyId. -Since the zipfile containing the website produced by `app-site` is an attached artifact in that module, we'll need to extract that artifact instead of the main project artifact. +Since the zipfile containing the website produced by `app-site` is an attached artifact in that module, +we need to extract that artifact instead of the main project artifact. ```xml ``` -_NOTE: The_ `binaries` _section still accommodates direct_ `` _and_ `` _subsections, for specifying which module-dependencies to include in the assembly. However, these are deprecated, and only provided for backward compatibility._ +_NOTE: The_ `binaries` _section still accommodates direct_ `` _and_ `` _subsections for specifying which module-dependencies to include in the assembly. However, these are deprecated and only provided for backward compatibility._ diff --git a/src/site/markdown/descriptor-refs.md b/src/site/markdown/descriptor-refs.md index ce4bb003..0e37aa90 100644 --- a/src/site/markdown/descriptor-refs.md +++ b/src/site/markdown/descriptor-refs.md @@ -28,38 +28,42 @@ under the License. # Pre-defined Descriptor Files -There are four predefined descriptor formats available for reuse, packaged within the Assembly Plugin. Their descriptorIds are: +There are four predefined descriptor formats available for reuse. They are packaged within the Assembly Plugin. Their descriptorIds are: + ## bin -Use `bin` as the `descriptorRef` of your assembly-plugin configuration in order to create a binary distribution archive of your project. This built-in descriptor produces an assembly with the classifier `bin` in three archive formats: tar.gz, tar.bz2, and zip. +Use `bin` as the `descriptorRef` of your assembly-plugin configuration. This creates a binary distribution archive of your project. The built-in descriptor produces an assembly with the classifier `bin` in three archive formats: tar.gz, tar.bz2, and zip. -The assembled archive contains the binary JAR produced by running `mvn package` plus any README, LICENSE, and NOTICE files available in the project root directory. +The assembled archive contains the binary JAR produced by running `mvn package`. It also contains any README, LICENSE, and NOTICE files available in the project root directory. Below is the `bin` descriptor format: + ## jar-with-dependencies -Use `jar-with-dependencies` as the `descriptorRef` of your assembly-plugin configuration in order to create a JAR which contains the binary output of your project, along its the unpacked dependencies. This built-in descriptor produces an assembly with the classifier `jar-with-dependencies` using the JAR archive format. +Use `jar-with-dependencies` as the `descriptorRef` of your assembly-plugin configuration. This creates a JAR which contains the binary output of your project along with its unpacked dependencies. The built-in descriptor produces an assembly with the classifier `jar-with-dependencies` using the JAR archive format. -Note that `jar-with-dependencies` provides only basic support for uber-jars. For more control, use the [Maven Shade Plugin](https://maven.apache.org/plugins/maven-shade-plugin/). +The `jar-with-dependencies` descriptor provides only basic support for uber-jars. For more control, use the [Maven Shade Plugin](https://maven.apache.org/plugins/maven-shade-plugin/). Below is the `jar-with-dependencies` descriptor format: + ## src -Use `src` as the `descriptorRef` in your assembly-plugin configuration to create source archives for your project. The archive will contain the contents of your project's `/src` directory structure, for reference by your users. The `src` descriptorId produces an assembly archive with the classifier `src` in three formats: tar.gz, tar.bz2, and zip. +Use `src` as the `descriptorRef` in your assembly-plugin configuration. This creates source archives for your project. The archive will contain the contents of your project's `/src` directory structure for reference by your users. The `src` descriptorId produces an assembly archive with the classifier `src`. It supports three formats: tar.gz, tar.bz2, and zip. Below is the `src` descriptor format: + ## project -Using the `project` `` in your Assembly Plugin configuration will produce an assembly containing your entire project, minus any build output that lands in the `/target` directory. The resulting assembly should allow your users to build your project using Maven, Ant, or whatever build system you have configured in your project's normal SCM working directory. It produces assemblies with the classifier `project` in three archive formats: tar.gz, tar.bz2, and zip. +Using the `project` `` in your Assembly Plugin configuration produces an assembly. The assembly contains your entire project, minus any build output that lands in the `/target` directory. The resulting assembly allows your users to build your project using Maven, Ant, or whatever build system you configured in your project's normal SCM working directory. It produces assemblies with the classifier `project` in three formats: tar.gz, tar.bz2, and zip. The following is the assembly descriptor for the `project` descriptorRef: - + \ No newline at end of file diff --git a/src/site/markdown/examples/index.md b/src/site/markdown/examples/index.md index d5c52403..3367ac00 100644 --- a/src/site/markdown/examples/index.md +++ b/src/site/markdown/examples/index.md @@ -28,7 +28,7 @@ under the License. ## Table of Contents -Below, you will see a series of examples showing how to use the Assembly Plugin in various contexts. +Below, you see a series of examples showing how to use the Assembly Plugin in various contexts. - [Working with Single Projects](./single/index.html) - [Filtering Some Distribution Files](./single/filtering-some-distribution-files.html) @@ -39,4 +39,4 @@ Below, you will see a series of examples showing how to use the Assembly Plugin - [Adding Module Sources to the Assembly](./multimodule/module-source-inclusion-simple.html) - [Adding Module Binaries to the Assembly](./multimodule/module-binary-inclusion-simple.html) - [Sharing Assembly Descriptors](./sharing-descriptors.html) -- [Using Inline Assembly Descriptors](./using-inline-descriptors.html) +- [Using Inline Assembly Descriptors](./using-inline-descriptors.html) \ No newline at end of file diff --git a/src/site/markdown/examples/multimodule/index.md b/src/site/markdown/examples/multimodule/index.md index 496a0bef..4df3484c 100644 --- a/src/site/markdown/examples/multimodule/index.md +++ b/src/site/markdown/examples/multimodule/index.md @@ -28,7 +28,7 @@ under the License. Multimodule Projects use <moduleSets> in their assemblies. -The examples below may be able to help you when creating assemblies for your multimodule project. +The examples below can help you create assemblies for multimodule projects. - [Adding Module Sources to the Assembly](./module-source-inclusion-simple.html) - [Adding Module Binaries to the Assembly](./module-binary-inclusion-simple.html) diff --git a/src/site/markdown/examples/multimodule/module-binary-inclusion-simple.md.vm b/src/site/markdown/examples/multimodule/module-binary-inclusion-simple.md.vm index 0309b9a2..ac9d5df9 100644 --- a/src/site/markdown/examples/multimodule/module-binary-inclusion-simple.md.vm +++ b/src/site/markdown/examples/multimodule/module-binary-inclusion-simple.md.vm @@ -26,29 +26,32 @@ under the License. # Including Module Binaries -Warning -------- +## Warning -**Warning:** Using the `binaries` section of a `moduleSet` definition involves some tricky considerations that are a result of the way Maven sorts and executes project builds within a multimodule context. Please read [this FAQ entry](../../faq.html#module-binaries) if you decide to use them. +**Warning:** Using the `binaries` section of a `moduleSet` definition is tricky. +These are a result of the way Maven sorts and executes project builds within a multimodule context. +Read [this FAQ entry](../../faq.html#module-binaries) if you decide to use them. -**NOTE:** The new `useAllReactorProjects` flag in the `moduleSet` section allows you to consume module binaries from child modules in a multimodule build. This is an important to resolve the conflict between Maven's build ordering and the old approach to module binaries, where the assembly was build from the parent POM. Please read the FAQ entry above for more information, and read the documentation below (carefully!) to see the new approach in action. +**NOTE:** The new `useAllReactorProjects` flag in the `moduleSet` section allows you to consume module binaries from child modules in a multimodule build. +This is important to resolve the conflict between Maven's build ordering and the old approach to module binaries. +The old approach built the assembly from the parent POM. +Read the FAQ entry above for more information, and read the documentation below to see the new approach in action. -Introduction ------------- +## Introduction -It is common practice to create an assembly using the parent POM of a multimodule build. At times, you may want to ensure that this assembly also includes one or more of the module binaries. +It is common practice to create an assembly using the parent POM of a multimodule build. +At times, you may want this assembly to also include one or more of the module binaries. This example demonstrates how to include the artifact and dependencies of a module, under the directory `modules/`. -The Assembly Descriptor ------------------------ +## The Assembly Descriptor -First, let's write an assembly descriptor to create this assembly. For the sake of clarity, this descriptor will be as simple as possible, only demonstrating the features described by this example. +This is an assembly descriptor that can create this assembly. It is as simple as possible, only demonstrating the features described by this example. ```xml + xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} https://maven.apache.org/xsd/assembly-${mdoVersion}.xsd"> bin dir @@ -73,16 +76,19 @@ First, let's write an assembly descriptor to create this assembly. For the sake ``` -This descriptor states that the assembly id should be `bin`, that the output format is a directory, and that the contents of the assembly should **not** be contained within a directory named after the finalName of the top-level project. +This descriptor states that the assembly id is `bin`, that the output format is a directory, +and that the contents of the assembly must **not** be contained within a directory named after the finalName of the top-level project. -Furthermore, it states that we wish to include the artifact files for the module with a groupId of `org.test` and an artifactId of `child1`, along with its dependency artifacts. These artifacts should be contained within the directory structure `modules/child1` for this module, since the outputDirectory expression will be interpolated on a module-by-module basis. +Furthermore, it states that the assembly will include the artifact files for the module with a groupId of `org.test` and an artifactId of `child1`, +along with its dependency artifacts. These artifacts must be contained within the directory structure `modules/child1` for this module, +since the outputDirectory expression will be interpolated on a module-by-module basis. -**Finally**, notice the **new** `useAllReactorProjects` flag. This enables access to all projects in the current reactor (multimodule build), even from a child module. Using this flag, it's now possible to use a child module - sorted to the end of the multimodule build process using appropriate dependency declarations - to generate an assembly containing module binaries. +**Finally**, notice the **new** `useAllReactorProjects` flag. This enables access to all projects in the current reactor (multimodule build), even from a child module. +Using this flag, a child module (sorted to the end of the multimodule build process using appropriate dependency declarations) can generate an assembly containing module binaries. -The POM -------- +## The POM -Now, let's review the POM configuration necessary to enable the building of this assembly via the `assembly:single` goal. First, let's look at the parent POM: +Now, review the POM configuration necessary to build this assembly via the `assembly:single` goal. First, look at the parent POM: ```xml @@ -123,7 +129,7 @@ Now, let's review the POM configuration necessary to enable the building of this ``` -**NOTE:** The last module - `distribution` - is the child in which the assembly will be created. +**NOTE:** The last module (`distribution`) is the child in which the assembly will be created. That POM looks like this: @@ -184,25 +190,26 @@ That POM looks like this: ``` -This POM directs the Assembly Plugin to execute the `single` goal when the build reaches the `package` phase, and tells it to use the `bin.xml` assembly descriptor when executing. +This POM directs the Assembly Plugin to execute the `single` goal when the build reaches the `package` phase. +It tells the plugin to use the `bin.xml` assembly descriptor when executing. -Execute! ---------- +## Execute! -To build the assembly, we issue the following command: +To build the assembly, run the following command: ``` mvn clean package ``` -This will ensure that the output directory (normally, `target`), is removed before building the assembly directory. +This removes the output directory (normally, `target`) before building the assembly directory. -**Note:** Because of a quirk in Maven 2.0's execution model relating to aggregator goals and the inheritance hierarchy, we need to explicitly execute the package phase ahead of the assembly invocation, to ensure all modules have been built. +**Note:** Because of a quirk in Maven 2.0's execution model relating to aggregator goals and the inheritance hierarchy, we need to explicitly execute the package phase ahead of the assembly invocation. +This ensures all modules have been built. -Examining the Output --------------------- +## Examining the Output -When the Maven execution completes, the following directory structure should be left. Remember, our assembly format was `dir`, which is why the output is a directory and not an archive of some sort. +When the Maven execution completes, the following directory structure is left. +Remember, the assembly format was `dir`, which is why the output is a directory and not an archive of some sort. Here are the directory contents: diff --git a/src/site/markdown/examples/multimodule/module-source-inclusion-simple.md.vm b/src/site/markdown/examples/multimodule/module-source-inclusion-simple.md.vm index e7dc7315..780493c4 100644 --- a/src/site/markdown/examples/multimodule/module-source-inclusion-simple.md.vm +++ b/src/site/markdown/examples/multimodule/module-source-inclusion-simple.md.vm @@ -26,17 +26,16 @@ under the License. # Including Module Sources -Introduction ------------- +## Introduction -It is common practice to create an assembly using the parent POM of a multimodule build. At times, you may want to ensure that this assembly also includes the source code from one or more of the modules in this build. +It is common practice to create an assembly using the parent POM of a multimodule build. +At times, you may this assembly to also include the source code from one or more of the modules in this build. This example demonstrates how to include the project sources from a module in the project assembly, under the directory `sources/`. -The Assembly Descriptor ------------------------ +## The Assembly Descriptor -First, let's write an assembly descriptor to create this assembly. For the sake of clarity, this descriptor will be as simple as possible, only demonstrating the features described by this example. +First, write an assembly descriptor to create this assembly. For clarity, this descriptor is as simple as possible, only demonstrating the features described by this example. ```xml ``` -This descriptor states that the assembly id should be `src`, that the output format is a directory, and that the contents of the assembly should **not** be contained within a directory named after the finalName of the top-level project. +This descriptor states that the assembly id is `src`, that the output format is a directory, and that the contents of the assembly must **not** be contained within a directory named after the finalName of the top-level project. -Furthermore, it states that we wish to include the source files for the module with a groupId of `org.test` and an artifactId of `child1`. These sources should be contained within the directory structure `sources/child1` for this module, since the outputDirectory expression will be interpolated on a module-by-module basis. +Furthermore, it states that we wish to include the source files for the module with a groupId of `org.test` and an artifactId of `child1`. These sources must be contained within the directory structure `sources/child1` for this module, since the outputDirectory expression is interpolated on a module-by-module basis. -By default, the Assembly Plugin will add the sources under a folder named with the artifactId of each module; this can be disabled by setting `includeModuleDirectory` to `false`. +By default, the Assembly Plugin adds the sources in a folder named with the artifactId of each module. This can be disabled by setting `includeModuleDirectory` to `false`. -Note that the build directory (`target` by default) will be included, so it is explicitly excluded since this is a temporary storage for files produced during the build and it should not contain any project sources. +The build directory is included by default, so it is explicitly excluded since this is a temporary storage for files produced during the build and it must not contain any project sources. -The POM -------- +## The POM -Now, let's review the POM configuration necessary to enable the building of this assembly via the _assembly:single_ goal: +Now, review the POM configuration necessary to build of this assembly via the _assembly:single_ goal: ```xml @@ -118,23 +116,21 @@ Now, let's review the POM configuration necessary to enable the building of this ``` -This POM simply directs the Assembly Plugin to use the `src.xml` assembly descriptor when executing. +This POM directs the Assembly Plugin to use the `src.xml` assembly descriptor when executing. -Execute! ---------- +## Execute! -To build the assembly, we issue the following command: +To build the assembly, run the following command: ```shell mvn clean assembly:single ``` -This will ensure that the output directory (normally, `target`), is removed before building the assembly directory. +This rmeoves the output directory (normally, `target`) before building the assembly directory. -Examining the Output --------------------- +## Examining the Output -When the Maven execution completes, the following directory structure should be left: +When the Maven execution completes, the following directory structure is left: ```unknown target/parent-1.0-src/ diff --git a/src/site/markdown/examples/sharing-descriptors.md.vm b/src/site/markdown/examples/sharing-descriptors.md.vm index f6218a5b..63c8fc03 100644 --- a/src/site/markdown/examples/sharing-descriptors.md.vm +++ b/src/site/markdown/examples/sharing-descriptors.md.vm @@ -26,14 +26,12 @@ under the License. # Sharing Assembly Descriptors -So you have created an assembly descriptor that you feel is so good that you want to share it between several of your projects. The simplest way to solve this problem is to create a separate project for your assembly descriptor. Let's call the project _my-assembly-descriptor_. +You have created an assembly descriptor that you want to share between several projects. +The simplest way to solve this problem is to create a separate project for your assembly descriptor. Let us call the project _my-assembly-descriptor_. -**Note:** This example has been updated for version 2.2. The previous versions of this example were wrong. You must follow the steps below to make your shared assembly descriptors work with version 2.2 or later. +## The Shared Assembly Descriptor Project -The Shared Assembly Descriptor Project --------------------------------------- - -Here's what the directory structure for that project looks like: +Here is the directory structure for that project: ```unknown my-assembly-descriptor @@ -45,11 +43,11 @@ my-assembly-descriptor `-- pom.xml ``` -There are just two files in this project: your assembly descriptor `myassembly.xml` and a `pom.xml`. +There are just two files in this project: your assembly descriptor `myassembly.xml` and `pom.xml`. -**Note:** Your assembly descriptors must be in the directory `/src/main/resources/assemblies` to be available to the Assembly Plugin. +**Note:** Your assembly descriptors must be in the directory `/src/main/resources/assemblies` to be available to the Assembly Plugin. -First let's check out the POM for the Shared Assembly Descriptor Project. It is quite simple: +This is the POM for the Shared Assembly Descriptor Project. It is quite simple: ```xml @@ -61,7 +59,7 @@ First let's check out the POM for the Shared Assembly Descriptor Project. It is ``` -Next let's look at our shared assembly descriptor. This is just an example. Replace it with the assembly descriptor you want to share. +Next, look at the shared assembly descriptor. ```xml ``` -Run '`mvn install`' on this project to install the Shared Assembly Descriptor project into your local repository. +Run '`mvn install`' to install the Shared Assembly Descriptor project into the local repository. -The Project Using the Shared Assembly Descriptor ------------------------------------------------- +## The Project Using the Shared Assembly Descriptor -In the project that wants to use our Shared Assembly Descriptor, you need to add `my-assembly-descriptor` as a dependency on the Assembly Plugin. This makes our assembly descriptor available for the Assembly Plugin to use. +In the project that needs Shared Assembly Descriptor, add `my-assembly-descriptor` as a dependency on the Assembly Plugin. +This makes the assembly descriptor available for the Assembly Plugin to use. -**Note:** You need to use the file name of your assembly descriptor, without the xml file extension, in ``. You can not use the id of your assembly descriptor. The assembly descriptor used in this example have the file name `myassembly.xml`, but its id is `my-assembly-descriptor-id`. Therefor we use `myassembly` to reference that assembly descriptor. +**Note:** You need to use the file name of the assembly descriptor, without the xml file extension, in ``. You can ot use the id of the assembly descriptor. +The assembly descriptor used in this example has the file name `myassembly.xml`, but its id is `my-assembly-descriptor-id`. +Therefore, we use `myassembly` to reference that assembly descriptor. ```xml diff --git a/src/site/markdown/examples/single/filtering-some-distribution-files.md.vm b/src/site/markdown/examples/single/filtering-some-distribution-files.md.vm index 213cb4c3..119ffeea 100644 --- a/src/site/markdown/examples/single/filtering-some-distribution-files.md.vm +++ b/src/site/markdown/examples/single/filtering-some-distribution-files.md.vm @@ -26,22 +26,29 @@ under the License. # Filtering Some Distribution Files -Introduction ------------- +## Introduction -File filtering is used to substitute variable fields from inside a file to their represented values. For the Assembly Plugin, and most Maven filtering procedures, these variables are enclosed between ${esc.d}{ and }. For example, before a file is filtered, it contains `${esc.d}{project.artifactId}`. But after filtering is complete, a new file is created with the project's `artifactId` substituting `${esc.d}{project.artifactId}` and that this new file is used instead of the original one. +File filtering substitutes variable fields from inside a file with their values. +For the Assembly Plugin, and most Maven filtering procedures, these variables are enclosed between ${esc.d}{ and }. +For example, before a file is filtered, it contains `${esc.d}{project.artifactId}`. +After filtering is complete, a new file is created. The project's `artifactId` substitutes `${esc.d}{project.artifactId}`. +This new file is used instead of the original one. -Although filtering can be done during the process-resources phase, not all files going into your distribution will be coming from a project resource. Thus, the Assembly Plugin allows filtering of files before copying them into the created assembly. +Although filtering can be done during the process-resources phase, not all files going into a distribution come from a project resource. +Thus, the Assembly Plugin allows filtering files before copying them into the created assembly. -This example demonstrates how to filter files before adding them into the assembly. In this example, we need to filter distribution files into the archive. The files included in the distribution are: +This example demonstrates how to filter files before adding them into the assembly. +We need to filter distribution files into the archive. The files included in the distribution are: - README.txt - LICENSE.txt - NOTICE.txt -All the above files are in the root directory of the project but only the README and the NOTICE files should be filtered. The property file used to filter these are files is found in `src/assembly/filter.properties`. +These files are in the root directory of the project, but only the README and the NOTICE files must be filtered. +The properties file used to filter these files is `src/assembly/filter.properties`. -A property file is a file which contains the names of the variables and their corresponding string value. The format of its contents is identical to how Java Property files are saved. Below is an example of a property file: +A property file contains the names of the variables and their corresponding string values. +The format is a Java Properties file. Here is an example of a property file: ```properties # lines beginning with the # sign are comments @@ -50,10 +57,9 @@ variable1=value1 variable2=value2 ``` -The Assembly Descriptor ------------------------ +## The Assembly Descriptor -Filtering is only enabled inside <files> so that's what we will use. Thus, our assembly descriptor will be: +Filtering is only enabled inside <files> so that is what we will use. The assembly descriptor is: ```xml ``` -The above descriptor tells the Assembly Plugin to filter both the README.txt and the NOTICE.txt files and to just copy the LICENSE.txt file. +This descriptor tells the Assembly Plugin to filter both README.txt and NOTICE.txt files and to copy the LICENSE.txt file without filtering. Alternatively, if there are many .txt files to include inside <files>, we can setup both <fileSets> and <files> like so: @@ -121,12 +127,11 @@ Alternatively, if there are many .txt files to include inside <files>, we ``` -The above descriptor adds all .txt files to the assembly but filters README.txt and NOTICE.txt files. +This descriptor adds all .txt files to the assembly but filters README.txt and NOTICE.txt files. -The POM -------- +## The POM -The configuration of the Assembly Plugin inside pom.xml should not be different from the others, except for the configuration of the filter file, so: +The configuration of the Assembly Plugin inside pom.xml must not be different from the others, except for the configuration of the filter file: ```xml @@ -151,10 +156,9 @@ The configuration of the Assembly Plugin inside pom.xml should not be different ``` -Generating The Assembly ------------------------ +## Generating The Assembly -To generate the distribution assembly, we then use: +To generate the distribution assembly, run: ```shell mvn clean assembly:single diff --git a/src/site/markdown/examples/single/including-and-excluding-artifacts.md b/src/site/markdown/examples/single/including-and-excluding-artifacts.md index fdc53be4..217bb6a5 100644 --- a/src/site/markdown/examples/single/including-and-excluding-artifacts.md +++ b/src/site/markdown/examples/single/including-and-excluding-artifacts.md @@ -23,13 +23,13 @@ limitations under the License. # Including and Excluding Artifacts -Currently the include/exclude format is based upon the dependency conflict id which has a form of: `groupId:artifactId:type:classifier`. A shortened form of the dependency conflict id may also be used `groupId:artifactId`. +The include/exclude format is based on the dependency conflict id. The form is: `groupId:artifactId:type:classifier`. A shortened form `groupId:artifactId` can also be used. -The check for inclusion/exclusion is done based on either the dependency conflict id or the shortened form as a `String.equals()` so it must be an identical match for it to be included or excluded. At present there is no support for regular expressions. +The check for inclusion/exclusion is done based on either the dependency conflict id or the shortened form as a `String.equals()` match. It must be an identical match for the artifact to be included or excluded. There is no support for regular expressions. -This example excludes the log4j-1.2-api and commons-lang3 jar files from the assembly. This would be useful when you are building a super distribution assembly which contained sub distributions (i.e. other already assembled zips or tars) where in your pom you are depenedent upon those distributions. But because the distributions transitively depend upon the project's dependencies the assembly also includes the jar files (which are already in the assemblies and don't need to be duplicated) +This example excludes the log4j-1.2-api and commons-lang3 jar files from the assembly. This is useful when you are building a super distribution assembly. The assembly contains sub distributions (other already assembled zips or tars). Your pom depends on those distributions. Because the distributions transitively depend on the project's dependencies, the assembly also includes the jar files. These files are already in the assemblies and do not need to be duplicated. -Your pom might include something like: +The pom might include something like: ```xml @@ -42,7 +42,7 @@ Your pom might include something like: ``` -And then in your assembly you exclude all the jar dependencies pulled in from the binary assembly. In this example the commons-lang3 and log4j-1.2-api jars are included unnecessarily (as they are in the bin.zip file already) +Then, in the assembly, exclude all the jar dependencies pulled in from the binary assembly. In this example the commons-lang3 and log4j-1.2-api jars are included unnecessarily (as they are in the bin.zip file already). ```xml diff --git a/src/site/markdown/examples/single/index.md b/src/site/markdown/examples/single/index.md index 6c141dc8..781d89d3 100644 --- a/src/site/markdown/examples/single/index.md +++ b/src/site/markdown/examples/single/index.md @@ -28,9 +28,9 @@ under the License. A Single Project is a project whose assemblies do not use <moduleSets>. -The examples below may help you in creating assemblies for your single projects. +The examples below can help you in creating assemblies for your single projects. - [Filtering Some Distribution Files](./filtering-some-distribution-files.html) - [Including/Excluding Artifacts](./including-and-excluding-artifacts.html) - [Using Component Descriptors](./using-components.html) -- [Using Container Descriptor Handlers](./using-container-descriptor-handlers.html) +- [Using Container Descriptor Handlers](./using-container-descriptor-handlers.html) \ No newline at end of file diff --git a/src/site/markdown/examples/single/using-components.md.vm b/src/site/markdown/examples/single/using-components.md.vm index 44fc1010..4f6b627e 100644 --- a/src/site/markdown/examples/single/using-components.md.vm +++ b/src/site/markdown/examples/single/using-components.md.vm @@ -26,19 +26,19 @@ under the License. # Using Component Descriptors -Introduction ------------- +## Introduction -Suppose you have a project which will be distributed in two forms: one for use with appserver A and another for appserver B. And as customization for these two servers, you need to exclude some dependencies which are not used by the appserver you will be distributing. +Suppose you have a project which will be distributed in two forms, one for use with appserver A and another for appserver B. +You need to exclude some dependencies which are not used by the appserver. -**NOTE:** _Although putting <excludes> inside <dependencySets> may provide the result we want, it is not recommended because if a new appserver becomes available, you will have to maintain the excludes of the other distributions to exclude dependencies meant for the new appserver._ +**NOTE:** _Putting <excludes> inside <dependencySets> might provide the result we want. +However, this approach is not recommended. If a new appserver becomes available, you will have to maintain the excludes of the other distributions._ -This example demonstrate the use of <componentDescriptors>, more information can be found [here](../../assembly.html). +This example demonstrates the <componentDescriptors>. More information can be found [here](../../assembly.html). -The Assembly Descriptors ------------------------- +## The Assembly Descriptors -First, let's write the assembly descriptor for appserver A distribution. It should like this: +First, write the assembly descriptor for appserver A distribution. It looks like this: ```xml ``` -The assembly descriptor for appserver B distribution would then be similar: +The assembly descriptor for appserver B distribution is similar: ```xml ``` -From the two descriptors shown, we can say that there are three artifacts common for both, thus we separate them into a common component descriptor and save it as `src/assembly/component.xml`. Its contents would be: +There are three artifacts in common between the two descriptors. +We separate them into a common component descriptor and save it as `src/assembly/component.xml`. Its contents are: ```xml @@ -103,7 +104,7 @@ From the two descriptors shown, we can say that there are three artifacts common ``` -Then the final assembly descriptor for the appserver A would be: +Then the final assembly descriptor for the appserver A is: ```xml ``` -And the corresponding assembly descriptor for the appserver B then would be: +The corresponding assembly descriptor for appserver B is: ```xml ``` -The POM -------- +## The POM -Now we should update the POM configuration of the project for the Assembly Plugin, which should look like: +Now update the POM configuration of the project for the Assembly Plugin: ```xml @@ -177,10 +177,10 @@ Now we should update the POM configuration of the project for the Assembly Plugi ``` -Creating The Distributions --------------------------- +## Creating The Distributions -Since we didn't configure the assembly plugin to always generate the configured assemblies during the project's normal build lifecycle, we create the distributions by: +Since we did not configure the assembly plugin to generate the configured assemblies during the project's normal build lifecycle, +create the distributions by: ```shell mvn assembly:single diff --git a/src/site/markdown/examples/single/using-container-descriptor-handlers.md.vm b/src/site/markdown/examples/single/using-container-descriptor-handlers.md.vm index 62d8612d..bc413ba3 100644 --- a/src/site/markdown/examples/single/using-container-descriptor-handlers.md.vm +++ b/src/site/markdown/examples/single/using-container-descriptor-handlers.md.vm @@ -26,21 +26,20 @@ under the License. # Using Container Descriptor Handlers -Introduction ------------- +## Introduction -Container descriptor handlers can be used to filter dynamically the content of files configured in a descriptor, for example by aggregating multiple files into a single file, or customizing the content of specific files. +Container descriptor handlers can be dynamically filter files configured in a descriptor. +They can aggregate multiple files into a single file or customize the content of specific files. -This example demonstrate the use of `` in the assembly [descriptor format](../../assembly.html). +This example demonstrates the `` in the assembly [descriptor format](../../assembly.html). -Built-in container descriptor handlers --------------------------------------- +## Built-in container descriptor handlers The plugin comes with several handlers already defined.
file-aggregator
-
This handler matches the files according to the given regular expression filePattern, aggregates their content, and stores the output in the assembly at the given outputPath. A sample descriptor which matches all file.txt files configured in the assembly and aggregates them, by appending their content, into a single file.txt located under the base directory of the assembly, is:
<assembly xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
+
This handler matches the files according to the given regular expression filePattern. It aggregates their content and stores the output in the assembly at the given outputPath. A sample descriptor which matches all file.txt files configured in the assembly and aggregates them into a single file.txt located under the base directory of the assembly is:
<assembly xmlns="http://maven.apache.org/ASSEMBLY/${mdoVersion}"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/ASSEMBLY/${mdoVersion} http://maven.apache.org/xsd/assembly-${mdoVersion}.xsd">
   ....
@@ -89,12 +88,12 @@ The plugin comes with several handlers already defined.
 </assembly>
-Custom container descriptor handlers ------------------------------------- +## Custom container descriptor handlers -You can create your own container descriptor handler by creating a class implementing `ContainerDescriptorHandler`. As an example, let's create a handler that will prepend a configured comment to every properties file configured in an assembly descriptor. +You can create your own container descriptor handler by creating a class implementing `ContainerDescriptorHandler`. +As an example, let us create a handler that prepends a configured comment to every properties file configured in an assembly descriptor. -We start by creating a new Maven project named `custom-container-descriptor-handler` with the following POM: +Start by creating a new Maven project named `custom-container-descriptor-handler` with the following POM: ```xml @@ -128,22 +127,23 @@ We start by creating a new Maven project named `custom-container-descriptor-hand ``` -This POM declares a dependency on the Assembly Plugin so that we can create our handler, and generates a Plexus configuration file so that it can be found through dependency injection during assembling. +This POM declares a dependency on the Assembly Plugin so that we can create our handler. +It generates a Plexus configuration file so that it can be found through dependency injection during assembling. -Implementing `ContainerDescriptorHandler` requires defining a couple of methods: +Implementing `ContainerDescriptorHandler` requires defining three methods:
isSelected
-
Tells whether a given file or directory, configured in the assembly descriptor, should be added to the final assembly. A typical set-up would be to prevent the addition of certain files, and let the handler do its work on them.
+
Tells whether a given file or directory, configured in the assembly descriptor, must be added to the final assembly. A typical set-up would be to prevent the addition of certain files and let the handler do its work on them.
getVirtualFiles
-
Returns the list of file paths, from the root of the assembly, of each file this handler will add.
+
Returns the file paths, from the root of the assembly, of each file this handler adds.
finalizeArchiveCreation
-
Callback that is invoked when an assembly is going to be created. This method can be used to add files that resulted from the handler's work on each selected file. Cave-at: Because of the way archive finalization is performed, we need to loop through each resource in the archive before doing anything.
+
Callback that is invoked when an assembly is going to be created. This method can be used to add files that resulted from the handler's work on each selected file. Caveat: Because of the way archive finalization is performed, we need to loop through each resource in the archive before doing anything.
finalizeArchiveExtraction
Callback that is invoked when an assembly has been extracted into a directory. This method can be used to process files that resulted from the handler's work on each selected file.
-Our handler that prepends a comment to each properties file could look like the following (using here Java 8 features): +The handler that prepends a comment to each properties file could look like this: ```java package com.test; @@ -247,11 +247,18 @@ public class MyCustomDescriptorHandler implements ContainerDescriptorHandler { } ``` -It is a Plexus component, having the `ContainerDescriptorHandler` role, that is distinguished from the other handlers with its `hint` of `custom`. +It is a Plexus component with the `ContainerDescriptorHandler` role. It is distinguished from the other handlers with its `hint` of `custom`. -It selects each properties file and stores their content into a catalog map, where the key is the name of the file and the value is a list of its lines. Those matched files are not added to the assembly, because the handler needs to process them first. During assembly creation, it creates temporary files whose content are the previously read lines, prepended by a custom comment. They are then added back into the archive with their previous name. Note that this simple handler does not aggregate files with the same name - it could be enhanced to do it. When the temporary files are added to the archive, the `isSelected` method is automatically called, hence we need to set a boolean `excludeOverride` to `true` to make sure the catalog processing part is not done. +It selects each properties file and stores their content into a catalog map. +The key is the name of the file and the value is a list of its lines. +Those matched files are not added to the assembly because the handler needs to process them first. +During assembly creation, it creates temporary files. The content of these files is the previously read lines, prepended by a custom comment. +They are then added back into the archive with their previous name. Note that this simple handler does not aggregate files with the same name. +It could be enhanced to do it. When the temporary files are added to the archive, the `isSelected` method is automatically called. Hence, we need to set a boolean `excludeOverride` to `true` to make sure the catalog processing part is not done. -The last ingredient is using our custom handler in an assembly descriptor of some Maven project. Suppose there is a `src/samples` directory in this project, containing an XML file named `test.xml` and a properties file named `test.properties`. With the following descriptor format +The last ingredient is using the custom handler in an assembly descriptor of some Maven project. +Suppose there is a `src/samples` directory in this project, containing an XML file named `test.xml` and a properties file named `test.properties`. +With the following descriptor format: ```xml ``` -and the following Assembly plugin configuration +and the following Assembly plugin configuration: ```xml @@ -314,4 +321,4 @@ and the following Assembly plugin configuration ``` -the resulting assembly would contain both `test.xml` and `test.properties` under the base directory, with only the latter starting with `# A comment`. +the resulting assembly would contain both `test.xml` and `test.properties` under the base directory. Only the latter would start with `# A comment`. diff --git a/src/site/markdown/examples/using-inline-descriptors.md.vm b/src/site/markdown/examples/using-inline-descriptors.md.vm index 7f920b1a..ea2a0d59 100644 --- a/src/site/markdown/examples/using-inline-descriptors.md.vm +++ b/src/site/markdown/examples/using-inline-descriptors.md.vm @@ -26,17 +26,15 @@ under the License. # Using Inline Assembly Descriptors -Introduction ------------- +## Introduction -For simple usage we can inline Assembly descriptor into the project configuration. We don't need to create an additional file with Assembly descriptor. +For simple usage, we can inline the Assembly descriptor into the project configuration. We do not need to create an additional file with the Assembly descriptor. -It can simplify configuration in case of the parent project inherited, we don't need to use a [Shared Assembly Descriptors](./sharing-descriptors.html) +It can simplify configuration when the parent project is inherited. We do not need to use [Shared Assembly Descriptors](./sharing-descriptors.html). -The POM -------- +## The POM -We can have POM configuration of the project for the Assembly Plugin, which can look like: +We can have POM configuration of the project for the Assembly Plugin: ```xml diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md index b8304675..500215b1 100644 --- a/src/site/markdown/faq.md +++ b/src/site/markdown/faq.md @@ -31,16 +31,16 @@ under the License. 4. [Starting with version 2.2 configuration/executions defined in a parent POM are no longer inherited, why?](#inherit) 5. [In previous versions (before 2.2 final), I followed the example in the documentation for sharing assembly descriptors, which recommended using the `` configuration section to refer to the shared assembly descriptor. As of version 2.2, this no longer works. Why not?](#shared-descriptor-bug) 6. [The Assembly Plugin is saying it cannot find files for the module binaries included by my assembly descriptor. What gives?](#module-binaries) -7. [In previous versions (before 2.2 final), leaving off the assembly id and leaving the classifier unconfigured resulted in the assembly being used as the project's main artifact. With the 2.2 release, this configuration results in a validation error. My project depended on the previous behavior! Why has this changed, and how can I make this work in my project?](#required-classifiers) +7. [In previous versions (before 2.2 final), leaving off the assembly id and leaving the classifier unconfigured resulted in the assembly used as the project's main artifact. With the 2.2 release, this configuration results in a validation error. My project depended on the previous behavior! Why has this changed, and how can I make this work in my project?](#required-classifiers) 8. [I have a dependencySet that includes some artifacts with classifiers, and others without classifiers. How can I setup the file mappings to handle both cases appropriately?](#dashClassifier) 9. [Which properties can be used in the outputFileNameMapping parameter?](#outputFileNameMapping) -10. [Tar complains about groupid value being too big](#tarFileModes) +10. [Tar complains about groupid value too big](#tarFileModes) ### If the Assembly Plugin is run during the package phase, do my assemblies get deployed during the deploy phase? -Yes. The assemblies created by the Assembly Plugin is attached to your project so it gets deployed too. +Yes. The assemblies created by the Assembly Plugin are attached to your project so they are deployed too. @@ -52,19 +52,17 @@ Yes. You can refer to it using the id of the assembly as the dependency classifi ### How do I use the Assembly Plugin to package my project's javadoc files? -The Javadoc Plugin can generate the javadoc files of your projects. Also, the Javadoc Plugin can package them! +The Javadoc Plugin can generate the javadoc files of your projects. The Javadoc Plugin can also package them. -Please see the [Javadoc Plugin Documentation](https://maven.apache.org/plugins/maven-javadoc-plugin/). +See the [Javadoc Plugin Documentation](https://maven.apache.org/plugins/maven-javadoc-plugin/). ### Starting with version 2.2 configuration/executions defined in a parent POM are no longer inherited, why? -As part of the deprecation of all goals except for the `single` goal, the goals of the Assembly Plugin and -their configuration/executions are no longer inherited by default. +The goals of the Assembly Plugin and their configuration/executions are no longer inherited by default. This change is part of the deprecation of all goals except the `single` goal. -If you need the configuration/executions to be inherited you need to explicitly say so by adding a line to -the plugin declaration in the parent POM: +If you need the configuration/executions to be inherited, add a line to the plugin declaration in the parent POM: ```xml @@ -77,84 +75,45 @@ the plugin declaration in the parent POM: ### In previous versions (before 2.2 final), I followed the example in the documentation for [sharing assembly descriptors](/examples/sharing-descriptors.html), which recommended using the `` configuration section to refer to the shared assembly descriptor. As of version 2.2, *this no longer works*. Why not? -The use of `` was always incorrect, and counter to the design of this configuration parameter. -Unfortunately, some code was introduced in version 2.2-beta-2 that allowed this parameter to reference -descriptors on the classpath, instead of being forced to use `` as is the intention of the -design. In version 2.2, this bug was fixed. +The use of `` was incorrect. It was counter to the design of this configuration parameter. Some code was introduced in version 2.2-beta-2. This code allowed the parameter to reference descriptors on the classpath. In version 2.2, this bug was fixed. -It is important to note that the correct form, `` has always worked, and continues to work. -The documentation has now been fixed to reflect the correct configuration. +The correct form `` has always worked and continues to work. The documentation now reflects the correct configuration. ### The Assembly Plugin is saying it cannot find files for the module binaries included by my assembly descriptor. What gives? -**If your assembly includes module binaries, those binaries won't be available to the assembly plugin except -in special cases.** This is normally seen when the Assembly Plugin is bound to a phase of the standard build -lifecycle in the **parent POM** of a multimodule build. It is a result of the way Maven sorts and executes the -build process for a multimodule project layout. - -In a multimodule hierarchy, when a child module declares the parent POM in its `` section, Maven -interprets this to mean that the parent project's build must be completed before the child build can start. -This ensures that the parent project is in its final form by the time the child needs access to its POM -information. In cases where the Assembly Plugin is included as part of that parent project's build process, -it will execute along with everything else as part of the parent build - **before the child build can start**. -If the assembly descriptor used in that parent build references module binaries, it effectively expects the -child build to be completed **before the assembly is processed**. This leads to a recursive dependency -situation, where the child build depends on the parent build to complete before it can start, while the parent -build depends on the presence of child-module artifacts to complete successfully. Since these artifacts are -missing, the Assembly Plugin will complain about missing artifacts, and the build will fail. - -In many cases, you can avoid this problem by adding a new child module whose sole purpose is to produce your -assembly. In the POM for this new project, add dependency definitions for any of the module binaries you had -previously referenced. This will ensure the new assembly child is built last. Then, move your assembly -descriptor into this new child module. At this point, you have the option of either changing all -moduleSet/binaries references to dependencySet references, **or you can keep the moduleSets and instead set -the useAllReactorProjects flag to *true* for each moduleSet.** - -Obviously, any fileSet or file references you may have in this descriptor may need to be adjusted or have the -files they reference moved into the new child module alongside the descriptor itself. - -In cases where you absolutely must use module-binaries references, you should create an assembly-child POM -mentioned above, then insert `true` to each of your `moduleSet` -sections. Then, bind the assembly in your assembly-child POM (normally to the `package` phase) using the -`single` goal. When you execute the build from the top-level POM, Maven should generated your assembly in the -new child project. +**If your assembly includes module binaries, those binaries are not available to the assembly plugin except in special cases.** This problem usually occurs when the Assembly Plugin is bound to a phase of the standard build lifecycle in the **parent POM** of a multimodule build. It is a result of the way Maven sorts and executes the build process for a multimodule project layout. + +In a multimodule hierarchy, when a child module declares the parent POM in its `` section, Maven interprets this to mean that the parent project's build must be completed before the child build can start. This ensures that the parent project is in its final form by the time the child needs access to its POM information. If the Assembly Plugin is included as part of that parent project's build process, it will execute as part of the parent build **before the child build can start**. If the assembly descriptor used in that parent build references module binaries, it expects the child build to be completed **before the assembly is processed**. This leads to a recursive dependency situation. The child build depends on the parent build to complete before it can start. The parent build depends on the presence of child-module artifacts to complete successfully. Since these artifacts are missing, the Assembly Plugin will report missing artifacts and the build will fail. + +You can avoid this problem by adding a new child module. This module's sole purpose is to produce your assembly. In the POM for this new project, add dependency definitions for any of the module binaries you referenced. This will ensure the new assembly child is built last. Then, move your assembly descriptor into this new child module. You can change all moduleSet/binaries references to dependencySet references. You can also keep the moduleSets and set the useAllReactorProjects flag to true for each moduleSet. + +Any fileSet or file references in this descriptor may need to be adjusted. The files they reference may need to be moved into the new child module alongside the descriptor. + +If you must use module-binaries references, create an assembly-child POM as mentioned above. Then, add `true` to each of your `moduleSet` sections. Bind the assembly in your assembly-child POM to the `package` phase using the `single` goal. When you execute the build from the top-level POM, Maven will generate your assembly in the new child project. **NOTE:** The useAllReactorProjects flag is only available in version 2.2 and higher. -### In previous versions (before 2.2 final), leaving off the assembly id and leaving the classifier unconfigured resulted in the assembly being used as the project's main artifact. With the 2.2 release, this configuration results in a validation error. My project depended on the previous behavior! Why has this changed, and how can I make this work in my project? +### In previous versions (before 2.2 final), leaving off the assembly id and leaving the classifier unconfigured resulted in the assembly used as the project's main artifact. With the 2.2 release, this configuration results in a validation error. My project depended on the previous behavior! Why has this changed, and how can I make this work in my project? -The assembly id is used for reporting and calculating descriptor/component merges. They're also required to -avoid collisions with the main output of the project's build process. It's critical that this id be in place, -to overriding the project's main artifact inadvertently, and to help error-reporting make sense to the user. -*Leaving off the assembly id has always been an error*, but unfortunately previous releases contained a bug in -the model that allowed empty or missing assembly id's. This bug has been fixed in version 2.2. +The assembly id is used for reporting and calculating descriptor/component merges. They are also required to avoid collisions with the main output of the project's build process. This id must be in place to prevent overriding the project's main artifact inadvertently. It also helps error-reporting make sense to the user. *Leaving off the assembly id was always an error*. However, previous releases contained a bug in the model that allowed empty or missing assembly id's. This bug was fixed in version 2.2. -However, in certain cases it makes sense to use the assembly output as the main project artifact. So, what's -the correct approach in these situations? This use case is meant to require deliberate configuration, so your -intention to depart from the normal behavior will be clear. To configure the use of the assembly output as the -main project artifact, follow these steps: +In some cases, it makes sense to use the assembly output as the main project artifact. This use case requires deliberate configuration so your intention to depart from the normal behavior is clear. To configure the use of the assembly output as the main project artifact, follow these steps: -1. Make sure your assembly only uses **one format**. More than one format could mean the assembly artifact - used for the project's main artifact is non-deterministic. -2. Add the configuration: `false` to your assembly-plugin execution. - This will prevent the assembly artifact from simply being attached to the project. +1. Make sure your assembly uses only **one format**. More than one format could mean the artifact used for the project's main artifact is non-deterministic. +2. Add the configuration `false` to your assembly-plugin execution. This prevents the assembly artifact from attachment to the project. ### I have a dependencySet that includes some artifacts with classifiers, and others without classifiers. How can I setup the file mappings to handle both cases appropriately? -The best way to handle a mixed bag of dependencies with and without classifiers is to use the -**${dashClassifier?}** expression, added in version 2.2-beta-2 of the assembly plugin especially for this -purpose. This expression will determine whether each artifact has a classifier, and if it does, it will -substitute the artifact's classifier - prepended by a dash - in place of the expression. +The the **${dashClassifier?}** expression is the best way to handle a mixed bag of dependencies with and without classifiers. +This expression was added in version 2.2-beta-2 of the assembly plugin. It determines whether each artifact has a classifier. If it does, it substitutes the artifact's classifier (prepended by a dash) in place of the expression. -For example, suppose you want to include two artifacts, commons-logging-1.0.4.jar, and -yourserver-1.0-client.jar (where 'client' is the classifier of the second artifact). To do this, simply add -the following to your dependencySet: +For example, suppose you want to include two artifacts. One is commons-logging-1.0.4.jar. The other is yourserver-1.0-client.jar (where 'client' is the classifier). Add the following to your dependencySet: ```xml ${artifact.artifactId}-${artifact.version}${dashClassifier?}.${artifact.extension} @@ -166,10 +125,10 @@ the following to your dependencySet: You can use : -- all system or maven properties available in your build with the syntax `${myProperty}`. -- all environment variables with `${env.XXX}` where `XXX` is the environment variable. -- the special `${dashClassifier?}` property (see above). -- all artifacts attributes ([from the Artifact class](https://maven.apache.org/ref/3.0.4/maven-artifact/apidocs/org/apache/maven/artifact/Artifact.html)) like : +- All system or maven properties available in your build with the syntax `${myProperty}`. +- All environment variables with `${env.XXX}` where `XXX` is the environment variable. +- The special `${dashClassifier?}` property (see above). +- All artifacts attributes ([from the Artifact class](https://maven.apache.org/ref/3.0.4/maven-artifact/apidocs/org/apache/maven/artifact/Artifact.html)) like : - `${artifact.groupId}` : The artifact groupId. - `${artifact.artifactId}` : The artifact artifactId. - `${artifact.version}` : The artifact classifier. @@ -184,7 +143,6 @@ You can use : -### Tar complains about groupid value being too big +### Tar complains about groupid value too big -GNU tar has restrictions on max value of UID/GUID in tar files. Consider using the more well defined POSIX tar -format, which should support larger values. Use tarLongFileMode=posix in the assembly:single goal. +GNU tar has restrictions on max value of UID/GUID in tar files. Use the POSIX tar format instead. The POSIX format supports larger values. Set tarLongFileMode=posix in the assembly:single goal. diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md index cd637c7b..4f1b7746 100644 --- a/src/site/markdown/index.md +++ b/src/site/markdown/index.md @@ -28,11 +28,11 @@ under the License. # Apache Maven Assembly Plugin ## Introduction -The Assembly Plugin for Maven enables developers to combine project output into a single distributable archive that also contains dependencies, modules, site documentation, and other files. +The Assembly Plugin for Maven combines project output into a single distributable archive. The archive also contains dependencies, modules, site documentation, and other files. -Your project can easily build distribution "assemblies" using one of the [prefabricated assembly descriptors](./descriptor-refs.html). These descriptors handle many common operations, such as packaging a project's artifact along with generated documentation into a [single zip archive](./descriptor-refs.html#bin). Alternatively, your project can provide its own [descriptor](./assembly.html) and assume a much higher level of control over how dependencies, modules, file-sets, and individual files are packaged in the assembly. +Your project can build distribution "assemblies" by using one of the [prefabricated assembly descriptors](./descriptor-refs.html). These descriptors handle common operations. For example, they package a project's artifact along with generated documentation into a [single zip archive](./descriptor-refs.html#bin). Your project can also provide its own [descriptor](./assembly.html). This gives you more control over how dependencies, modules, file-sets, and individual files are packaged. -Currently it can create distributions in the following formats: +The plugin can create distributions in these formats: - zip - tar @@ -44,29 +44,29 @@ Currently it can create distributions in the following formats: - jar - dir - war -- and any other format that the ArchiveManager has been configured for +- Any other format that the ArchiveManager supports -If your project wants to package your artifact in an uber-jar, the assembly plugin provides only basic support. For more control, use the [Maven Shade Plugin](/plugins/maven-shade-plugin/). +If your project must package artifacts in an uber-jar, the assembly plugin provides only basic support. For more control, use the [Maven Shade Plugin](/plugins/maven-shade-plugin/). -To use the Assembly Plugin in Maven, you simply need to: +To use the Assembly Plugin in Maven, you must: -- choose or write the assembly descriptor to use, -- configure the Assembly Plugin in your project's `pom.xml`, and -- run "mvn assembly:single" on your project. +- Choose or write the assembly descriptor. +- Configure the Assembly Plugin in your project's `pom.xml`. +- Run `mvn assembly:single` on your project. -To write your own custom assembly, you will need to refer to the [Assembly Descriptor Format](./assembly.html) reference. +To write a custom assembly, refer to the [Assembly Descriptor Format](./assembly.html) reference. ## What is an Assembly? -An "assembly" is a group of files, directories, and dependencies that are 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. +An "assembly" is a group of files, directories, and dependencies that are assembled into an archive format and distributed. For example, consider a Maven project that defines a single JAR artifact. The artifact contains both a console application and a Swing application. This project could define two "assemblies". One assembly bundles the console application with its supporting scripts and dependencies. The other assembly bundles the Swing application with a 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 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 descriptor](./assembly.html). +The Assembly Plugin provides a descriptor format. This format allows you to define an arbitrary assembly of files and directories from a project. For example, if your Maven project contains the directory `src/main/bin`, you can instruct the plugin to copy this directory to the `bin` directory of an assembly. You can also change the file permissions to UNIX mode 755. The parameters for this configuration are supplied through the [assembly descriptor](./assembly.html). ## Goals -The main goal in the assembly plugin is the [single](./single-mojo.html) goal. It is used to create all assemblies. +The main goal in the assembly plugin is the [single](./single-mojo.html) goal. This goal creates all assemblies. -For more information about the goals that are available in the Assembly Plugin, see [the plugin documentation page](./plugin-info.html). +For more information about the goals in the Assembly Plugin, see [the plugin documentation page](./plugin-info.html). ## Assembly and Component Descriptor Schemas (XSD) @@ -79,14 +79,15 @@ For more information about the goals that are available in the Assembly Plugin, - [https://maven.apache.org/xsd/assembly-1.1.1.xsd](/xsd/assembly-1.1.1.xsd), [https://maven.apache.org/xsd/component-1.1.1.xsd](/xsd/component-1.1.1.xsd) (for version 2.2-beta-4 - 2.2-beta-5) - [https://maven.apache.org/xsd/assembly-1.1.0.xsd](/xsd/assembly-1.1.0.xsd), [https://maven.apache.org/xsd/component-1.1.0.xsd](/xsd/component-1.1.0.xsd) (for version 2.2-beta-1 - 2.2-beta-3) - [https://maven.apache.org/xsd/assembly-1.0.0.xsd](/xsd/assembly-1.0.0.xsd), [https://maven.apache.org/xsd/component-1.0.0.xsd](/xsd/component-1.0.0.xsd) (for version 2.1 and lower) + ## Usage -General instructions on how to use the Assembly Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. +General instructions on how to use the Assembly Plugin are on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. -In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). +If you have questions about the plugin's usage, look at the [FAQ](./faq.html) and contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and may already contain the answer to your question. You can browse the [mail archive](./mailing-lists.html). -If you feel the plugin is missing a feature or has a defect, you can file a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our [source repository](./scm.html) and will find supplementary information in the [guide to helping with Maven](/guides/development/guide-helping.html). +If the plugin is missing a feature or has a defect, file a feature request or bug report in our [issue tracker](./issue-management.html). When you create a new issue, provide a clear description of your concern. For bug fixes, developers must be able to reproduce your problem. Attach debug logs, POMs, or small demo projects to the issue. Contributors can check out the project from our [source repository](./scm.html) and find information in the [guide to helping with Maven](/guides/development/guide-helping.html). ## 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 [here](./examples/index.html). +For a deeper understanding of the Assembly Plugin, see the [examples](./examples/index.html). diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm index 797d4699..8bfc6002 100644 --- a/src/site/markdown/usage.md.vm +++ b/src/site/markdown/usage.md.vm @@ -26,20 +26,19 @@ under the License. # Usage -To handle filtering this version of Maven Assembly Plugin uses [Maven Filtering](/shared/maven-filtering/index.html) ${mavenFilteringVersion}. +To handle filtering, this version of Maven Assembly Plugin uses [Maven Filtering](/shared/maven-filtering/index.html) ${mavenFilteringVersion}. -To handle archiving this version of Maven Assembly Plugin uses [Maven Archiver](/shared/maven-archiver/index.html) ${mavenArchiverVersion}. +To handle archiving, this version of Maven Assembly Plugin uses [Maven Archiver](/shared/maven-archiver/index.html) ${mavenArchiverVersion}. -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. +This document provides instructions for using the maven-assembly-plugin. You must understand two topics. These are configuration of the plugin and the different execution styles. Configuration includes settings inside the POM and, where possible, from the command line. We cover configuration before execution. -Configuration -------------- +## Configuration -Getting started with the Assembly Plugin is pretty simple. If you want to use one of the prefabricated assembly descriptors, you configure which descriptor to use with the <`descriptorRefs>`/<`descriptorRef>` parameter. If you want to use a custom assembly descriptor, you configure the path to your descriptor using the <`descriptors>`/<`descriptor>` parameter. +Getting started with the Assembly Plugin is simple. If you want to use one of the prefabricated assembly descriptors, configure which descriptor to use with the <`descriptorRefs>`/<`descriptorRef>` parameter. If you want to use a custom assembly descriptor, configure the path to your descriptor using the <`descriptors>`/<`descriptor>` parameter. -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. When the assembly is created it will use the assemblyId as the artifact's classifier and will attach the created assembly to the project so that it will be uploaded into the repository in the install and deploy phase. +A single invocation of the Assembly Plugin can produce assemblies from multiple descriptors. This gives you maximum flexibility to customize the suite of binaries your project produces. When the assembly is created, it uses the assemblyId as the artifact's classifier. It attaches the created assembly to the project. The assembly is uploaded into the repository in the install and deploy phase. -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. You configure it as follows in your project's `pom.xml`: +For example, suppose our project produces a JAR. If we want to create an assembly binary that includes our project's dependencies, we can use one of the Assembly Plugin's prefabricated descriptors. Configure it as shown in your project's `pom.xml`: ```xml @@ -62,9 +61,9 @@ For example, imagine that our project produces a JAR. If we want to create an as ``` -Note that the Assembly Plugin allows you to specify multiple `descriptorRefs` at once, to produce multiple types of assemblies in a single invocation. +The Assembly Plugin allows you to specify multiple `descriptorRefs` at once. This produces multiple types of assemblies in a single invocation. -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 that instead: +Alternatively, you can create a custom assembly descriptor called `src.xml` in the `src/assembly` directory (see the [Resources](#Resources) section for more information). Tell the Assembly Plugin to use that descriptor instead: ```xml @@ -84,18 +83,17 @@ Alternatively, we've created a custom assembly descriptor called `src.xml` in th ``` -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. +You can specify multiple custom assembly descriptors here. You can also specify a mixture of `descriptors` and `descriptorRefs` in the same configuration. **Note:** Many other configuration options are available for the various goals in the Assembly Plugin. For more information, see the [examples section](./examples/index.html) or the [plugin parameter documentation](./plugin-info.html). -Execution: Building an Assembly -------------------------------- +## Execution: 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 build them. +Once you have configured the various `descriptors` and `descriptorRefs` for the assemblies you want the project to produce, you can build them. -In most cases, you'll want to make sure your assemblies are created as part of your normal build process. This ensures the assembly archives are made available for installation and deployment, and that they are created during the release of your project. This is handled by the `assembly:single` goal. +In most cases, you want your assemblies to be created as part of your normal build process. This ensures the assembly archives are available for installation and deployment. It also ensures they are created during the release of your project. The `assembly:single` goal handles this. -To bind the `single` goal to a project's build lifecycle, you can add this configuration (assuming you're using the `jar-with-dependencies` prefabricated descriptor): +To bind the `single` goal to a project's build lifecycle, add this configuration (assuming you are using the `jar-with-dependencies` prefabricated descriptor): ```xml @@ -125,32 +123,31 @@ To bind the `single` goal to a project's build lifecycle, you can add this confi ``` -Then, to create a project assembly, simple execute the normal `package` phase from the default lifecycle: +Then, to create a project assembly, execute the normal `package` phase from the default lifecycle: ```shell mvn package ``` -When this build completes, you should see a file in the `target` directory with a name similar to the following: +When this build completes, you see a file in the `target` directory with a name similar to: ```unknown 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. +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 that created this artifact. #[[### GOTCHA!]]# -In most cases, the `single` goal should be bound to the `package` phase of the build. However, if your assembly doesn't require binaries, or if you need to use one assembly as input for another, you may need to change this. While it's possible to assign the `single` goal to any phase of the build lifecycle, you should be careful to make sure the resources included in your assembly exist before that assembly is created. +In most cases, the `single` goal must be bound to the `package` phase of the build. However, if your assembly does not require binaries, or if you need to use one assembly as input for another, you may need to change this. You can assign the `single` goal to any phase of the build lifecycle. Make sure the resources included in your assembly exist before the assembly is created. -Advanced Configuration ----------------------- +## Advanced Configuration #[[### Creating an Executable JAR]]# -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. +The Assembly Plugin creates a self-contained binary artifact for a project. You make this an executable jar +by specifying the `Main-Class` in a `configuration`/`archive`/`manifest`/`mainClass` element. -To accommodate this, the Assembly Plugin supports configuration of an `` element which is handled by `maven-archiver` (see [Resources](#Resources)). Using this configuration, it's easy to configure the `Main-Class` attribute of the JAR manifest: ```xml @@ -175,7 +172,7 @@ To accommodate this, the Assembly Plugin supports configuration of an ` ``` -If we add this configuration to the `single` goal example above and rebuild, we will see an entry like this in the `META-INF/MANIFEST.MF` file of the resulting JAR: +With this configuration, the `single` goal adds an entry like this in the `META-INF/MANIFEST.MF` file of the JAR it assembles: ```unknown [...] @@ -186,10 +183,11 @@ For more information on advanced configuration for the Assembly Plugin, see the #[[### GOTCHA!]]# -At this point, only the `jar` and `war` assembly formats support the `` configuration element. +Only the `jar` and `war` assembly formats support the `` configuration element. -Resources -------------------------------- + + +## Resources 1. For more information on writing your own assembly descriptor, read the [Assembly Descriptor](./assembly.html) 1. For more information about `maven-archiver`, look [here](https://maven.apache.org/shared/maven-archiver/index.html).