From 31c47192ee396ba0254761746f5ae3c1580d5262 Mon Sep 17 00:00:00 2001 From: Mark Harrah Date: Sun, 20 Dec 2009 23:55:24 -0500 Subject: [PATCH] update launcher documentation to include app.resources --- launch.specification | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/launch.specification b/launch.specification index cd100a417..4b3299933 100644 --- a/launch.specification +++ b/launch.specification @@ -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 @@ -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' @@ -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: {{{ @@ -141,7 +142,7 @@ 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. @@ -149,7 +150,7 @@ The main class for the application is then instantiated. It must be a public cl 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: {{{ @@ -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 @@ -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]