Now that we’ve made it through the main body of the assembly descriptor, we can close the discussion of content-related descriptor sections with something lighter: root-directory naming and site-directory handling.
Some may consider it a stylistic concern, but it’s often important
to have control over the name of the root directory for your assembly,
or whether the root directory is there at all. Fortunately, two
configuration options in the root of the assembly descriptor make
managing the archive root directory simple:
includeBaseDirectory and
baseDirectory. In cases like executable jar files,
you probably don’t want a root directory at all. To skip it, simply set
the includeBaseDirectory flag to
false (it’s true by default). This
will result in an archive that, when unpacked, may create more than one
directory in the unpack target directory. While this is considered bad
form for archives that are meant to be unpacked before use, it’s not so
bad for archives that are consumable as-is.
In other cases, you may want to guarantee the name of the archive
root directory regardless of the POM’s version or
other information. By default, the baseDirectory
element has a value equal to
content-zh-0.5. However, we
can easily set this element to any value that consists of literal
strings and expressions which can be interpolated from the current
POM, such as
org.sonatype.mavenbook-content-zh. This could
be very good news for your documentation team! (We all have those,
right?)
Another configuration available is the
includeSiteDirectory flag, whose default value is
false. If your project build has also constructed a
website document root using the site lifecycle or the Site plugin goals,
that output can be included by setting this flag to
true. However, this feature is a bit limited, since
it only includes the outputDirectory from the
reporting section of the current POM (by default,
target/site) and doesn’t take into consideration
any site directories that may be available in module projects. Use it if
you want, but a good fileSet specification or
moduleSet specification with sources configured could
serve equally well, if not better. This is yet another example of legacy
configuration currently supported by the Assembly plugin for the purpose
of backward compatibility. Your mileage may vary. If you really want to
include a site that is aggregated from many modules, you'll want to
consider using a fileSet or
moduleSet instead of setting
includeSiteDirectory to
true.
