Uploaded image for project: 'Maven Assembly Plugin'
  1. Maven Assembly Plugin
  2. MASSEMBLY-151

Documentation for the assembly plugin is utterly confusing

Details

    • Bug
    • Status: Closed
    • Major
    • Resolution: Fixed
    • 2.1, 2.2
    • 2.2
    • None
    • None

    Description

      This is going to come across as a whinge, I'm afraid, but the assembly plugin is a fairly important vital component in M2; I find it very confusing and I've been using it for a bit. I have observed it putting off other people from using m2 at all, which is I think a shame.

      I'd document it myself, but I don't understand the differences between some of the goals (and I don't understand why the fix in MASSEMBLY-97 is neccessary).

      In the goals page,there's lots of options that seem to overlap or do the same thing. There's no clue (other than trial and error) as to why some of them will work some times, and some will not (e.g. in multiproject builds). What's worse is some of the problems only appear in specific circumstances (E.g. doing multiprojects in a 'clean' build').

      This either needs documenting, or (better), fixing in the code. We have (from the site):

      assembly:assembly Assemble an application bundle or distribution from an assembly descriptor.

      Good, seems logical to me

      assembly:unpack Unpack project dependencies. Currently supports dependencies of type jar and zip.

      The reverse. Yep.

      assembly:attached Assemble an application bundle or distribution from an assembly descriptor. Do not specify a phase, so make it usable in a reactor environment where forking would create issues.

      Erk? How should a user read this? To me "usable in a reactor environment where forking would create issues" reads to me as "there's a bug in assembly:assembly if used in a multiproject build".

      • it assumes that the user knows a multi project build is a 'reactor' build
      • why can't assembly:assembly be fixed so it does work in multiproject builds? Why can't it detect the environment, and do the 'right thing' (or at the very least spit out a warning) ?
        This is just inviting the user to pick the wrong goal.

      assembly:directory Assemble an application bundle or distribution.

      Without a descriptor? If I click the link to the goal parameters for this or for assembly:assembly, I get identical pages of parameters. How is this different?

      assembly:directory-inline Assemble an application bundle or distribution from an assembly descriptor without launching a parallel lifecycle build.

      In what scenarios would I as a user need this? Is it for a bug workaround? Would it not be better as a parameter to turn off/on "parallel lifecycle build" ?

      assembly:single Assemble an application bundle or distribution from an assembly descriptor. Do not specify a phase, so make it usable in a reactor environment where forking would create issues. Do not specify it as an aggregator, so it is only for a single project. Both cases aid it in working around issues with the Maven lifecycle that should be addressed in Maven 2.1.

      A whole heap of information that seems to boil down to "there is a bug", and a heap of confusing terminology ("do not specify it as an aggregator").
      When should this be used ? Every time you actually want assembly:assembly in a multiproject build? How is it different to assembly:attached?

      It seems to me that the plugin does 2 things. (pack things, unpack things). All these additional goals seem to be (I can't tell this) workarounds for bugs.
      Why can't we just have
      assembly:assembly
      and
      assembly:unpack

      and make the plugin work properly? If multiproject builds fail on fork, then stop the plugin from forking until it can be fixed (or keep it as a cryptic option for people that really want to optimise their builds rather than confusing new customers).

      Attachments

        Issue Links

          Activity

            I've overhauled the javadoc descriptions for the different mojos in this plugin, which is what drives the descriptions that show up on the generated website. I'm going to have to take a deeper look at the descriptor documentation for the 2.2-final release (in particular, the discussions of how to use outputFileNameMapping and probably outputDirectory expressions properly).

            jdcasey John Dennis Casey added a comment - I've overhauled the javadoc descriptions for the different mojos in this plugin, which is what drives the descriptions that show up on the generated website. I'm going to have to take a deeper look at the descriptor documentation for the 2.2-final release (in particular, the discussions of how to use outputFileNameMapping and probably outputDirectory expressions properly).

            need to discuss the differences between ${module.} and ${artifact.}, especially given the changes associated with the commit for MASSEMBLY-190, in revId: 698739.

            jdcasey John Dennis Casey added a comment - need to discuss the differences between ${module. } and ${artifact. }, especially given the changes associated with the commit for MASSEMBLY-190 , in revId: 698739.
            sgfan Michael Osipov added a comment -

            John Casey's comment refers to MASSEMBLY-309. Documentation should always refer to $module.<sub-property>.

            sgfan Michael Osipov added a comment - John Casey's comment refers to MASSEMBLY-309 . Documentation should always refer to $module.<sub-property>.

            the outputFileNameMapping documentation needs to be reviewed.

            jdcasey John Dennis Casey added a comment - the outputFileNameMapping documentation needs to be reviewed.
            tuomas_kiviaho Tuomas Kiviaho added a comment -

            Interpolation precedence,

            Current description of outputFileNameMapping did not give any clues that such prefixes as 'module.' 'artifact.' and 'pom.' existed. There aren't any examples of how to reference artifact at hand. outputDirectory has also similar extra features available, but they are not documented on site.

            I just spent some time to discover the semantics from within source code where they were well documented (org.apache.maven.plugin.assembly.utils.AssemblyFormatUtils) but for general documentation too technically oriented as-is. Following version removal example could be added to including-and-excluding-artifacts.apt

            <dependencySets>
            <dependencySet>
            ...
            <outputFileNameMapping>
            ${artifact.artifactId}${dashClassifier?}.${artifact.extension}
            </outputFileNameMapping>
            </dependencySet>
            ..
            </dependencySets>

            tuomas_kiviaho Tuomas Kiviaho added a comment - Interpolation precedence, Current description of outputFileNameMapping did not give any clues that such prefixes as 'module.' 'artifact.' and 'pom.' existed. There aren't any examples of how to reference artifact at hand. outputDirectory has also similar extra features available, but they are not documented on site. I just spent some time to discover the semantics from within source code where they were well documented (org.apache.maven.plugin.assembly.utils.AssemblyFormatUtils) but for general documentation too technically oriented as-is. Following version removal example could be added to including-and-excluding-artifacts.apt <dependencySets> <dependencySet> ... <outputFileNameMapping> ${artifact.artifactId}${dashClassifier?}.${artifact.extension} </outputFileNameMapping> </dependencySet> .. </dependencySets>

            Small doc issue

            In the Descriptor Format section on the site the description of moduleSet.binaries.outputFileNameMapping is:

            "Sets the mapping pattern for all dependencies included in this assembly. Default is ${artifactId}-${version}.${extension}."

            However this (also?) applies to the included binaries. In my use case I wanted to unpack a war to the basedir of the assembly, so I had includeDependencies set to false, unpack set to true. But I kept ending up with the unpacked war in a subdirectory. I didn't specify outputFileNameMapping cause includeDependencies was false and, after reading the documentation, had decided this property was no good to me... Took me a while to figure it out.

            bramk Bram de Kruijff added a comment - Small doc issue In the Descriptor Format section on the site the description of moduleSet.binaries.outputFileNameMapping is: "Sets the mapping pattern for all dependencies included in this assembly. Default is ${artifactId}-${version}.${extension}." However this (also?) applies to the included binaries. In my use case I wanted to unpack a war to the basedir of the assembly, so I had includeDependencies set to false, unpack set to true. But I kept ending up with the unpacked war in a subdirectory. I didn't specify outputFileNameMapping cause includeDependencies was false and, after reading the documentation, had decided this property was no good to me... Took me a while to figure it out.

            People

              jdcasey John Dennis Casey
              magnayn nigel magnay
              Votes:
              7 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: