Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

78 lines (56 sloc) 6.32 KB
= Launcher Specification =
The sbt launcher component is a self-contained jar that boots a Scala application without Scala or the application already existing on the system. The only prerequisites are the launcher jar itself, an optional configuration file, and a java runtime version 1.5 or greater.
== Configuration ==
The launcher may be configured in the following ways in increasing order of precedence:
* Replace the /sbt/sbt.launch.config file in the jar
* Put a configuration file named sbt.launch.config file on the classpath. Put it in the classpath root without the /sbt prefix.
* Specify the location of an alternate configuration on the command line. The alternate configuration option is specified as the first argument to the launcher. This option is the path to the configuration file preceeded by '@'. Resolution of a relative path is first attempted against the current working directory, then against the user's home directory, and then against the directory containing the launcher jar. An error is generated if none of these attempts succeed.
The configuration file is read as UTF-8 encoded and is defined by the following grammer (nl is a newline or end of file):
configuration ::= scala app repositories boot log
scala ::= '[' 'scala' ']' nl versionSpecification nl
app ::= '[' 'app' ']' nl org nl name nl versionSpecification nl components nl class nl cross-versioned nl
repositories ::= '[' 'repositories' ']' nl (repository nl)*
boot ::= '[' 'boot' ']' nl directory nl properties nl
log ::= '[' log ']' nl logLevel nl
directory ::= 'directory' ':' path
properties ::= 'properties' ':' path
logLevel ::= 'log-level' ':' ('debug' | 'info' | 'warn' | 'error')
versionSpecification ::= 'version' ':' ( ( ('read'|'prompt'|'read-or-prompt') [defaultVersion] ) | fixedVersion )
defaultVersion ::= text
fixedVersion ::= text
org ::= 'org' ':' text
name ::= 'name' ':' text
class ::= 'class' ':' text
components ::= 'components' ':' component (',' component)*
cross-versioned ::= 'cross-versioned' ':' ('true' | 'false')
repository ::= ( predefinedRepository | ( label ':' url [',' pattern] ) ) nl
predefinedRepository ::= 'local' | 'maven-local' | 'maven-central' | 'scala-tools-releases' | 'scala-tools-snapshots'
The default configuration file for sbt looks like:
version: read-or-prompt, 2.7.5
org: org.scala-tools.sbt
name: xsbt
version: read-or-prompt, 0.7.0_13
class: xsbt.Main
components: xsbti, default
cross-versioned: true
Sbt Repository,, [revision]/[type]s/[artifact].[ext]
directory: project/boot
properties: project/
level: info
The scala.version property specifies the version of Scala used to run the application. The,, and app.version properties specify the organization, module ID, and version of the application, respectively. These are used to resolve and retrieve the application from the repositories listed in [repositories]. If cross-versioned is true, the resolved module is {'_'+scala.version}
The app.class property specifies the name of the entry point to the application. An application entry point must be a public class with a no-argument constructor and conform to xsbti.SbtMain. The SbtMain interface specifies the entry method signature 'run'. The run method is passed an instance of SbtConfiguration, which provides access to the startup environment.
== Execution ==
On startup, the launcher searches for its configuration in the order described in the Configuration section and then parses it. If either the Scala version or the application version are implicit (read, prompt, or read-or-prompt), the launcher determines them in the following manner. If the implicit is specified to be 'read', the file given by '' is read as a Java properties file to obtain the version. The property names are [name].version for the application version (where [name] is replaced with and scala.version for the Scala version. If the file does not exist, the default value provided is used. If no default was provided, an error is generated. If the implicit is 'prompt', the user is prompted for the version to use and is provided a default option if one was specified. If the implicit is 'read-or-prompt', the file given by '' is read. If the version is not specified there, the user is prompted and is provided a default option if one was specified. The '' file is updated with the value specified by the user.
Once the final configuration is resolved, the launcher proceeds to obtain the necessary jars to launch the application. The '' property is used as a base directory to retrieve jars to. No locking is done on the directory, so it should not be shared system-wide. The launcher retrieves the requested version of Scala to []/[scala.version]/lib/. If this directory already exists, the launcher takes a shortcut for performance and assumes that the jars have already been downloaded. If the directory does not exists, the launcher uses Apache Ivy to resolve and retrieve the jars. A similar process occurs for the application itself. It and its dependencies are retreived to []/[scala.version]/[]/[]/.
Once all required code is downloaded, the class loaders are set up. The launcher creates a class loader for the requested version of Scala. It then creates a child class loader containing the jars for the requested 'app.components'. An application that does not use components will have all of its jars in this class loader.
The main class for the application is then instantiated. It must be a public class with a public no-argument constructor and must conform to xsbti.AppMain. The `run` method is invoked and execution passes to the application. The argument to the 'run' method provides configuration information and a callback to obtain a class loader for any version of Scala that can be obtained from a repository in [repositories]. The return value of the run method determines what is done after the application executes. It can specify that the launcher should restart the application or that it should exit with the provided exit code.
Jump to Line
Something went wrong with that request. Please try again.