Introduction

SBT native packager lets you build application packages in native formats and offers different archetypes for common configurations, such as simple Java apps or server applications.

This section provides a general overview of native packager and its core concepts. If you want a quick start, go to the getting started section. However we recommend understanding the core concepts, which will help you to get started even quicker.

Goals

Native packager defines project goals in order to set expectations and scope for this project.

  1. Native formats should build on their respective platform

    This allows native packager to support a wide range of formats as the packaging plugin serves as a wrapper around the actual packaging tool. However, alternative packaging plugins maybe provided if a java/scala implementation exists. As an example debian packages should always build on debian systems, however native packager provides an additional plugin that integrates JDeb for a platform independent packaging strategy.

  2. Provide archetypes for zero configuration builds

    While packaging plugins provide the how a package is created, archetypes provide the configuration for what gets packaged. Archetypes configure your build to create a package for a certain purpose. While an archetype may not support all packaging formats, it should work without configuration for the supported formats.

  3. Enforce best-practices

    There is no single way to create a package. Native packager tries to create packages following best practices, e.g. for file names, installation paths or script layouts.

Scope

While native packager provides a wide range of formats and archetype configurations, its scope is relatively narrow. Native packager only takes care of packaging, the act of putting a list of mappings (source file to install target path) into a distinct package format (zip, rpm, etc.).

Archetypes like Java Application Archetype or Java Server Application Archetype only add additional files to the mappings enriching the created package, but they don’t provide any new features for native-packager core functionality. Much like the packaging format plugins, the archetypes rely on functionality already available on your deploy target.

These things are out of native packagers scope

  1. Providing application lifecyle management.

    The Java Server Application Archetype provides configurations for common system-loaders like SystemV, Upstart or SystemD. However creating a custom solution which includes stop scripts, PID management, etc. are not part of native packager.

  2. Providing deployment configurations

    Native packager produces artifacts with the packageBin task. What you do with these is part of another step in your process.

Core Concepts

Native packager is based on a few simple concepts. If you understand these, you will be able to customize your build, create own packaging formats and deploy more effectively.

  1. Separation of concerns with two kinds of plugins

  2. Mappings define how your build files should be organized on the target system.

    Mappings are a Seq[(File, String)], which translates to “a list of tuples, where each tuple defines a source file that gets mapped to a path on the target system”.

The following sections describe these concepts in more detail.

Format Plugins

Format plugins provide the implementation to create package, the how a package is created. For example the Debian Plugin provides a way to package debian packages. Each format plugin has its own documentation. Each plugin provides a common set of features:

  1. Provide a new configuration scope

    Formats define their own configuration scope to be able to customize every shared setting or task.

  2. Provide package format related settings and tasks

    Each format plugin may add additional settings or tasks that are only used by this plugin. Normally these settings start with the plugin name, e.g. rpmXYZ.

  3. Implement package task

    packageBin or publishLocal tasks provide the actual action to create a package.

By enabling a format plugin only with

enablePlugins(SomePackageFormatPlugin)

the resulting package will be empty because a format plugin doesn’t provide any configuration other than the default settings for the format plugin’s specific settings.

Archetype Plugins

While format plugins provide the how, archetypes provide the what gets packaged. An archetype changes the configuration in all supported package format scopes; they don’t add configuration scopes.

A full list of archetypes can be found here.

An archetype may provide the following:

  1. Archetype related settings and tasks

  2. New files in your package

By enabling an archetype plugin with

enablePlugins(SomeArchetypePlugin)

all configuration changes will be applied as well as all supported format plugins will be enabled.

Tip

An archetype plugin should be the starting point for creating packages!

Mappings

Mappings are the heart of native packager. This task defines what files in your build should be mapped where on the target system. The type signature for the mappings task is

mappings: TaskKey[Seq[(File, String)]]

The file part of the tuple must be available during the packaging phase. The String part represents the path inside the installation directory.

The Universal Plugin represents the base for all other plugins. It has a big section on how to customize mappings.

Architecture

The architecture can be summarized with this diagram

Architecture diagram.

When using the full power of the plugin, all of the packaging is driven from the Universal / mappings setting, which defines what files will be included in the package. These files are automatically moved around for the appropriate native packaging as needed.