Skip to content

Commit

Permalink
update launcher documentation to include app.resources
Browse files Browse the repository at this point in the history
  • Loading branch information
harrah committed Dec 21, 2009
1 parent ffae830 commit 31c4719
Showing 1 changed file with 11 additions and 10 deletions.
21 changes: 11 additions & 10 deletions launch.specification
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ The configuration file is line-based, read as UTF-8 encoded, and defined by the
{{{
configuration ::= scala app repositories boot log app-properties
scala ::= '[' 'scala' ']' nl version nl
app ::= '[' 'app' ']' nl org nl name nl version nl components nl class nl cross-versioned nl
app ::= '[' 'app' ']' nl org nl name nl version nl components nl class nl cross-versioned nl resources nl
repositories ::= '[' 'repositories' ']' nl (repository nl)*
boot ::= '[' 'boot' ']' nl directory nl bootProperties nl search nl promptCreate nl promptFill nl quickOption nl
log ::= '[' 'log' ']' nl logLevel nl
Expand All @@ -60,6 +60,7 @@ configuration ::= scala app repositories boot log app-properties
class ::= 'class' ':' text
components ::= 'components' ':' component (',' component)*
cross-versioned ::= 'cross-versioned' ':' boolean
resources ::= 'resources' ':' path (',' path)*

repository ::= ( predefinedRepository | customRepository ) nl
predefinedRepository ::= 'local' | 'maven-local' | 'maven-central' | 'scala-tools-releases' | 'scala-tools-snapshots'
Expand Down Expand Up @@ -109,14 +110,14 @@ The default configuration file for sbt looks like:
project.name: quick=set(test), new=prompt(Name), fill=prompt(Name)
project.organization: new=prompt(Organization)
project.version: quick=set(1.0), new=prompt(Version)[1.0], fill=prompt(Version)[1.0]
def.scala.version: quick=set(2.7.5), new=set(2.7.5), fill=set(2.7.5)
build.scala.versions: quick=set(2.7.5), new=prompt(Scala version)[2.7.5], fill=prompt(Scala version)[2.7.5]
sbt.version: quick=set(0.6.0), new=prompt(sbt version)[0.6.0], fill=prompt(sbt version)[0.6.0]
def.scala.version: quick=set(2.7.7), new=set(2.7.7), fill=set(2.7.7)
build.scala.versions: quick=set(2.7.7), new=prompt(Scala version)[2.7.7], fill=prompt(Scala version)[2.7.7]
sbt.version: quick=set(0.6.8), new=prompt(sbt version)[0.6.8], fill=prompt(sbt version)[0.6.8]
project.scratch: quick=set(true)
project.initialize: quick=set(true), new=set(true)
}}}

The `scala.version` property specifies the version of Scala used to run the application. 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 `scala.version` property specifies the version of Scala used to run the application. 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.

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:
{{{
Expand All @@ -141,15 +142,15 @@ If this directory already exists, the launcher takes a shortcut for startup perf
${boot.directory}/${scala.version}/${app.org}/${app.name}/.
}}}

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.
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.

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.

== Creating a Launched Application ==

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:
{{{
val launchInterface = "org.scala-tools.sbt" % "launcher-interface" % "0.7" % "provided"
val launchInterface = "org.scala-tools.sbt" % "launcher-interface" % "0.6.8" % "provided"
}}}
Make the entry point to your class implement 'xsbti.AppMain'. An example that uses some of the information:
{{{
Expand All @@ -167,7 +168,7 @@ class Main extends xsbti.AppMain
// and how to return the code to exit with
scalaVersion match
{
case "2.7.5" =>
case "2.7.7" =>
new xsbti.Reboot {
def arguments = configuration.arguments
def baseDirectory = configuration.baseDirectory
Expand All @@ -184,11 +185,11 @@ class Main extends xsbti.AppMain
Next, define a configuration file for the launcher. For the above class, it might look like:
{{{
[scala]
version: 2.7.5
version: 2.7.7
[app]
org: org.scala-tools.sbt
name: xsbt-test
version: 0.7
version: 0.6.8
class: xsbt.test.Main
cross-versioned: true
[repositories]
Expand Down

0 comments on commit 31c4719

Please sign in to comment.