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.
- 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.
- 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.
- 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
- 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.
- 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.
Separation of concerns with two kinds of plugins
- format plugins define how a package is created
- archetype plugins define what a package should contain
Mappings define how your build files should be organized on the target system.
Mappings
are aSeq[(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:
- Provide a new configuration scope
- Formats define their own configuration scope to be able to customize every shared setting or task.
- 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.
- Implement package task
packageBin
orpublishLocal
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:
- Archetype related settings and tasks
- 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
When using the full power of the plugin, all of the packaging is driven from the mappings in Universal
setting,
which defines what files will be included in the package. These files are automatically moved around for the appropriate
native packaging as needed.