Skip to main content
Version: 2.1.26

bootstrap

bootstrap creates binary launchers from one or more dependencies.

$ cs bootstrap org.scalameta::scalafmt-cli:2.4.2 -o scalafmt
$ ./scalafmt --version
scalafmt 2.4.2

Launcher types​

Bootstraps​

This is the default. When generating a launcher like

$ cs bootstrap scalafmt -o scalafmt
$ ls -lh scalafmt
-rwxr-xr-x 1 user group 26K apr 8 23:28 scalafmt
$ ./scalafmt --version
scalafmt 2.4.2

the generated scalafmt file is a JAR containing a tiny Java application, along with a URL list as a resource (the URLs of the JARs of scalafmt, in coursier/bootstrap/launcher/bootstrap-jar-urls).

$ unzip -c scalafmt coursier/bootstrap/launcher/bootstrap-jar-urls
https://repo1.maven.org/maven2/com/geirsson/junit-interface/0.11.9/junit-interface-0.11.9.jar
https://repo1.maven.org/maven2/com/geirsson/metaconfig-core_2.13/0.9.8/metaconfig-core_2.13-0.9.8.jar
https://repo1.maven.org/maven2/com/geirsson/metaconfig-typesafe-config_2.13/0.9.8/metaconfig-typesafe-config_2.13-0.9.8.jar
https://repo1.maven.org/maven2/com/github/scopt/scopt_2.13/3.7.1/scopt_2.13-3.7.1.jar
…

It also contains a shell preamble, that basically calls java -jar $0, so that scalafmt is self-executable.

$ head -25 scalafmt
#!/usr/bin/env sh

…
set -- "$@" -jar "$0"
…
exec java $JAVA_OPTS "$@"

Running it calls java on the script itself, which starts the tiny Java application mentioned above. That application reads the URL list, and ensures all of these are available in the coursier cache (it downloads them if necessary). It then loads them from the coursier cache in a java.net.URLClassLoader, and starts the actual application from it.

Standalone bootstraps​

These are very similar to simple bootstraps above, except they are more heavyweight, as they embed all the JARs of the application:

$ cs bootstrap scalafmt --standalone -o scalafmt
$ ls -lh scalafmt
-rwxr-xr-x 1 user group 35M apr 8 23:41 scalafmt

Here, scalafmt contains the same tiny Java application as above, along with the same shell preamble to make it self-executable. Unlike simple bootstraps, it doesn't contain a URL list, but contains all the scalafmt JARs as resources, under coursier/bootstrap/launcher/jars/:

$ unzip -l scalafmt
…
168411 02-23-2020 00:06 coursier/bootstrap/launcher/jars/scalafmt-cli_2.13-2.4.2.jar
5721063 09-18-2019 08:59 coursier/bootstrap/launcher/jars/scala-library-2.13.1.jar
1119106 02-23-2020 00:06 coursier/bootstrap/launcher/jars/scalafmt-core_2.13-2.4.2.jar
136879 02-23-2020 00:06 coursier/bootstrap/launcher/jars/scalafmt-dynamic_2.13-2.4.2.jar
…

It also contains a resource list, in coursier/bootstrap/launcher/bootstrap-jar-resources:

$ unzip -c scalafmt coursier/bootstrap/launcher/bootstrap-jar-resources
common_2.13-4.3.0.jar
config-1.4.0.jar
diffutils-1.3.0.jar
fansi_2.13-0.2.7.jar
fastparse-utils_2.13-1.0.1.jar
…

When running scalafmt, instead of loading URLs via the coursier cache, the tiny startup Java application loads JARs from this list via its own resources. That makes these standalone bootstrap runnable even with no network connection and an empty coursier cache. They are more heavyweight, as they embed the full class path of the application to start.

Standalone bootstraps are very similar to the JARs generated by One-JAR.

Manifest-based launchers​

These are even more lightweight than standard bootstraps, but are only meant to be used by the same user / on the same machine.

$ cs bootstrap scalafmt --manifest-jar -o scalafmt
$ ls -lh scalafmt
-rwxr-xr-x 1 alexandre staff 1,6K 8 avr 23:53 scalafmt

These are also a JAR, and contain the same shell preamble as standard and standalone bootstraps. As a JAR, they contain only one file:

$ unzip -l scalafmt
Length Date Time Name
--------- ---------- ----- ----
4686 04-08-2020 21:53 META-INF/MANIFEST.MF
--------- -------
4686 1 file

That only file is the JAR manifest. It contains a Class-Path field, listing the paths to the application JAR in the local coursier cache:

$ unzip -c scalafmt META-INF/MANIFEST.MF
Manifest-Version: 1.0
Class-Path: /Users/alexandre/.coursier/cache/v1/https/repo1.maven.org/
maven2/org/scalameta/scalafmt-cli_2.13/2.4.2/scalafmt-cli_2.13-2.4.2.
jar /Users/alexandre/.coursier/cache/v1/https/repo1.maven.org/maven2/
org/scala-lang/scala-library/2.13.1/scala-library-2.13.1.jar /Users/a
…
Main-Class: org.scalafmt.cli.Cli

Upon start-up, java loads the JARs from the Class-Path field, and starts the main class from Main-Class.

Assemblies​

bootstrap can generate assemblies, aka "fat" JARs:

$ cs bootstrap scalafmt --assembly -o scalafmt
$ ls -lh scalafmt
-rwxr-xr-x 1 user group 35M apr 9 00:12 scalafmt

Assemblies merge together the JARs of the application, so that they form a single large JAR.

$ unzip -l scalafmt
Length Date Time Name
--------- ---------- ----- ----
59 04-08-2020 22:11 META-INF/MANIFEST.MF
0 02-23-2020 00:05 org/
0 02-23-2020 00:05 org/scalafmt/
0 02-23-2020 00:05 org/scalafmt/cli/
944 02-23-2020 00:05 org/scalafmt/cli/Cache.class
2046 02-23-2020 00:05 org/scalafmt/cli/Terminal.class
…

bootstrap puts the same preamble as standard bootstraps in assemblies

$ head -25 scalafmt
#!/usr/bin/env sh

…
set -- "$@" -jar "$0"
…
exec java $JAVA_OPTS "$@"

Some of the application JARs may contain files with the same path. When merging those JARs, these conflicting files have to be either merged, or discarded. bootstrap has a default set of sensible "rules" handling the most common cases. These can be disabled with --default-assembly-rules=false. Custom rules can be passed with --assembly-rule, like

$ cs bootstrap scalafmt --assembly -o scalafmt --assembly-rule exclude:logback.xml

See cs bootstrap --help for the format of the rules accepted by --assembly-rule.

Relocating classes​

When generating an assembly, classes can be relocated ("shaded"), so that the classes of a dependency end up under a different package in the resulting JAR. This is useful to avoid clashes when the assembly is meant to be used as a library alongside other versions of its dependencies. This relies on jarjar-abrams, like sbt-shading.

Pass --relocate from=to to move every class under the from package to be under the to package (references to the moved classes are rewritten too):

$ cs bootstrap io.get-coursier:echo:1.0.1 --assembly -o echo \
--relocate coursier.echo=shaded.coursier.echo \
-M shaded.coursier.echo.Echo

Alternatively, --relocate move-under:from=to moves the from package under to (that is, from.Foo becomes to.from.Foo).

--relocate can only be used along with --assembly.

GraalVM native-image​

bootstrap can generate native executables via GraalVM native image, like

$ cs bootstrap echo-java --native-image -o echo
$ ls -lh echo
-rwxr-xr-x 1 user group 2,8M apr 9 00:49 echo
$ ./echo foo
foo

This command automatically fetches and extracts a GraalVM Community edition archive, like the java command of coursier does, then uses it to call native-image.

You can pass an explicit GraalVM version via --graalvm-version or --graalvm, like

$ cs bootstrap echo-java --native-image --graalvm 19.3 -o echo

Note that this option accepts short versions. So as of writing this, 19.3 gets automatically expanded to 19.3.1.

You can pass custom options to native-image via --graalvm-option or --graalvm-opt, or after a --, like

$ cs bootstrap echo-java --native-image --graalvm 19.3 -o echo \
--graalvm-opt --no-fallback \
-- \
--enable-all-security-services \
--initialize-at-build-time

Note that it can be more convenient to pass arguments to native-image via a native-image.properties resource rather than on the command-line, if adding it to the original application sources is an option for you.

Scala native​

bootstrap can generate Scala Native-based native launchers:

$ cs bootstrap echo-native -o echo --native
[info] Linking (1457 ms)
[info] Discovered 614 classes and 4200 methods
[info] Optimizing (debug mode) (2157 ms)
[info] Generating intermediate code (1657 ms)
[info] Produced 4 files
…
[info] Linking native code (immix gc, none lto) (207 ms)
[info] Total (13172 ms)
Wrote …/echo
$ ls -lh echo
-rwxr-xr-x 1 user group 1,6M apr 9 00:57 echo

Note that this requires coursier to be launched via its JVM launcher. Install it with cs install coursier, or replace coursier in the command above with cs launch coursier --, like

$ cs launch coursier -- bootstrap echo-native -o echo --native

This requires the application you want a launcher for to be cross-compiled to Scala Native, and its Scala Native artifacts to be published to Maven or Ivy repositories. The echo project of coursier has such a module, published as io.get-coursier:echo_native0.3_2.11.

In order to generate a launcher for such a published application, you'll need to have your environment set up for Scala Native.

Linking flags during the linking phase can be adjusted via LDFLAGS in the environment.

Notes​

Local artifacts​

When generating standard bootstraps, some of the JARs may come from local repositories, like ~/.ivy2/local. The URL of these is like file:///home/user/.ivy/local/org/name/0.1/jars/name.jar. Relying on those URLs, which are specific to the current machine / user, would make the bootstrap non-portable. To circumvent that, such local artifacts are embedded as resources in the bootstraps, like standalone bootstraps do. That makes the generated bootstraps slightly more heavyweight, but also more portable. If you wish to disable that behavior, pass --embed-files=false when generating the bootstrap, like

$ cs bootstrap scalafmt:2.0.5-SNAPSHOT -o scalafmt --embed-files=false

Preamble​

If you wish standard bootstraps, standalone bootstraps, assemblies, not to contain a shell preamble, disable the preamble with --preamble=false, like

$ cs bootstrap scalafmt -o scalafmt --preamble=false
$ ./scalafmt # not self-executable anymore
zsh: exec format error: ./scalafmt
$ java -jar scalafmt --version
scalafmt 2.4.2

Java options​

Standard bootstraps, standalone bootstraps, and assemblies, with the default shell preamble, automatically pass their arguments starting with -J to Java, stripping the leading -J, like

$ cs bootstrap ammonite -o amm
$ ./amm -J-Dfoo=bar
Loading...
Welcome to the Ammonite Repl 2.0.4 (Scala 2.13.1 Java 1.8.0_121)
@ sys.props("foo")
res0: String = "bar"

Alternatively, one can hard-code Java options when generating these launchers, --java-opt, like

$ cs bootstrap ammonite -o amm \
--java-opt -Dfoo=bar
$ ./amm
Loading...
Welcome to the Ammonite Repl 2.0.4 (Scala 2.13.1 Java 1.8.0_121)
@ sys.props("foo")
res0: String = "bar"

Windows​

Standard bootstraps, standalone bootstraps, and assemblies, generate launchers with a shell preamble. These can't be run as-is from the Windows terminal. When generating those on Windows, a .bat file is automatically generated along them, like

> cs bootstrap scalafmt -o scalafmt
> dir
…
scalafmt
scalafmt.bat
…

If both files are present, the launcher can be run directly, like

> scalafmt --version
scalafmt 2.4.2

If you wish to generate that .bat file on Linux or macOS, pass --bat=true, like

$ cs bootstrap scalafmt -o scalafmt --bat=true
Wrote .../scalafmt
Wrote .../scalafmt.bat
$ ls -lh
-rwxr-xr-x 1 user group 26K apr 9 00:30 scalafmt
-rw-r--r-- 1 user group 2,1K apr 9 00:30 scalafmt.bat

Inversely, disable generating it on Windows with --bat=false.

> cs bootstrap scalafmt -o scalafmt --bat=false
> dir
…
scalafmt
…
> scalafmt & :: no bat file, doesn't work anymore