Assembly Operations

All to elements refer to a path within the package.

Common Settings and Behaviour

Artifact Naming and Identification

Explain how the artifacts are looked up, groupId:artifactId[:classifier][:type] etc. Show examples of ZIP, WAR and TAR.GZ files.

File Name Rewriting

Includes and Excludes

Explain the difference between:

  • *.foo
  • **/*.foo

The order of includes vs excludes

TODO: Explain the effect of having a basedir-like parameter set when calculating matches. (the include/exclude expressions can't contain the basedir part). Applies only to set attributes for now.

File Attributes

  • user - specifies the user that owns the file
  • group - specifies the group that owns the file
  • mode - the read/write/executable modes on the file, specified in octal format. Examples
    • 0644 => -rw-r--r--
    • 0744 => -rwxr--r--

Assembly Operations

Copy File

Copies a single file.

Supported parameters:

  • file - the file to copy.
  • toFile/ toDir - the destination file or directory. Only one of these two can be specified. If toDir is used, the file will get the same name as the source file.
  • attributes - the attributes to set on the copied file. See File Attributes

Example: 

<copy-file>
  <file>src/main/native/myapp.so</file>
  <toFile>/opt/myapp/myapp.so</toFile>
  <attributes>
    <user>myapp</user>
    <group>myapp</group>
    <mode>0644</mode>
  </attributes>
</copy-file>

Copy Artifact

Copies an artifact from the local repository. It has to be specified as a dependency.

Supported parameters:

  • artifact - the artifact id of the file to copy. See Artifact Naming and Identification
  • toFile/ toDir - the destination file or directory. Only one of these two can be specified. If toDir is used, the file will get the same name as the source file.
  • attributes - the attributes to set on the copied file. See File Attributes

Example: 

<copy-artifact>
  <artifact>org.jvnet.hudson.main:hudson-war:war</artifact>
  <toFile>/opt/hudson/hudson.war</toFile>
  <attributes>
    <user>hudson</user>
    <group>hudson</group>
    <mode>0644</mode>
  </attributes>
</copy-artifact>

Mkdirs

Creates one or more directories with the specified attributes.

Supported parameters:

  • artifact - the artifact id of the file to copy. See Artifact Naming and Identification
  • path/ paths - the directory or directories to create. Only one of these two can be specified. If toDir is used, the file will get the same name as the source file.
  • attributes - the attributes to set on the direectories. See File Attributes

Example: 

<mkdirs>
  <paths>
    <path>/var/opt/jetty</path>
    <path>/var/opt/jetty/cache</path>
    <path>/var/opt/jetty/log</path>
  </paths>
  <attributes>
    <user>jetty</user>
    <group>jetty</group>
  </attributes>
</mkdirs>

Set Attributes

Changes the attributes on files and directories found. It will only look at files copied so far.

Supported parameters:

  • basedir - the base directory when applying. If not specified it defaults to the root of the package.
  • fileAttributes - the attributes to set on the matched files. See File Attributes
  • includes and excludes - controls files to include in the archive. The paths are relative to the basedir. See Includes and Excludes
  • directoryAttributes - the attributes to set on the matched direectories. See File Attributes

Example: 

<set-attributes>
  <basedir>/usr/share/hello/bin</basedir>
  <fileAttributes>
    <user>bah</user>
    <group>bah</group>
    <mode>0755</mode>
  </fileAttributes>
</set-attributes>

Symlink

Creates a symbolic link.

Supported parameters:

  • path - the file to create in the package.
  • value - where the symbolic link points to.

Copy Directory, Extract Artifact and Extract File

These operation work in a similar fasion and share these attributes:

  • to - the base destination directory.
  • includes and excludes - controls files to include in and exlucde from the package. See Includes and Excludes
  • pattern and replacement - controls rewriting of file names. See File Name Rewriting
  • fileAttributes - the attributes to set of any files copied. See File Attributes
  • directoryAttributes - the attributes to set of any directories copied. See the File Attributes

Copy Directory

Copies a complete directory structure.

Additional parameters:

  • from - The directory to copy from.

Example: 

<copy-directory>
  <from>target/appassembler</from>
  <to>/usr/share/hello</to>
</copy-directory>

Extract Artifact

Exctracts an artifact from the local repository. It has to be specified as a dependency. TODO: document the supported archive types. (at least zip, jar and war are supported)

Additional parameters:

Example: 

<extract-artifact>
  <artifact>org.mortbay.jetty:jetty-assembly:zip</artifact>
  <to>/opt/jetty</to>
</extract-artifact>

Extract File

Exctracts a file. TODO: document the supported archive types. (at least zip, jar and war are supported)

Additional parameters:

  • archive - The path to an archive to extract.

Example: 

<extract-file>
  <archive>src/main/extras.zip</archive>
  <to>/opt/share/myapp/extras</to>
</extract-file>