Documentation for the assembly plugin is utterly confusing
----------------------------------------------------------
Key: MASSEMBLY-151
URL: http://jira.codehaus.org/browse/MASSEMBLY-151
Project: Maven 2.x Assembly Plugin
Issue Type: Bug
Affects Versions: 2.1, 2.2
Reporter: Nigel Magnay
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).
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://jira.codehaus.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
