sbt-pack plugin

A sbt plugin for creating distributable Scala packages that include dependent jars and launch scripts.

Features

• sbt pack

  creates a distributable package in

  target/pack

  folder.
  • All dependent jars including scala-library.jar are collected in

    target/pack/lib

    folder. This process is much faster than creating a single-jar as in

    sbt-assembly

    or

    proguard

    plugins.
  • Supporting multi-module projects.
  • Useful for creating runnable Docker images of Scala programs

• sbt packArchive

  generates

  tar.gz

  archive that is ready to distribute.
  • The archive name is

    target/{project name}-{version}.tar.gz

• sbt pack

  generates program launch scripts

  target/pack/bin/{program name}

  • To run the program no need exists to install Scala, since it is included in the lib folder. Only java command needs to be found in the system.
  • It also generates

    .bat

    launch scripts for Windows users.
• Generates a Makefile for program installation.
  • Do

    cd target/pack; make install

    . Then you can run your program with

    ~/local/bin/{program name}

• You can install multiple versions of your program in the system.
  • The above Makefile script uses a separate folder for each version (e.g.,

    ~/local/{project name}/{project version}

    ).
  • The latest version is linked from

    ~/local/{project name}/current

• You can add other resources in

  src/pack

  folder.
  • All resources in this folder will be copied to

    target/pack

    .

• Check duplicated classes in dependencies.

• Release Notes

Usage

Add

sbt-pack

project/plugins.sbt

// for sbt-0.13.x, sbt-1.x
addSbtPlugin("org.xerial.sbt" % "sbt-pack" % "(version)")  

Repository URL: http://repo1.maven.org/maven2/org/xerial/sbt/

Minimum configuration

build.sbt ``` // [Required] Enable plugin and automatically find def main(args:Array[String]) methods from the classpath enablePlugins(PackPlugin)

// [Optional] Specify main classes manually // This example creates

hello

Now you can use

sbt pack

Full build configuration

sbt-pack will generate launcher scripts for calling

def main(args:Array[String]): Unit

packMain

packMain := Map("hello" -> "myprog.Hello")

target/pack/bin/hello

myprog.Hello

If

packMain

def main(args:Array[])

myprog.ExampleProg

example-prog

build.sbt

// [Required] Enable plugin and automatically find def main(args:Array[String]) methods from the classpath
enablePlugins(PackPlugin)

name := "myprog"
base := file(".")
// [Optional] Specify mappings from program name -> Main class (full package path). If no value is set, it will find main classes automatically
packMain := Map("hello" -> "myprog.Hello")
// [Optional] JVM options of scripts (program name -> Seq(JVM option, ...))
packJvmOpts := Map("hello" -> Seq("-Xmx512m"))
// [Optional] Extra class paths to look when launching a program. You can use ${PROG_HOME} to specify the base directory
packExtraClasspath := Map("hello" -> Seq("${PROG_HOME}/etc")) 
// [Optional] (Generate .bat files for Windows. The default is true)
packGenerateWindowsBatFile := true
// [Optional] jar file name format in pack/lib folder
//   "default"   (project name)-(version).jar 
//   "full"      (organization name).(project name)-(version).jar
//   "no-version" (organization name).(project name).jar
//   "original"  (Preserve original jar file names)
packJarNameConvention := "default",
// [Optional] Patterns of jar file names to exclude in pack
packExcludeJars := Seq("scala-.*\.jar")
// [Optional] Generate a text file containing the list of copied jars.
packJarListFile := Some("lib/jars.mf")
// [Optional] List full class paths in the launch scripts (default is false) (since 0.5.1)
packExpandedClasspath := false
// [Optional] Resource directory mapping to be copied within target/pack. Default is Map("{projectRoot}/src/pack" -> "") 
packResourceDir += (baseDirectory.value / "web" -> "web-content")
// To publish tar.gz, zip archives to the repository, add the following lines:
import xerial.sbt.pack.PackPlugin._
publishPackArchives
// Publish only tar.gz archive. To publish another type of archive, use publishPackArchive(xxx) instead
//publishPackArchiveTgz

src/main/scala/Hello.scala

package myprog

object Hello {
  def main(args:Array[String]) = {
    println("Hello World!!")
  }
}

Command Examples

Create a package

$ sbt pack

Your program package will be generated in

target/pack

Launch a command

$ target/pack/bin/hello
Hello World!!

Install the command

Install the command to

$(HOME)/local/bin

$ sbt packInstall

or

$ cd target/pack; make install

To launch the command:

    $ ~/local/bin/hello
    Hello World!

Add the following configuration to your .bashprofile, .zshprofile, etc. for the usability:

export PATH=$(HOME)/local/bin:$PATH

Install the command to the system

$ cd target/pack
$ sudo make install PREFIX="/usr/local"
$ /usr/local/bin/hello
Hello World!

Create a tar.gz archive of your Scala program package

$ sbt packArchive

Copy dependencies

The

packCopyDependencies

packCopyDependenciesTarget

By default, a symbolic link will be created. By setting

packCopyDependenciesUseSymbolicLinks

false

It can be used e.g. for copying dependencies of a webapp to

WEB-INF/lib

See an example project.

Example projects

See also examples folder in the source code. It contains several Scala project examples using sbt-pack.

Use case

• scala-min: A minimal Scala project using sbt-pack: https://github.com/xerial/scala-min
  • A minimal project to start writing Scala programs.

Building A Docker image file with sbt-pack

Building a docker image of Scala application becomes easier with sbt-pack:

build.sbt

scala
enablePlugins(PackPlugin)
name := "myapp"
packMain := Map("myapp"->"org.yourdomain.MyApp")

Dockerfile ```

Using an Alpine Linux based JDK image

FROM anapsix/alpine-java:8u131b11_jdk

COPY target/pack /srv/myapp

Using a non-privileged user:

USER nobody WORKDIR /srv/myapp

ENTRYPOINT ["sh", "./bin/myapp"] ```

Then you can build a docker image of your project: ``` $ sbt pack $ docker build -t your_org/myapp:latest .

Run your application with Docker

$ docker run -it --rm your_org/myapp:latest (command line arg...) ```

For developers

To test sbt-pack plugin, run

$ ./sbt scripted

Run a single test project, e.g.,

src/sbt-test/sbt-pack/multi-module

$ ./sbt "scripted sbt-pack/multi-module"

For releasing:

$ ./sbt
# cross tests for sbt 0.13 and 1.1
> ^ scripted
> ^ publishSigned
> sonatypeReleaseAll