Usage

Plugin configuration

You should specify the version in your project's plugin configuration:

<project>
  ...
  <build>
    <!-- To use the plugin goals, add the following in your POM or parent POM -->
    <plugins>
      <plugin>
        <groupId>net.sf.debian-maven</groupId>
        <artifactId>debian-maven-plugin</artifactId>
        <version>1.0.6</version>
        <configuration>
          <!--
          <packageName>my-package</packageName>
          <packageVersion>1.0.0</packageVersion>
          ...
          -->
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

The plugin accepts the following configuration parameters (most of them have reasonable default values):

POM settingCommand line argumentDescriptionData typeDefault value
packageNamedeb.package.namePackage nameString ${project.artifactId}
packageVersiondeb.package.versionPackage versionString ${project.version}
packageRevisiondeb.package.revisionPackage revisionString1
packagePrioritydeb.package.priorityInstallation priorityStringoptional
packageSectiondeb.package.sectionRepository sectionStringcontrib/utils
packageTitledeb.package.titleShort package descriptionString ${project.name}
packageDescriptiondeb.package.descriptionExtended package descriptionString ${project.description}
snapshotRevisionFiledeb.package.snapshotRevFileWhen building snapshot packages, append the modification time of this file to the version number.FileThe default is to use the system time.
packageDependenciesDependencies to other packagesString[]
projectUrldeb.project.urlProject websiteString ${project.organization.url}
projectOrganizationdeb.project.organizationOrganization for Debian control fileString ${project.organization.name}
maintainerNamedeb.maintatier.namePackage maintainer's nameString ${project.developers[0].name}
maintainerEmaildeb.maintatier.emailPackage maintainer's email addressString ${project.developers[0].email}
includeArtifactsArtifacts to be included, identified by their filenames.String[]The project artifact and its dependencies.
excludeArtifactsArtifacts to be excluded (takes precedence over includeArtifacts).String[]
excludeAllArtifactsExclude all regular artifacts (attached artifacts are not affected)Booleanfalse
excludeAllDependenciesExclude all dependenciesBooleanfalse
includeAttachedArtifactsInclude all attached artifacts.Booleantrue
repositorydeb.repository.locationLocation of the Debian repositoryFile
repositoryBranchdeb.repository.branchThe codename of the distribution branch (e.g., lenny, natty, etc.)Stringexperimental
repreproConfigurotionDirdeb.reprepro.configReprepro configuration directoryFile
skipDeployMissingdeb.deploy.skipMissingSkip package deployment if the package does not existBooleantrue

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

Adding package content

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 are excluded from the Debian package. 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:

Adding other files

The plugin does not take care of files other than JARs. However, it can be used in conjunction with other plugins to take care of that. The stage directory for the Debian package is target/deb, so any files copied into that directory during the build process are included in the Debian package.

I recommend the Maven Resources Plugin to copy resources into the stage directory. The following is an example configuration.

<build>
  <plugins>
    ...

    <plugin>
      <!--
        This plugin's configuration must come *before* the Debian Maven
        Plugin.
      -->
      <artifactId>maven-resources-plugin</artifactId>
      <version>2.3</version>
      <executions>
        <execution>
          <id>copy-deb-resources</id>
          <phase>process-resources</phase>
          <goals><goal>copy-resources</goal></goals>
          <configuration>
            <overwrite>true</overwrite>
            <outputDirectory>${basedir}/target/deb</outputDirectory>
            <resources>
              <resource>
                <directory>src/deb/resources</directory>
                <!-- Uncomment the following line to enable Velocity filtering. -->
                <!--
                <filtering>true</filtering>
                -->
              </resource>
            </resources>
          </configuration>
        </execution>
      </executions>
    </plugin>

    ...
  </plugins>
</build>

IMPORTANT: plugins in the same phase run in the order in which they are mentioned in the POM. This means that the Maven Resources Plugin must be included above the Debian Maven Plugin!

Unfortunately, the Maven Resources Plugin does not retain Unix file permissions, meaning that all executable files lose their execution permission after copying. A workaround is to use the Maven Antrun Plugin to re-enable execution of all relevant files. An example configuration to do so is the following:

<build>
  <plugins>
    ...

    <plugin>
      <!--
        This plugin's configuration must come *after* the Maven Resources
        Plugin, and *before* the Debian Maven Plugin.
      -->
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-antrun-plugin</artifactId>
      <version>1.6</version>
      <executions>
        <execution>
          <id>fix-permissions</id>
          <phase>package</phase>
          <configuration>
            <target>
              <chmod perm="ugo+x">
                <fileset dir="${basedir}/target/deb">
                  <include name="**/bin/**"/>
                  <include name="**/sbin/**"/>
                  <include name="DEBIAN/post*"/>
                  <include name="DEBIAN/pre*"/>
                </fileset>
              </chmod>
            </target>
          </configuration>
          <goals><goal>run</goal></goals>
        </execution>
      </executions>
    </plugin>

    ...
  </plugins>
</build>

Deploying

The plugin can use reprepro to deploy the Debian package to a local reprepro repository. The plugin assumes an existing reprepro repository and configuration, and requires pointers to their locations. The plugin uses the following parameters:

  • repository (path to the repository; ex: /path/to/repo)
  • repreproConfigurationDir (the reprepro configuration directory)
  • repositoryBranch (optional)
  • skipDeployMissing (optional)

Note: when the package version has the substring -SNAPSHOT, it is replaced by the modification time of the file pom.xml. This way, each change of the POM causes an increase of the version number, which is useful as reprepro does not allow you to deploy an update with the same version number.