Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 218 lines (182 sloc) 14.405 kb
56e96c3 @harrah New generalized launcher
authored
1 = Launcher Specification =
2
3 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.
4
f045123 @harrah Launcher documentation
authored
5 = Overview =
6
0a79f1e @harrah First update to launcher documentation
authored
7 A user downloads the launcher jar and creates a script to run it. In this documentation, the script will be assumed to be called 'launch'. For unix, the script would look like:
8 {{{
f045123 @harrah Launcher documentation
authored
9 java -jar sbt-launcher.jar "$@"
0a79f1e @harrah First update to launcher documentation
authored
10 }}}
f045123 @harrah Launcher documentation
authored
11
0a79f1e @harrah First update to launcher documentation
authored
12 The user then downloads the configuration file for the application (call it `my.app.configuration`) and creates a script to launch it (call it `myapp`):
13 {{{
f045123 @harrah Launcher documentation
authored
14 launch @my.app.configuration "$@"
0a79f1e @harrah First update to launcher documentation
authored
15 }}}
f045123 @harrah Launcher documentation
authored
16
17 The user can then launch the application using
0a79f1e @harrah First update to launcher documentation
authored
18 {{{
f045123 @harrah Launcher documentation
authored
19 myapp arg1 arg2 ...
0a79f1e @harrah First update to launcher documentation
authored
20 }}}
f045123 @harrah Launcher documentation
authored
21
0a79f1e @harrah First update to launcher documentation
authored
22 Like the launcher used to distribute `sbt`, the downloaded launcher jar will retrieve Scala and the application. The difference is that this behavior is now configurable. The versions may be fixed or read from a configuration file (the location of which is also configurable). The location to which the Scala and application jars are downloaded is configurable as well. The repositories searched are configurable. Optional initialization of a properties file is configurable.
f045123 @harrah Launcher documentation
authored
23
0a79f1e @harrah First update to launcher documentation
authored
24 Once the launcher has downloaded the necessary jars, it loads the application and calls its entry point. The application is passed information about how it was called: command line arguments, current working directory, Scala version, and application ID (organization, name, version). In addition, the launcher can ask the launcher to perform operations such as obtaining the Scala jars and a `ClassLoader` for any version of Scala retrievable from the repositories specified in the configuration file. It can request that other applications be downloaded and run. When the application completes, it can tell the launcher to exit with a specific exit code or to reload the application with a different version of Scala, a different version of the application, or different arguments.
f045123 @harrah Launcher documentation
authored
25
0a79f1e @harrah First update to launcher documentation
authored
26 There are some other options for setup, such as putting the configuration file inside the launcher jar and distributing that as a single download. The rest of this documentation describes the details of configuring, writing, distributing, and running the application.
f045123 @harrah Launcher documentation
authored
27
56e96c3 @harrah New generalized launcher
authored
28 == Configuration ==
29
f045123 @harrah Launcher documentation
authored
30 The launcher may be configured in one of the following ways in increasing order of precedence:
0a79f1e @harrah First update to launcher documentation
authored
31 * Replace the `/sbt/sbt.boot.properties` file in the jar
32 * Put a configuration file named `sbt.boot.properties` on the classpath. Put it in the classpath root without the `/sbt` prefix.
33 * Specify the location of an alternate configuration on the command line. This can be done by either specifying the location as the system property `sbt.boot.properties` or as the first argument to the launcher prefixed by `'@'`. The system property has lower precedence. 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.
56e96c3 @harrah New generalized launcher
authored
34
0a79f1e @harrah First update to launcher documentation
authored
35 The configuration file is line-based, read as UTF-8 encoded, and defined by the following grammer. `'nl'` is a newline or end of file and `'text'` is plain text without newlines or the surrounding delimiters (such as parentheses or square brackets):
36 {{{
1c9cabc @harrah Update launch specification, fix launch initialization, general cleanup
authored
37 configuration ::= scala app repositories boot log app-properties
2d9a7b1 @harrah Add scala.classifiers property to specify classifiers for additional sca...
authored
38 scala ::= '[' 'scala' ']' nl version nl classifiers nl
31c4719 @harrah update launcher documentation to include app.resources
authored
39 app ::= '[' 'app' ']' nl org nl name nl version nl components nl class nl cross-versioned nl resources nl
56e96c3 @harrah New generalized launcher
authored
40 repositories ::= '[' 'repositories' ']' nl (repository nl)*
0a79f1e @harrah First update to launcher documentation
authored
41 boot ::= '[' 'boot' ']' nl directory nl bootProperties nl search nl promptCreate nl promptFill nl quickOption nl
1c9cabc @harrah Update launch specification, fix launch initialization, general cleanup
authored
42 log ::= '[' 'log' ']' nl logLevel nl
43 app-properties ::= '[' 'app-properties' ']' nl property*
56e96c3 @harrah New generalized launcher
authored
44
0a79f1e @harrah First update to launcher documentation
authored
45 directory ::= 'directory' ':' path
46 bootProperties ::= 'properties' ':' path
47 search ::= 'search' ':' ('none'|'nearest'|'root-first'|'only') (',' path)*
48 logLevel ::= 'log-level' ':' ('debug' | 'info' | 'warn' | 'error')
49 promptCreate ::= 'prompt-create' ':' label
50 promptFill ::= 'prompt-fill' ':' boolean
51 quickOption ::= 'quick-option' ':' boolean
52
53 version ::= 'version' ':' versionSpecification
54 versionSpecification ::= readProperty | fixedVersion
55 readProperty ::= 'read' '(' propertyName ')' '[' default ']'
56 fixedVersion ::= text
56e96c3 @harrah New generalized launcher
authored
57
2d9a7b1 @harrah Add scala.classifiers property to specify classifiers for additional sca...
authored
58 classifiers ::= 'classifiers' ':' text (',' text)*
59
56e96c3 @harrah New generalized launcher
authored
60 org ::= 'org' ':' text
61 name ::= 'name' ':' text
62 class ::= 'class' ':' text
63 components ::= 'components' ':' component (',' component)*
0a79f1e @harrah First update to launcher documentation
authored
64 cross-versioned ::= 'cross-versioned' ':' boolean
31c4719 @harrah update launcher documentation to include app.resources
authored
65 resources ::= 'resources' ':' path (',' path)*
56e96c3 @harrah New generalized launcher
authored
66
0a79f1e @harrah First update to launcher documentation
authored
67 repository ::= ( predefinedRepository | customRepository ) nl
68 predefinedRepository ::= 'local' | 'maven-local' | 'maven-central' | 'scala-tools-releases' | 'scala-tools-snapshots'
835ee0d @ebowman XSBT-5: maven-style ivy repo support in the launcher config
ebowman authored
69 customRepository ::= label ':' url [[',' pattern] ',' pattern [',' 'mavenCompatible']]
56e96c3 @harrah New generalized launcher
authored
70
1c9cabc @harrah Update launch specification, fix launch initialization, general cleanup
authored
71 property ::= label ':' propertyDefinition (',' propertyDefinition)* nl
0a79f1e @harrah First update to launcher documentation
authored
72 propertyDefinition ::= mode '=' (set | prompt)
73 mode ::= 'quick' | 'new' | 'fill'
74 set ::= 'set' '(' value ')'
75 prompt ::= 'prompt' '(' label ')' ('[' default ']')?
76
77 boolean ::= 'true' | 'false'
78 path, propertyName, label, default ::= text
79 }}}
56e96c3 @harrah New generalized launcher
authored
80 The default configuration file for sbt looks like:
0a79f1e @harrah First update to launcher documentation
authored
81 {{{
56e96c3 @harrah New generalized launcher
authored
82 [scala]
0a79f1e @harrah First update to launcher documentation
authored
83 version: read(def.scala.version)
f68c906 @harrah minor fixes to launch specification
authored
84 # classifiers: sources
56e96c3 @harrah New generalized launcher
authored
85
86 [app]
87 org: org.scala-tools.sbt
1c9cabc @harrah Update launch specification, fix launch initialization, general cleanup
authored
88 name: sbt
0a79f1e @harrah First update to launcher documentation
authored
89 version: read(sbt.version)
1c9cabc @harrah Update launch specification, fix launch initialization, general cleanup
authored
90 class: sbt.xMain
91 components: xsbti
56e96c3 @harrah New generalized launcher
authored
92 cross-versioned: true
93
94 [repositories]
95 local
96 maven-local
f68c906 @harrah minor fixes to launch specification
authored
97 sbt-db: http://databinder.net/repo/, [organization]/[module]/[revision]/[type]s/[artifact](-[classifier]).[ext]
56e96c3 @harrah New generalized launcher
authored
98 maven-central
99 scala-tools-releases
0a79f1e @harrah First update to launcher documentation
authored
100 scala-tools-snapshots
56e96c3 @harrah New generalized launcher
authored
101
102 [boot]
103 directory: project/boot
104 properties: project/build.properties
1c9cabc @harrah Update launch specification, fix launch initialization, general cleanup
authored
105 prompt-create: Project does not exist, create new project?
106 prompt-fill: true
107 quick-option: true
56e96c3 @harrah New generalized launcher
authored
108
109 [log]
110 level: info
111
1c9cabc @harrah Update launch specification, fix launch initialization, general cleanup
authored
112 [app-properties]
113 project.name: quick=set(test), new=prompt(Name), fill=prompt(Name)
0a79f1e @harrah First update to launcher documentation
authored
114 project.organization: new=prompt(Organization)
1c9cabc @harrah Update launch specification, fix launch initialization, general cleanup
authored
115 project.version: quick=set(1.0), new=prompt(Version)[1.0], fill=prompt(Version)[1.0]
31c4719 @harrah update launcher documentation to include app.resources
authored
116 def.scala.version: quick=set(2.7.7), new=set(2.7.7), fill=set(2.7.7)
117 build.scala.versions: quick=set(2.7.7), new=prompt(Scala version)[2.7.7], fill=prompt(Scala version)[2.7.7]
f68c906 @harrah minor fixes to launch specification
authored
118 sbt.version: quick=set(0.6.9), new=prompt(sbt version)[0.6.9], fill=prompt(sbt version)[0.6.9]
1c9cabc @harrah Update launch specification, fix launch initialization, general cleanup
authored
119 project.scratch: quick=set(true)
120 project.initialize: quick=set(true), new=set(true)
0a79f1e @harrah First update to launcher documentation
authored
121 }}}
122
24e34a0 @waywardmonkeys Spelling fixes.
waywardmonkeys authored
123 The `scala.version` property specifies the version of Scala used to run the application. If specified, the `scala.classifiers`property defines classifiers such as 'sources' of extra Scala artifacts to retrieve. The `app.org`, `app.name`, 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 `app.cross-versioned` is true, the resolved module ID is `{app.name+'_'+scala.version}`. The paths given in `app.resources` are added to the application's classpath. If the path is relative, it is resolved against the application's working directory.
0a79f1e @harrah First update to launcher documentation
authored
124
125 Jars are retrieved to the directory given by `boot.directory`. You can make this an absolute path to be shared by all sbt instances on the machine. You might see messages like:
126 {{{
127 Waiting for lock on <lock-file> to be available...
128 }}}
129 if multiple versions access it simultaneously.
1c9cabc @harrah Update launch specification, fix launch initialization, general cleanup
authored
130
0a79f1e @harrah First update to launcher documentation
authored
131 The `boot.properties` property specifies the location of the properties file to use if `app.version` or `scala.version` is specified as `read`. The `prompt-create`, `prompt-fill`, and `quick-option` properties together with the property definitions in `[app.properties]` can be used to initialize the `boot.properties` file.
56e96c3 @harrah New generalized launcher
authored
132
0a79f1e @harrah First update to launcher documentation
authored
133 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 that implements `xsbti.AppMain`. The `AppMain` interface specifies the entry method signature 'run'. The run method is passed an instance of AppConfiguration, which provides access to the startup environment. `AppConfiguration` also provides an interface to retrieve other versions of Scala or other applications. Finally, the return type of the run method is `xsbti.MainResult`, which has two subtypes: `xsbti.Reboot` and `xsbti.Exit`. To exit with a specific code, return an instance of `xsbti.Exit` with the requested code. To restart the application, return an instance of Reboot. You can change some aspects of the configuration with a reboot, such as the version of Scala, the application ID, and the arguments.
56e96c3 @harrah New generalized launcher
authored
134
135 == Execution ==
136
0a79f1e @harrah First update to launcher documentation
authored
137 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 specified as 'read', the launcher determines them in the following manner. The file given by the 'boot.properties' property is read as a Java properties file to obtain the version. The expected property names are `${app.name}.version` for the application version (where `${app.name}` is replaced with the value of the `app.name` property from the boot configuration file) and `scala.version` for the Scala version. If the properties file does not exist, the default value provided is used. If no default was provided, an error is generated.
56e96c3 @harrah New generalized launcher
authored
138
0a79f1e @harrah First update to launcher documentation
authored
139 Once the final configuration is resolved, the launcher proceeds to obtain the necessary jars to launch the application. The `boot.directory` 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
140 {{{
141 ${boot.directory}/${scala.version}/lib/
142 }}}
24e34a0 @waywardmonkeys Spelling fixes.
waywardmonkeys authored
143 If this directory already exists, the launcher takes a shortcut for startup performance and assumes that the jars have already been downloaded. If the directory does not exist, the launcher uses Apache Ivy to resolve and retrieve the jars. A similar process occurs for the application itself. It and its dependencies are retrieved to
0a79f1e @harrah First update to launcher documentation
authored
144 {{{
145 ${boot.directory}/${scala.version}/${app.org}/${app.name}/.
146 }}}
56e96c3 @harrah New generalized launcher
authored
147
31c4719 @harrah update launcher documentation to include app.resources
authored
148 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' and with the paths specified in `app.resources`. An application that does not use components will have all of its jars in this class loader.
56e96c3 @harrah New generalized launcher
authored
149
69aa076 @harrah Add example for using launcher
authored
150 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.
151
152 == Creating a Launched Application ==
153
f045123 @harrah Launcher documentation
authored
154 This section shows how to make an application that is launched by this launcher. First, declare a dependency on the launcher-interface. Do not declare a dependency on the launcher itself. The launcher interface consists strictly of Java interfaces in order to avoid binary incompatibility between the version of Scala used to compile the launcher and the version used to compile your application. The launcher interface class will be provided by the launcher, so it is only a compile-time dependency. If you are building with sbt, your dependency definition would be:
0a79f1e @harrah First update to launcher documentation
authored
155 {{{
31c4719 @harrah update launcher documentation to include app.resources
authored
156 val launchInterface = "org.scala-tools.sbt" % "launcher-interface" % "0.6.8" % "provided"
0a79f1e @harrah First update to launcher documentation
authored
157 }}}
158 Make the entry point to your class implement 'xsbti.AppMain'. An example that uses some of the information:
159 {{{
69aa076 @harrah Add example for using launcher
authored
160 package xsbt.test
161 class Main extends xsbti.AppMain
162 {
163 def run(configuration: xsbti.AppConfiguration) =
164 {
165 // get the version of Scala used to launch the application
166 val scalaVersion = configuration.provider.scalaProvider.version
167 // Print a message and the arguments to the application
168 println("Hello world! Running Scala " + scalaVersion)
169 configuration.arguments.foreach(println)
170 // demonstrate the ability to reboot the application into different versions of Scala
171 // and how to return the code to exit with
172 scalaVersion match
173 {
31c4719 @harrah update launcher documentation to include app.resources
authored
174 case "2.7.7" =>
69aa076 @harrah Add example for using launcher
authored
175 new xsbti.Reboot {
176 def arguments = configuration.arguments
177 def baseDirectory = configuration.baseDirectory
178 def scalaVersion = "2.7.4"
179 def app = configuration.provider.id
180 }
f045123 @harrah Launcher documentation
authored
181 case "2.7.4" => new Exit(1)
182 case _ => new Exit(0)
69aa076 @harrah Add example for using launcher
authored
183 }
184 }
f045123 @harrah Launcher documentation
authored
185 class Exit(val code) extends xsbti.Exit
69aa076 @harrah Add example for using launcher
authored
186 }
0a79f1e @harrah First update to launcher documentation
authored
187 }}}
f045123 @harrah Launcher documentation
authored
188 Next, define a configuration file for the launcher. For the above class, it might look like:
0a79f1e @harrah First update to launcher documentation
authored
189 {{{
69aa076 @harrah Add example for using launcher
authored
190 [scala]
31c4719 @harrah update launcher documentation to include app.resources
authored
191 version: 2.7.7
69aa076 @harrah Add example for using launcher
authored
192 [app]
193 org: org.scala-tools.sbt
194 name: xsbt-test
31c4719 @harrah update launcher documentation to include app.resources
authored
195 version: 0.6.8
69aa076 @harrah Add example for using launcher
authored
196 class: xsbt.test.Main
197 cross-versioned: true
198 [repositories]
199 local
200 maven-local
201 maven-central
202 scala-tools-releases
203 # scala-tools-snapshots
204 [boot]
205 directory: boot
0a79f1e @harrah First update to launcher documentation
authored
206 }}}
207 Then, `publish-local` or `+publish-local` the application to make it available.
69aa076 @harrah Add example for using launcher
authored
208
f045123 @harrah Launcher documentation
authored
209 == Running an Application ==
210
69aa076 @harrah Add example for using launcher
authored
211 As mentioned above, there are a few options to actually run the application. The first involves providing a modified jar for download. The second two require providing a configuration file for download.
f68c906 @harrah minor fixes to launch specification
authored
212 # Replace the /sbt/sbt.boot.properties file in the launcher jar and distribute the modified jar. The user would need a script to run 'java -jar your-launcher.jar arg1 arg2 ...'.
213 # The user downloads the launcher jar and you provide the configuration file.
214 # The user needs to run 'java -Dsbt.boot.properties=your.boot.properties -jar launcher.jar'.
215 # The user already has a script to run the launcher (call it 'launch'). The user needs to run
0a79f1e @harrah First update to launcher documentation
authored
216 {{{
217 launch @your.boot.properties your-arg-1 your-arg-2
218 }}}
Something went wrong with that request. Please try again.