Skipping execution

The plugin execution is skipped automatically if the operating system is not linux. The plugin execution can be skipped explicitly by providing the system property skipDeb, and it is forced to run regardless the operating system if runDeb is provided. Example:

mvn -DskipDeb

Multi-module projects

The top-level module in multi-module projects usually only defines plugins, properties, etc, but does not actually contain any code that requires packaging. In order to avoid execution in the top-level module, you can use the skip parameter set to true:

<build>
  <plugins>
    ...

    <plugin>
      <groupId>com.github.fracpete</groupId>
      <artifactId>debian-maven-plugin</artifactId>
      <configuration>
        <skip>true</skip>
      </configuration>
    </plugin>
    ...
  </plugins>
</build>

And in the sub-modules, you set this flag to false:

<build>
  <plugins>
    ...

    <plugin>
      <groupId>com.github.fracpete</groupId>
      <artifactId>debian-maven-plugin</artifactId>
      ...
      <configuration>
        <skip>false</skip>
        ...
      </configuration>
    </plugin>
    ...
  </plugins>
</build>

Adding JARs (and other attached artifacts and dependencies)

By default, the project artifact, its dependencies, and attached artifacts are packaged. The project artifact and its dependencies can be excluded from the package by setting excludeAllArtifacts to true. The parameter excludeAllDependencies does the same, but only for dependencies. The inclusion of attached artifacts is governed by includeAttachedArtifacts. If includeArtifacts is provided, only those listed artifacts are included. The artifacts in excludeArtifacts (supplied in via nested <param></param> tags) are excluded from the Debian package. You can also supply regular expressions to exclude artifacts using excludeArtifactsRegExp (the actual regular expressions are supplied in nested <param></param> tags). Artifacts will be accompanied by a symbolic link, which enables reference without the version number.

For the project artifact and each of its dependencies, a file is created which lists all dependencies of the artifact. The name of this file is the artifact filename with its extension replaced by .inc. This is particularly useful for setting the classpath, e.g. from a shell script.

Adding man pages

The plugin searches for man page source files in the directory src/deb/man. The files are automatically compiled, using groff. The source files must be named pagename.N, where N is the section number. The compiled man pages are gzip'ed and included in the appropriate place in the deb file. Here are some pointers for help writing man pages:

• Wikipedia page on man pages: http://en.wikipedia.org/wiki/Man_page
• A short howto: http://www.linuxhowtos.org/System/creatingman.htm
• A somewhat more extensive howto: http://www.schweikhardt.net/man_page_howto.html

Adding other files

By default, the plugin only takes care of JARs. However, if you require additional resources to be part of your debian package (eg scripts in /usr/bin), then you can use the useDefaultCopyResources and copyResources parameters to achieve this.

With useDefaultCopyResources set to true, the plugin copies everything below src/deb/resources into the staging directory target/deb.

copyResources allows you to copy other files as well. Each of the nested copyResource tags is comprised of source, target and an optional include tags. Both, source and target can be directories or files. The include tag uses regular expressions for matching files to include in the copy process. If omitted, the match all pattern .* is assumed.

The following example applies the default copy rules and also copies PDF files from the target directory into target/deb/usr/share/doc/my-package to make them available in /usr/share/doc/my-package after installing the package.

<build>
  <plugins>
    ...

    <plugin>
      <groupId>com.github.fracpete</groupId>
      <artifactId>debian-maven-plugin</artifactId>
      <configuration>
        <packageName>my-package</packageName>
        <packageVersion>1.0.0</packageVersion>
        <useDefaultCopyResources>true</useDefaultCopyResources>
        <copyResources>
          <copyResource>
            <source>target</source>
            <target>target/deb/usr/share/doc/my-package</target>
            <include>.*\.pdf</include>
          </copyResource>
        </copyResources>
      </configuration>
    </plugin>
    ...
  </plugins>
</build>

Unfortunately, the copying does not retain Unix file permissions, meaning that all executable files lose their execution permission after copying. But you can use the useDefaultFixPermissions and fixPermissions parameters to counter this.

When useDefaultFixPermissions is set to true, then the plugin ensures that all scripts in the bin and sbin directories and the DEBIAN/pre and DEBIAN/post scripts are executable (using rwxr-xr-x).

fixPermissions allows you to change the permissions of other files and directories. Each of the nested fixPermission tags consists of the include regular expression to match against the full filename and permissions containing the ugo (user, group, other) permissions.

Here is an example that applies the default permission fixes and also ensures that the myscript script is executable as well:

<build>
  <plugins>
    ...

    <plugin>
      <groupId>com.github.fracpete</groupId>
      <artifactId>debian-maven-plugin</artifactId>
      <configuration>
        <packageName>my-package</packageName>
        <packageVersion>1.0.0</packageVersion>
        <useDefaultFixPermissions>true</useDefaultFixPermissions>
        <fixPermissions>
          <fixPermission>
            <include>.*myscript.*</include>
            <permissions>rwxr-xr-x</permissions>
          </fixPermission>
        </fixPermissions>
      </configuration>
    </plugin>
    ...
  </plugins>
</build>

Filtering files

By default, resource files are just copied across as is. However, in order to make start-up scripts more general, you can place variables (${varname}) in them and turn file filtering on in your configuration.

In terms of what variables are supported, there are two types: The first type being POM related ones, that start with project. like project.name or project.version. Sub-properties from properties in the POM that allow multiple values, like licenses can access these via [index], with the index being 0-based. The second type are ones specific to this plugin. Here is a list of supported variables:

packageName
packageTitle
packagePriority
packageSection
packageDescription
packageArchitecture
packageRevision

Considering the following configuration for file filtering:

...

<licenses>
  <license>
    <name>GNU General Public License 3</name>
    <url>http://www.gnu.org/licenses/gpl-3.0.txt</url>
  </license>
  <license>
    <name>Apache 2.0</name>
    <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
  </license>
</licenses>

...

<build>
  <plugins>
    ...

    <plugin>
      <groupId>com.github.fracpete</groupId>
      <artifactId>debian-maven-plugin</artifactId>
      <configuration>
        <packageName>my-package</packageName>
        <packageVersion>1.0.0</packageVersion>
        <fileFiltering>
          <enabled>true</enabled>
          <include>.*</include>
          <excluded>.*\.(jpg|jpeg|png|svg|zip|jar|pdf)</excluded>
        </fileFiltering>
      </configuration>
    </plugin>
    ...
  </plugins>
</build>

When applied to the following snippet of a bash script (the blank between $ and { was required for display purposes):

...
# Licenses
# - $ {project.licenses[0].name}
# - $ {project.licenses[1].name}

CLASSPATH_DIR=/usr/lib/${packageName}
...

Will yield this output:

# Licenses
# - GNU General Public License 3
# - Apache 2.0

CLASSPATH_DIR=/usr/lib/my-package