Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

exported HTML from Google Code wiki

  • Loading branch information...
commit 5f236d1a1680fb83272823f81c11e4758943f4c8 1 parent 47f625a
@harrah harrah authored
Showing with 7,071 additions and 0 deletions.
  1. +194 −0 0.7.7/docs/090p1tour.html
  2. +159 −0 0.7.7/docs/090p2tour.html
  3. +241 −0 0.7.7/docs/090p3tour.html
  4. +202 −0 0.7.7/docs/090p4tour.html
  5. +130 −0 0.7.7/docs/0_6_Summary.html
  6. +71 −0 0.7.7/docs/ActionContent.html
  7. +73 −0 0.7.7/docs/Artifacts.html
  8. +40 −0 0.7.7/docs/Build.html
  9. +198 −0 0.7.7/docs/BuildConfiguration.html
  10. +217 −0 0.7.7/docs/ChangeDetectionAndTesting.html
  11. +71 −0 0.7.7/docs/ChangeSummary0_3_5.html
  12. +50 −0 0.7.7/docs/ChangeSummary0_3_7.html
  13. +70 −0 0.7.7/docs/ChangeSummary_0_4.html
  14. +88 −0 0.7.7/docs/ChangeSummary_0_4_3.html
  15. +68 −0 0.7.7/docs/ChangeSummary_0_4_5.html
  16. +90 −0 0.7.7/docs/ChangeSummary_0_4_6.html
  17. +69 −0 0.7.7/docs/ChangeSummary_0_5.html
  18. +51 −0 0.7.7/docs/ChangeSummary_0_5_2.html
  19. +75 −0 0.7.7/docs/ChangeSummary_0_5_4.html
  20. +53 −0 0.7.7/docs/ChangeSummary_0_5_5.html
  21. +626 −0 0.7.7/docs/Changes.html
  22. +82 −0 0.7.7/docs/Classpaths.html
  23. +53 −0 0.7.7/docs/CompilerPlugins.html
  24. +51 −0 0.7.7/docs/Credits.html
  25. +66 −0 0.7.7/docs/CrossBuild.html
  26. +98 −0 0.7.7/docs/CustomActions.html
  27. +79 −0 0.7.7/docs/CustomCompileConfiguration.html
  28. +100 −0 0.7.7/docs/DocumentationHome.html
  29. +106 −0 0.7.7/docs/ExampleSbtTest.html
  30. +59 −0 0.7.7/docs/Forking.html
  31. +213 −0 0.7.7/docs/GeneralizedLauncher.html
  32. +52 −0 0.7.7/docs/GettingInvolved.html
  33. +88 −0 0.7.7/docs/IntegrationSupport.html
  34. +201 −0 0.7.7/docs/IvyInterface.html
  35. +48 −0 0.7.7/docs/JavaSources.html
  36. +170 −0 0.7.7/docs/LibraryManagement.html
  37. +68 −0 0.7.7/docs/Loader.html
  38. +57 −0 0.7.7/docs/LocalScala.html
  39. +44 −0 0.7.7/docs/ManagedConfigurations.html
  40. +60 −0 0.7.7/docs/MethodTasks.html
  41. +139 −0 0.7.7/docs/Paths.html
  42. +52 −0 0.7.7/docs/ProGuard.html
  43. +82 −0 0.7.7/docs/Process.html
  44. +146 −0 0.7.7/docs/Processors.html
  45. +63 −0 0.7.7/docs/ProjectConsole.html
  46. +215 −0 0.7.7/docs/ProjectDefinitionExamples.html
  47. +33 −0 0.7.7/docs/ProjectDependencies.html
  48. +133 −0 0.7.7/docs/Properties.html
  49. +65 −0 0.7.7/docs/Publishing.html
  50. +147 −0 0.7.7/docs/Resolvers.html
  51. +53 −0 0.7.7/docs/RunningProjectCode.html
  52. +411 −0 0.7.7/docs/RunningSbt.html
  53. +121 −0 0.7.7/docs/SbtPlugins.html
  54. +61 −0 0.7.7/docs/ScalaJars.html
  55. +97 −0 0.7.7/docs/SettingsProposal.html
  56. +139 −0 0.7.7/docs/Setup.html
  57. +135 −0 0.7.7/docs/SubProjects.html
  58. +70 −0 0.7.7/docs/TestFrameworkExtensions.html
  59. +67 −0 0.7.7/docs/TriggeredExecution.html
  60. +83 −0 0.7.7/docs/Troubleshooting.html
  61. +40 −0 0.7.7/docs/WebApplicationExample.html
  62. +68 −0 0.7.7/docs/WebApplications.html
  63. +43 −0 0.7.7/docs/Webstart.html
  64. +77 −0 0.7.7/docs/WebstartExample.html
  65. BIN  0.7.7/docs/jsp-test.zip
View
194 0.7.7/docs/090p1tour.html
@@ -0,0 +1,194 @@
+<html>
+ <head>
+ <title>090p1tour</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">090p1tour</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <p></p>
+ <ul>
+ <li><a href="#Introduction">Introduction</a></li>
+ <li><a href="#Basics">Basics</a></li>
+ <li><a href="#sbtrc">sbtrc</a></li>
+ <li><a href="#Compile/Discover">Compile/Discover</a></li>
+ <ul>
+ <li><a href="#Compile">Compile</a></li>
+ <li><a href="#Discover">Discover</a></li>
+ </ul>
+ <li><a href="#Defining_Commands">Defining Commands</a></li>
+ <ul>
+ <li><a href="#Command_Example">Command Example</a></li>
+ <li><a href="#Build_and_Load_Commands">Build and Load Commands</a></li>
+ <li><a href="#Load_Projects">Load Projects</a></li>
+ <li><a href="#Conclusion">Conclusion</a></li>
+ </ul>
+ </ul>
+ <p></p>
+ <h1><a name="Introduction"></a>Introduction<a href="#Introduction" class="section_anchor"></a></h1>
+ <p>This is intended as a guided tour through some of the ideas being explored in 0.9. </p>
+ <h1><a name="Basics"></a>Basics<a href="#Basics" class="section_anchor"></a></h1>
+ <p>The interface is different from what you are used to in 0.7.4 due to this being an early preview for the curious. </p>
+ <p>Try some commands: </p>
+ <pre class="prettyprint">$ xsbt help
+...
+$ xsbt 'help alias'
+...
+$ xsbt 'alias h=help' h
+...
+$ xsbt shell
+&gt; alias
+&gt; alias $%=reload
+&gt; alias h=help
+&gt; alias
+ h = help
+ $% = reload
+&gt; alias $%
+ $% = reload
+&gt; alias h=
+&gt; alias
+ $% = reload
+&gt; $%
+&gt; alias</pre>
+ <p>This is all done so far without a project object. The usual Project hierarchy does not exist at this point. More on this later... </p>
+ <h1><a name="sbtrc"></a>sbtrc<a href="#sbtrc" class="section_anchor"></a></h1>
+ <p>sbt 0.7.4 already has <tt>'&lt; file'</tt> for reading commands from a file. What 0.9.x adds is reading from <tt>~/.sbtrc</tt> and <tt>./.sbtrc</tt> on startup. So, create <tt>~/.sbtrc</tt> and add some commands to it: </p>
+ <pre class="prettyprint">alias h=help
+h &lt;
+iflast shell</pre>
+ <p>The last command sets up interactive mode if the user has not provided any commands on the command line. Otherwise, the commands provided on the command line are run and then sbt exits. If you want to always enter interactive mode, you can either manually append <tt>shell</tt> to the arguments you provide on the command line or replace <tt>iflast</tt> with <tt>append</tt>. <tt>append shell</tt> adds the <tt>shell</tt> command after all pending commands. </p>
+ <p>With the above <tt>~/.sbtrc</tt>, startup looks like: </p>
+ <pre class="prettyprint">$ xsbt
+
+&lt; file1 file2 ...
+ Reads the lines ...
+
+&gt;</pre>
+ <h1><a name="Compile/Discover"></a>Compile/Discover<a href="#Compile/Discover" class="section_anchor"></a></h1>
+ <p>The next two commands we'll look at are <tt>compile</tt> and <tt>discover</tt>. First, a warning: command parsing is rough. Invalid options are usually ignored and path parsing might not do what you expect. </p>
+ <h2><a name="Compile"></a>Compile<a href="#Compile" class="section_anchor"></a></h2>
+ <p>Create two source files <tt>B.scala</tt> and <tt>C.scala</tt>: </p>
+ <pre class="prettyprint">case class B(i: Int) {
+ def y = C.x - 1
+}
+
+@deprecated object C {
+ def x = 3
+}</pre>
+ <p>Compile them using: </p>
+ <pre class="prettyprint">$ xsbt
+&gt; compile -src *.scala</pre>
+ <p>(see 'help compile' for details) </p>
+ <p>Then, modify C.x to be </p>
+ <pre class="prettyprint"> def x = 6</pre>
+ <p>and recompile. </p>
+ <p>In sbt 0.7.4, this would cause both <tt>B.scala</tt> and <tt>C.scala</tt> to be recompiled. With the new incremental compilation in 0.9.x, <tt>C.scala</tt> is recompiled, the result is analyzed, and it is seen that only the implementation of <tt>C.x</tt> changed, not its signature. Therefore, the transitive dependencies of <tt>C.scala</tt> do not need to be recompiled. This will mainly help larger projects and multi-project builds. It does nothing to speed up initial compilation and can even be slower when signatures do change because it does multiple compilation runs in this case. </p>
+ <p>You can change <tt>C.x</tt> to be: </p>
+ <pre class="prettyprint"> def x = &quot;6&quot;</pre>
+ <p>and see that <tt>B.scala</tt> is properly recompiled with the expected error message. (Lots of incremental compilation debugging information can be turned on by adding <tt>-Dxsbt.inc.debug=true</tt> to the startup script.) </p>
+ <h2><a name="Discover"></a>Discover<a href="#Discover" class="section_anchor"></a></h2>
+ <p>Additionally, <tt>compile</tt> sets the <tt>Analysis</tt> of the compiled code to be the current &quot;project&quot; object. You can then run <tt>discover</tt>, a command available after a successful <tt>compile</tt> that finds subclasses and annotated classes. See <tt>help discover</tt> for details, but here are some examples: </p>
+ <pre class="prettyprint">&gt; discover -annot scala.deprecated
+...
+&gt; discover -sub scala.Product
+...</pre>
+ <p>The Analysis object represents the full API of the compiled classes and is persisted to disk. This means, for example, that the process of discovering tests will be done separately from compilation just like <tt>discover</tt> runs separate from <tt>compile</tt>. You can inspect the API of compiled classes by writing a <tt>Command</tt> that operates on <tt>sbt.inc.Analysis</tt>. Later, when tasks are ready, you will be able to do this by writing a normal task. </p>
+ <h1><a name="Defining_Commands"></a>Defining Commands<a href="#Defining_Commands" class="section_anchor"></a></h1>
+ <p>Next, we'll look at defining a <tt>Command</tt>. In sbt 0.7.4 you can define plugins and processors. These require a full project for each <tt>Processor</tt> or plugin and have to be published somewhere. sbt 0.9.x has a more lightweight, low-level concept that is not attached to the Project hierarchy called a <tt>Command</tt>: </p>
+ <blockquote>
+ <tt>Command</tt> is basically a function:
+ <tt>State =&gt; Option[Apply]</tt>
+ <blockquote>
+ where
+ <tt>Apply</tt> provides
+ <tt>Help</tt> and a function
+ <tt>Input =&gt; Option[State]</tt>
+ </blockquote>
+ </blockquote>
+ <p></p>
+ <p><tt>State</tt> contains the currently declared <tt>Command</tt>s, commands queued for execution, the current &quot;project definition&quot;, and some other state. <tt>Input</tt> contains both the full input line and the line broken into a command name and arguments. </p>
+ <p>The idea is that a command might apply only to some project types. If it doesn't apply, None is returned by the <tt>State =&gt; Option[Apply]</tt> function. Otherwise, an <tt>Apply</tt> instance is returned, which then processes the <tt>Input</tt> command. If the command doesn't select that particular <tt>Command</tt>, <tt>None</tt> is returned. <tt>Apply.simple</tt> handles this for the simple, common case of fixed command names. </p>
+ <h2><a name="Command_Example"></a>Command Example<a href="#Command_Example" class="section_anchor"></a></h2>
+ <p>As an example, make a file <tt>~/.sbt/commands/HelloWorld.scala</tt>: </p>
+ <pre class="prettyprint">
+import sbt._
+
+class HelloWorld extends ReflectedCommands
+{
+ val hw = Command.single(
+ &quot;hello&quot;, /* command name */
+ (&quot;hello x&quot;, briefHelp), /* (usage, description) */
+ briefHelp /* Detailed help. Here, just use the brief help. */
+ ) { (s: State, in: String) =&gt;
+
+ println(&quot;Hello &quot; + in)
+
+ // no changes to the state. We could have added new commands to run, loaded new Commands, changed the current project definition, ...
+ s
+ }
+
+ private def briefHelp = &quot;Says hello to the name provided on the command line.&quot;
+}</pre>
+ <h2><a name="Build_and_Load_Commands"></a>Build and Load Commands<a href="#Build_and_Load_Commands" class="section_anchor"></a></h2>
+ <p>There is a command <tt>load-commands</tt> that builds and loads commands (replace <tt>~</tt> with your home directory): </p>
+ <pre class="prettyprint">&gt; load-commands -src ~/.sbt/commands/*.scala
+...
+&gt; hello World
+...</pre>
+ <p>Add this command to your <tt>~/.sbtrc</tt> and the commands will be built and loaded on startup and on calls to <tt>reload</tt>. </p>
+ <p>All internal sbt commands in 0.9.x are implemented as <tt>Command</tt>s. There are two distinguished commands that run at startup, however. These are <tt>add-default-commands</tt> and <tt>initialize</tt>. sbt initially does not know about any commands, so <tt>add-default-commands</tt> registers built-in commands. <tt>initialize</tt> reads commands from <tt>~/.sbtrc</tt> and <tt>./.sbtrc</tt> if they exist. </p>
+ <h2><a name="Load_Projects"></a>Load Projects<a href="#Load_Projects" class="section_anchor"></a></h2>
+ <p><tt>load-commands</tt> has a relative, <tt>load</tt>, which does something similar for &quot;project definitions&quot;. I have been quoting &quot;project definitions&quot; because at the basic level, a &quot;project definition&quot; is any object. Commands select the state they apply to by pattern matching on the current project definition. We can define a command that operates on history by requiring a project definition to implement a simple interface to provide the history path: </p>
+ <p>trait HistoryEnabled { </p>
+ <blockquote>
+ def historyPath: OptionPath
+ </blockquote>}
+ <p></p>
+ <p>To demonstrate this, make ./project/a/Test.scala: </p>
+ <pre class="prettyprint">import sbt._
+import Path._
+class Test extends HistoryEnabled {
+ def historyPath = Some(cwd / &quot;target&quot; / &quot;.history&quot;)
+ def cwd = new java.io.File(&quot;.&quot;)
+}</pre>
+ <p>and run: </p>
+ <pre class="prettyprint">&gt; load -src project/a/*.scala -name Test
+...
+&gt; !
+...
+&gt; !:
+...</pre>
+ <p>Note that we can load any type as the &quot;project definition&quot;, as we have done here and with the 'compile' command. A standard sbt interface would make this type <tt>Project</tt>. </p>
+ <h2><a name="Conclusion"></a>Conclusion<a href="#Conclusion" class="section_anchor"></a></h2>
+ <p>You can see that commands are really intended to build an interface to configuring sbt. Many people configure a build, quite a few people write plugins, fewer people write processors, and even fewer write commands. Perhaps I will be the only one to ever use them; however, hopefully you can see that they enable interesting things. I believe commands fill an open slot on the spectrum of using and extending sbt. From convention to customization: </p>
+ <ol>
+ <li>use sbt defaults/conventions/built-in tasks, no project definition </li>
+ <li>configure by creating Project definition in project/build </li>
+ <li>distribute/reuse project definition code using plugins </li>
+ <li>add commands using Processors, which use the standard Project hierarchy </li>
+ <li>build an interface to the sbt core using Commands, possibly different than the Project hierarchy </li>
+ <li>use sbt libraries outside of sbt </li>
+ <li>use/customize the launcher to run an arbitrary application </li>
+ </ol>
+ <p></p>
+ <p>The usual sbt interface is 1-4. The idea is to put these on top of 5, which itself is built on 6 and 7. </p>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
159 0.7.7/docs/090p2tour.html
@@ -0,0 +1,159 @@
+<html>
+ <head>
+ <title>090p2tour</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">090p2tour</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <h1><a name="Introduction"></a>Introduction<a href="#Introduction" class="section_anchor"></a></h1>
+ <p>This is the second preview of new features in 0.9.x. The feature this time is the new task engine. The main change is that tasks now produce a value. Another change is that cross-building is at the task level and can be done for more variables than just the Scala version. </p>
+ <p>I believe the model behind tasks to be simple, but powerful. Once you understand the model, using tasks should be straightforward and without surprises. I am interested in making this documentation clear and thorough to minimize the time to understanding the model. Your feedback is appreciated. </p>
+ <h1><a name="Setup"></a>Setup<a href="#Setup" class="section_anchor"></a></h1>
+ <p>You can follow along by setting up a project as in <a href="090p1tour">090p1tour</a>, having your project definition extend <tt>SingleProject</tt> (a trait for testing out tasks) and import from <tt>sbt</tt> and <tt>sbt.std</tt>: </p>
+ <pre class="prettyprint">import sbt._
+import std._
+
+class TaskTest extends SingleProject
+{
+ ...
+}</pre>
+ <p>Remember to run the appropriate 'load' after each change for it to take effect. If you have put your project definition in <tt>project/build</tt>: </p>
+ <pre class="prettyprint">&gt; load -src project/build/*.scala -name TaskTest</pre>
+ <p>All of the task examples are available at <a href="http://gist.github.com/556888" rel="nofollow">http://gist.github.com/556888</a>. </p>
+ <h1><a name="Basics"></a>Basics<a href="#Basics" class="section_anchor"></a></h1>
+ <p><tt>Task[T]</tt> represents a computation that produces a value of type <tt>T</tt>. To create a new task that has no inputs, use the <tt>task</tt> method. The argument to the <tt>task</tt> method is the code to run when the task is executed. </p>
+ <pre class="prettyprint"> lazy val hello: Task[Unit] =
+ task { println(&quot;Hi!&quot;) }
+
+ lazy val three: Task[Int] =
+ task { 3 }</pre>
+ <p>Note: the explicit type annotations in the examples are not necessary unless otherwise indicated. You can see the result of a task by running it with the <tt>show</tt> task. For example: </p>
+ <pre class="prettyprint">&gt; show hello three
+Hi!
+hello: ()
+three: 3</pre>
+ <p>To declare a dependency on another task, use <tt>dependsOn</tt>. For example: </p>
+ <pre class="prettyprint"> lazy val goodbye: Task[Unit] = task { println(&quot;Goodbye&quot;) } dependsOn(hello)</pre>
+ <p>To use the value from another task, use <tt>map</tt>: </p>
+ <pre class="prettyprint"> lazy val four: Task[Int] = three map { (t: Int) =&gt; t + 1 }</pre>
+ <p>Or, a bit more concisely: </p>
+ <pre class="prettyprint"> lazy val four = three map { _ + 1 }</pre>
+ <p>The next fundamental method is <tt>flatMap</tt>. This takes the result of one Task and provides another Task that will provide the result. For example, the following uses the output of the <tt>rand</tt> task to determine if either <tt>four</tt> or <tt>three</tt> should execute. </p>
+ <pre class="prettyprint"> lazy val rand: Task[Boolean] = task { math.random &gt; 0.5 }
+ lazy val num: Task[Int] = rand flatMap { (b: Boolean) =&gt; if(b) four else three }</pre>
+ <p>If <tt>rand</tt> produces <tt>true</tt>, the <tt>four</tt> task is run and its result is the result of <tt>num</tt>. Otherwise, the <tt>three</tt> task runs and its result is used for the result of <tt>num</tt>. Note that in both cases the <tt>three</tt> tasks runs- once directly and once indirectly because <tt>four</tt> uses its result. </p>
+ <h1><a name="Parallel"></a>Parallel<a href="#Parallel" class="section_anchor"></a></h1>
+ <p>Those were the basic serial methods<a href="#Notes">[1</a>]. There are also versions of <tt>map</tt> and <tt>flatMap</tt> that operate on multiple input tasks<a href="#Notes">[2</a>]. They do not impose an ordering on the input tasks, so you might refer to them as parallel map and flatMap. For example: </p>
+ <pre class="prettyprint"> lazy val par: Task[Int] = (three, four) map { (t: Int, f: Int) =&gt; t * f }</pre>
+ <p>This means &quot;create a new Task that takes the results of <tt>three</tt> and <tt>four</tt> and multiplies them together&quot;. Note that for the parallel map/flatMap, explicit parameter types are required for the function literal<a href="#Notes">[3</a>]. In order to abstract over arity, the native data structures involed are heterogeneous lists. Implicit conversions translate the above syntax to: </p>
+ <pre class="prettyprint"> lazy val par: Task[Int] = three :^: four :^: KNil map { case t :+: f :+: HNil =&gt; t * f }</pre>
+ <p>Because of this, the compiler cannot infer the type parameters for the standard function literal. These implicit conversions are available for arity 2 and 3. For arbitrary arity or if you want type inference for the mapping function, you need to use the heterogenous list approach. </p>
+ <p>There are also methods to apply a function across a sequence in parallel, to combine the results of a sequence of tasks, or to reduce the results of a sequence of tasks. </p>
+ <pre class="prettyprint"> lazy val forkReduce: Task[Int] = (0 to 1000).fork( _ * 3).reduce { _ + _ }
+ lazy val forkJoin: Task[Seq[Int]] = (0 to 1000).fork(_ * 3).join</pre>
+ <p>(This is just an example. The overhead is too high for this to be faster than a direct computation.) </p>
+ <h1><a name="Error_Handling"></a>Error Handling<a href="#Error_Handling" class="section_anchor"></a></h1>
+ <p>If a Task fails by throwing an Exception, tasks that need the failing task's result also fail. There are methods that are similar to Scala's <tt>catch/finally</tt> that modify this behavior. </p>
+ <p><tt>task mapFailure f</tt> only succeeds if <tt>task</tt> fails, in which case the error handling function <tt>f</tt> is evaluated for the failure. Failure is represented by the <tt>Incomplete</tt> class. The main purpose of <tt>Incomplete</tt> is to track multiple sources of failure, since tasks form a graph. A simple example that prints the failing stack trace: </p>
+ <pre class="prettyprint"> lazy val fail: Task[Int] = task { error(&quot;A failure.&quot;) }
+ lazy val catchLike: Task[Unit] = fail mapFailure { (t: Incomplete) =&gt; t.printStackTrace }</pre>
+ <p>This just prints the stack trace of the top-level failure, but more useful error reporting would need to report the full graph of failures. </p>
+ <p>Like an exception in normal code, the failure propagates through the dependency graph. If all dependent tasks &quot;catch&quot; the failure, propagation of the failure ceases. As with <tt>catch</tt>, you must rethrow the exception if you want the catching function to fail as well. There is also <tt>flatMapFailure</tt> that allows returning a new <tt>Task</tt> like <tt>flatMap</tt> does when the input succeeds. Both methods are also available in parallel. The parallel <tt>map/flatMapFailure</tt> succeeds if any input fails and provides a <tt>Seq[Incomplete]</tt> to the error handling function. </p>
+ <p>To always run some code regardless of the success of a task, use <tt>andFinally</tt>. This works like <tt>finally</tt>. The provided code is run and the result of the initial task, either a successful value or an exception, is propagated. </p>
+ <pre class="prettyprint"> lazy val alwaysRunA: Task[Int] = fail andFinally { println(&quot;Finally 1&quot;) }
+ lazy val alwaysRunB: Task[Int] = four andFinally { println(&quot;Finally 2&quot;) }</pre>
+ <p><tt>alwaysRunA</tt> will print &quot;Finally 1&quot; and then propagate the exception thrown by <tt>fail</tt>. <tt>alwaysRunB</tt> will print &quot;Finally 2&quot; and then return the result of <tt>four</tt>, which is 4. </p>
+ <p>To chain tasks and ignore their outputs, use <tt>&amp;&amp;</tt> or <tt>||</tt>. For <tt>&amp;&amp;</tt>, if <tt>a</tt> fails, <tt>a &amp;&amp; b</tt> fails and <tt>b</tt> is not run (unless, of course, another task requires <tt>b</tt> to run). Otherwise, the result of <tt>a</tt> is ignored and the final result is that of <tt>b</tt>. </p>
+ <pre class="prettyprint"> // succeeds because 'hello' succeeds. The result is that of the final task, which is `three` here.
+ lazy val allA: Task[Int] = hello &amp;&amp; three
+
+ // fails because 'fail' fails
+ lazy val allB: Task[Unit] = fail &amp;&amp; hello</pre>
+ <p>For <tt>a || b</tt>, if <tt>a</tt> fails, the result of <tt>a || b</tt> is that of <tt>b</tt>. If <tt>a</tt> succeeds, the result is that of <tt>a</tt> and <tt>b</tt> is not run. Each of following returns <tt>4</tt>. </p>
+ <pre class="prettyprint"> lazy val orA: Task[Int] = fail || four
+ lazy val orB: Task[Int] = four || fail
+ lazy val orC: Task[Int] = four || three</pre>
+ <p>Actually, <tt>||</tt>, <tt>&amp;&amp;</tt>, <tt>map*</tt>, <tt>flatMap*</tt>, <tt>andFinally</tt>, <tt>reduce</tt>, and <tt>fork</tt> (that is, everything mentioned so far except <tt>task</tt>, <tt>dependsOn</tt> and <tt>join</tt>), are implemented in terms of two primitive functions (four, counting the parallel versions separately). Instead of requiring success and mapping on the resulting value or requiring failure and mapping on the cause, these always run and map on <tt>Result[T]</tt>. <tt>Result[T]</tt> is isomorphic to <tt>Either[Incomplete, T]</tt> and is used instead of <tt>Either</tt> for type inference<a href="#Notes">[4</a>]. </p>
+ <p>The primitive functions are <tt>mapR</tt> and <tt>flatMapR</tt>, where the <tt>R</tt> is for <tt>Result</tt> <a href="#Notes">[5</a>]. </p>
+ <pre class="prettyprint"> lazy val fullA: Task[Int] = four mapR {
+ case Inc(i) =&gt; 0
+ case Value(v) =&gt; v
+ }</pre>
+ <p><tt>Inc[T]</tt> is like <tt>Left[Incomplete, T]</tt> and <tt>Value[T]</tt> is like <tt>Right[Incomplete, T]</tt>. </p>
+ <h1><a name="Cross-building"></a>Cross-building<a href="#Cross-building" class="section_anchor"></a></h1>
+ <p>Cross-building (running tasks against multiple configurations) is built into the task model. A task produces a result for a specific configuration. You define a configuration variable by declaring the type of value and a label for that value. </p>
+ <p>For example, the following declares two configuration variables. <tt>ScalaVersion</tt> ranges over <tt>String</tt>s, while <tt>Number</tt> ranges over <tt>Int</tt>s. In the default sbt model, <tt>ScalaVersion</tt> will likely be predefined and most users won't have to worry about this part. </p>
+ <pre class="prettyprint"> val ScalaVersion = AttributeKey[String](&quot;scala-version&quot;)
+ val Number = AttributeKey[Int](&quot;num&quot;)</pre>
+ <p>You define the values to cross-build against with the <tt>cross</tt> task, which accepts the configuration and the values. For example: </p>
+ <pre class="prettyprint"> lazy val scalaVersion: Task[String] = cross(ScalaVersion)(&quot;2.7.7&quot;, &quot;2.8.0&quot;)
+ lazy val number: Task[Int] = cross(Number)(1,2,3)</pre>
+ <p>Note that the result types are not <tt>Seq[String]</tt> and <tt>Seq[Int]</tt>. This means that cross-building is not present in the type of a task. Cross-building is handled mostly transparently after this point with some of restrictions. </p>
+ <p>The idea is that we use the methods presented above and the task system takes care of applying them across each configuration. </p>
+ <pre class="prettyprint"> lazy val printVersion: Task[Unit] = scalaVersion map println
+ lazy val printNumber: Task[Unit] = number map println
+
+ lazy val printBoth: Task[Unit] = (scalaVersion, number) map { (v: String, n: Int) =&gt; println(n + &quot;: &quot; + v) }</pre>
+ <p>The task <tt>printBoth</tt> does a parallel map on <tt>scalaVersion</tt> and <tt>number</tt>. These have different configurations, though. <tt>scalaVersion</tt> produces a value for <tt>ScalaVersion</tt> values &quot;2.7.7&quot; and &quot;2.8.0&quot; and <tt>number</tt> produces a value for <tt>Number</tt> values 1,2, and 3. The parallel map does a cross product of its inputs. So, we now have a task <tt>printBoth</tt> that ranges over these configurations: </p>
+ <pre class="prettyprint"> AttributeMap(Number -&gt; 1, ScalaVersion -&gt; &quot;2.7.7&quot;)
+ AttributeMap(Number -&gt; 2, ScalaVersion -&gt; &quot;2.7.7&quot;)
+ AttributeMap(Number -&gt; 3, ScalaVersion -&gt; &quot;2.7.7&quot;)
+ AttributeMap(Number -&gt; 1, ScalaVersion -&gt; &quot;2.8.0&quot;)
+ AttributeMap(Number -&gt; 2, ScalaVersion -&gt; &quot;2.8.0&quot;)
+ AttributeMap(Number -&gt; 3, ScalaVersion -&gt; &quot;2.8.0&quot;)</pre>
+ <p>Each configuration is represented by an <tt>AttributeMap</tt>, which is a map that ensures that a key of type <tt>AttributeKey[T]</tt> is mapped to a value of type <tt>T</tt>. If we then map on <tt>printBoth</tt>, we will cross build against each of these six configurations. </p>
+ <p>If you do something like: </p>
+ <pre class="prettyprint"> lazy val numA: Task[Int] = cross(Number)(1,2,3)
+ lazy val numB: Task[Int] = cross(Number)(4,5,6)
+ (numA, numB) map { ...}</pre>
+ <p>sbt will complain that there are no compatible configurations. There is no result for <tt>numA</tt> for <tt>Number</tt> values 4,5,6. Similarly, <tt>numB</tt> has no result for 1,2,3. Therefore, this constraint cannot be satisfied. I don't expect this to come up much, since I don't know when you would declare different values to cross-build like this, except in error. Most people will probably just use the cross-building built into sbt by default. If anyone starts doing more interesting cross-builds, more details on this can be documented. </p>
+ <p>To pull the result of all cross-builds of a <tt>Task</tt> into an explicit value, use <tt>merge</tt>. This takes the tasks for all configurations and puts their results into <tt>Seq[(AttributeMap, T)]</tt>. For example: </p>
+ <pre class="prettyprint"> lazy val stringBoth: Task[String] = (scalaVersion, number) map { (v: String, n: Int) =&gt; n + &quot;: &quot; + v }
+ lazy val merged: Task[Seq[(AttributeMap, String)]] = stringBoth.merge</pre>
+ <p>The result of <tt>merged</tt> is a <tt>Seq</tt> that contains a mapping from each configuration (<tt>AttributeMap</tt>) to the result (here, <tt>String</tt>). </p>
+ <p>As a final note on cross-building, it is done at construction time. This places a limitation on returning cross-built tasks in a <tt>flatMap</tt>. You cannot introduce new configurations in a <tt>flatMap</tt>. Consider the following examples: </p>
+ <pre class="prettyprint"> lazy val onBoth = stringBoth flatMap { #1 }
+ lazy val onNum = number flatMap { #2 }
+ lazy val onHello = hello flatMap { #3 }</pre>
+ <ul>
+ <li>For #1, you can return a task that is not cross-built or a task that is cross-built against <tt>Number</tt>, <tt>ScalaVersion</tt>, or both. This is because <tt>stringBoth</tt> is built against configurations with both variables <tt>Number</tt> and <tt>ScalaVersion</tt>. </li>
+ <li>For #2, you can return a task cross-built against <tt>Number</tt> or a non-cross-built task because <tt>number</tt> is cross-built for <tt>Number</tt>. </li>
+ <li>For #3, you can only return a task that is not cross-built against anything because <tt>hello</tt> is not cross-built. </li>
+ </ul>
+ <h1><a name="Next_part"></a>Next part<a href="#Next_part" class="section_anchor"></a></h1>
+ <ul>
+ <li>Streams: a task I/O and logging system </li>
+ <li>Integration with processes: piping and redirection between tasks and processes </li>
+ <li>Controlling multi-project aggregation </li>
+ <li>Access to command line input </li>
+ </ul>
+ <h1><a name="Notes"></a>Notes<a href="#Notes" class="section_anchor"></a></h1>
+ <ol>
+ <li>You might notice that they give rise to a monad. See also <a href="http://code.google.com/p/scalaz/" rel="nofollow">scalaz</a>'s <a href="http://scalaz.googlecode.com/svn/continuous/latest/browse.sxr/scalaz/example/concurrent/Fibs.scala.html" rel="nofollow">Promise</a>. </li>
+ <li>These are related to <tt>liftA2</tt>, <tt>liftA3</tt>, ... This usage is preferred to nested flatMaps (as in for comprehensions) because no ordering is imposed on the inputs and so they can be executed in parallel. </li>
+ <li>This is a rough edge. Sorry. </li>
+ <li><a href="http://lampsvn.epfl.ch/trac/scala/ticket/2712" rel="nofollow">http://lampsvn.epfl.ch/trac/scala/ticket/2712</a> </li>
+ <li>Suggestions for better names welcome. </li>
+ <li>Conceptually, a task is the combination of three monads: one for <tt>Task[_]</tt>, one for <tt>Either[Incomplete, _]</tt>, and one for <tt>Map[AttributeMap, _]</tt>. If it were fully represented in the type system, the type of a task might look like: <tt>Task[Map[AttributeMap, Either[Incomplete, T]]]</tt>. </li>
+ </ol>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
241 0.7.7/docs/090p3tour.html
@@ -0,0 +1,241 @@
+<html>
+ <head>
+ <title>090p3tour</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">090p3tour</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <p></p>
+ <ul>
+ <li><a href="#Introduction">Introduction</a></li>
+ <li><a href="#Command_line_input">Command line input</a></li>
+ <li><a href="#Streams">Streams</a></li>
+ <ul>
+ <li><a href="#Logging">Logging</a></li>
+ <li><a href="#Text_and_Binary_I/O">Text and Binary I/O</a></li>
+ <ul>
+ <li><a href="#Basics">Basics</a></li>
+ <li><a href="#Streams_and_Process_API">Streams and Process API</a></li>
+ <li><a href="#Streams_and_SBinary">Streams and SBinary</a></li>
+ </ul>
+ </ul>
+ <li><a href="#Notes">Notes</a></li>
+ </ul>
+ <p></p>
+ <h1><a name="Introduction"></a>Introduction<a href="#Introduction" class="section_anchor"></a></h1>
+ <p>The second preview introduced the new task engine for 0.9.x. This preview expands on some features built on top of this new task model. These are: </p>
+ <ul>
+ <li>Access to command line input </li>
+ <li>Streams: a task I/O and logging system </li>
+ <li>Integration with processes: piping and redirection between tasks and processes </li>
+ </ul>
+ <p></p>
+ <p>These provided sufficient material for one post, so multi-project improvements will be covered in a follow-up. As before, type annotations are optional unless otherwise indicated. The context for all of the example code is: </p>
+ <pre class="prettyprint"> import sbt._
+ import std._
+ import java.io._
+ import Process._
+
+class Test(val info: ProjectInfo) extends TestProject
+{
+ ...
+}</pre>
+ <p>To follow along: </p>
+ <ol>
+ <li>Setup sbt 0.9 as indicated in the <a href="http://code.google.com/p/simple-build-tool/wiki/090p1tour" rel="nofollow">first preview</a> </li>
+ <li>Create a new project (type <tt>'xsbt'</tt> and enter <tt>'s'</tt> for scratch) </li>
+ <li>Save the project definition template above in <tt>.sbt/Test.scala</tt> (<tt>.sbt</tt> is an experiment) or <tt>project/build/Test.scala</tt> </li>
+ <li>Run interactive mode (<tt>'xsbt shell'</tt>) </li>
+ <li>To initially load and to reload the project definition, run the <tt>'loadp'</tt> command. </li>
+ </ol> For example:
+ <p></p>
+ <pre class="prettyprint">$ xsbt
+Project does not exist, create new project? (y/N/s) s
+Getting Scala 2.8.0 ...
+:: retrieving :: org.scala-tools.sbt#boot-scala
+ confs: [default]
+ 2 artifacts copied, 0 already retrieved (14484kB/83ms)
+Getting org.scala-tools.sbt sbt_2.8.0 0.9.0-SNAPSHOT ...
+:: retrieving :: org.scala-tools.sbt#boot-app
+ confs: [default]
+ 29 artifacts copied, 0 already retrieved (3726kB/36ms)
+$ xsbt shell
+&gt; loadp</pre>
+ <h1><a name="Command_line_input"></a>Command line input<a href="#Command_line_input" class="section_anchor"></a></h1>
+ <p>The command line is available as the result of a task <tt>input</tt> of type <tt>Task[Input]</tt>. The <tt>Input</tt> interface looks like: </p>
+ <pre class="prettyprint">trait Input {
+ // the full, unparsed command line
+ val line: String
+ // the command name
+ val name: String
+ // everything after the command name
+ val arguments: String
+ // 'arguments' split around whitespace, no escaping supported
+ val splitArgs: Seq[String]
+}</pre>
+ <p><tt>line</tt> is the full input String and the rest of the methods are convenience methods for processing this<a href="http://code.google.com/p/simple-build-tool/wiki/090p3tour#Notes" rel="nofollow">[1</a>]. </p>
+ <p>Grab the <tt>Input</tt> instance from the <tt>input</tt> task using functions shown in the <a href="http://code.google.com/p/simple-build-tool/wiki/090p2tour" rel="nofollow">previous article</a>, such as by using <tt>map</tt>: </p>
+ <pre class="prettyprint"> lazy val hi =
+ input map { (in: Input) =&gt;
+ println(&quot;Hi &quot; + in.arguments)
+ }
+
+ lazy val hiAll =
+ input map { (in: Input) =&gt;
+ in.splitArgs foreach( (arg: String) =&gt; println(&quot;Hi &quot; + arg) )
+ }</pre>
+ <p>Sample usage of these tasks is: </p>
+ <pre class="prettyprint"> &gt; hi A B
+ Hi A B
+
+ &gt; hiAll A B
+ Hi A
+ Hi B</pre>
+ <p>Because the input task is just a task, any task has access to the command line. It remains to be seen whether this will be useful or confusing in practice. However, it does loosen some restrictions imposed on method tasks, the predecessor to this approach. A method task could not be a dependency of other tasks and only the method task on the current project would be executed. Both of these will be demonstrated later. </p>
+ <h1><a name="Streams"></a>Streams<a href="#Streams" class="section_anchor"></a></h1>
+ <p>There is a new system for logging that I call <tt>Streams</tt> (like <tt>Input/OutputStreams</tt>, not Scala's lazy list <tt>Stream</tt> type). It has several advantages, which will be demonstrated here. Similar to the command line <tt>input</tt> task, there is a task called <tt>streams</tt> that provides a <tt>TaskStreams</tt> instance. Unlike the <tt>input</tt> task, the provided <tt>TaskStreams</tt> is specific to the retrieving task<a href="http://code.google.com/p/simple-build-tool/wiki/090p3tour#Notes" rel="nofollow">[2</a>]. This <tt>TaskStreams</tt> provides access to managed logging and persisted text and binary input and output streams. Any I/O streams used by the task are automatically closed when the task finishes executing<a href="http://code.google.com/p/simple-build-tool/wiki/090p3tour#Notes" rel="nofollow">[3</a>]. </p>
+ <p>The <tt>TaskStreams</tt> interface looks like: </p>
+ <pre class="prettyprint">sealed trait TaskStreams
+{
+ val log: Logger = log(default)
+ def log(sid: String): Logger
+
+ def text(sid: String = default): PrintWriter
+ def binary(sid: String = default): BufferedOutputStream
+
+ def readText(a: Task[_], sid: String = default): Task[BufferedReader]
+ def readBinary(a: Task[_], sid: String = default): Task[BufferedInputStream]
+
+ val default = &quot;out&quot;
+}</pre>
+ <h2><a name="Logging"></a>Logging<a href="#Logging" class="section_anchor"></a></h2>
+ <p>We'll start by looking at logging. We grab a <tt>TaskStreams</tt> instance and log something to the default <tt>Logger</tt>. </p>
+ <pre class="prettyprint"> lazy val logDemo = streams map { (s: TaskStreams) =&gt;
+ s.log.info(&quot;Testing...&quot;)
+ }</pre>
+ <p>The first benefit is that the default <tt>Logger</tt> not only logs to the screen, but also to a file. The pre-defined <tt>last</tt> task lets us view the previous output. </p>
+ <pre class="prettyprint"> &gt; logDemo
+ [info] Testing...
+ &gt; last logDemo
+ [info] Testing...</pre>
+ <p>One use for this is when there is a lot of output from multiple tasks. Additionally, different logging levels can be set for printing to the screen and for persisting the messages. You could set the logging level for the screen to be quiet and verbose for the persisted file. Then, if you need to see detail, you could pull up the previous logging. Note that <tt>last</tt> is not special, merely predefined. You could write it yourself, but how to do that isn't shown here. </p>
+ <p>The Streams model allows multiple streams, each labeled with a String identifier. You can send logging to other streams by using the <tt>log</tt> method that accepts a stream id (sid). </p>
+ <pre class="prettyprint"> lazy val logExtra = streams map { (s: TaskStreams) =&gt;
+ val log: Logger = s.log(&quot;extra&quot;)
+ log.info(&quot;Testing extra...&quot;)
+ }</pre>
+ <p>If you run 'last logExtra', nothing is printed to the screen because 'logExtra' didn't send anything to the default stream. So, the 'last' command is currently simple, but it could be modified to show a particular stream instead of the default output stream. </p>
+ <h2><a name="Text_and_Binary_I/O"></a>Text and Binary I/O<a href="#Text_and_Binary_I/O" class="section_anchor"></a></h2>
+ <h3><a name="Basics"></a>Basics<a href="#Basics" class="section_anchor"></a></h3>
+ <p>In addition to logging, a task can send arbitrary text and binary data to a stream. </p>
+ <pre class="prettyprint"> lazy val echo =
+ (streams, input) map { (s: TaskStreams, in: Input) =&gt;
+ val out: PrintWriter = s.text()
+ out.println(in.arguments)
+ }
+
+ lazy val hello =
+ (streams, input) map { (s: TaskStreams, in: Input) =&gt;
+ val out: PrintWriter = s.text()
+ in.splitArgs foreach { arg =&gt; out.println(&quot;Hi &quot; + arg) }
+ }</pre>
+ <p><tt>text()</tt> uses the default stream. <tt>text(&quot;id&quot;)</tt> would use the stream labeled <tt>id</tt>. </p>
+ <p>Example usage: </p>
+ <pre class="prettyprint"> &gt; echo some input
+ &gt; hello some input
+ &gt; last echo
+ some input
+ &gt; last hello
+ Hi input
+ Hi some</pre>
+ <p>The data sent to a stream can then be read from other tasks. The following reads the output stream of the <tt>echo</tt> task just defined and sends it to standard output. </p>
+ <pre class="prettyprint"> lazy val goodbye = echo text { (in: BufferedReader) =&gt;
+ println(&quot;Goodbye &quot; + in.readLine())
+ }</pre>
+ <p>Example output: </p>
+ <pre class="prettyprint">&gt; goodbye for now
+Goodbye for now</pre>
+ <p>One thing to note here is that <tt>goodbye</tt> is not processing the command line. <tt>goodbye</tt> depends on <tt>echo</tt>, which is the one processing the arguments. To see this, use 'last': </p>
+ <pre class="prettyprint">&gt; last goodbye
+&gt; last echo
+for now</pre>
+ <p>As mentioned in the command line input section, I'm not sure if this is useful or confusing in practice. Finally, if <tt>echo</tt> sent output to a different stream, you would use need to specify that stream id to <tt>text</tt>. </p>
+ <h3><a name="Streams_and_Process_API"></a>Streams and Process API<a href="#Streams_and_Process_API" class="section_anchor"></a></h3>
+ <p>There is some integration between the Process API and Streams. You can pipe between <tt>Task</tt>s and <tt>Process</tt>es and the output of a <tt>Process</tt> can be persisted like a <tt>Task</tt>. Note that there is an overhead to this compared to piping between two real <tt>Process</tt>es due to reading/writing from an intermediate backing <tt>File</tt>. </p>
+ <pre class="prettyprint"> // the exit code of the 'grep' process is the result of the 'grep' task.
+ lazy val grep: Task[Int] =
+ hello #| &quot;grep me&quot;
+
+ // 'lines' is a method of type Task[Seq[String]]
+ // that gets the lines of output from a task, here from 'grep'
+ lazy val grepLines =
+ grep.lines map( (ls: List[String]) =&gt; println(ls) )
+
+ lazy val grepToFile = grep #&gt; new File(&quot;test&quot;)</pre>
+ <p>Example output: </p>
+ <pre class="prettyprint"> &gt; grep you me someone
+ &gt; last grep
+ Hi someone
+ Hi me
+ &gt; grepLines you me someone
+List(Hi me, Hi someone)
+ &gt; grepToFile you me someone
+ $ cat test
+ Hi me
+ Hi someone</pre>
+ <h3><a name="Streams_and_SBinary"></a>Streams and SBinary<a href="#Streams_and_SBinary" class="section_anchor"></a></h3>
+ <p>As a final example, let's store some binary data using <a href="http://github.com/harrah/sbinary" rel="nofollow">SBinary</a>. This library is now distributed with sbt and is available for use in project definitions (it is used by sbt itself for caching data). </p>
+ <pre class="prettyprint"> import sbinary._
+ import JavaIO._
+ import DefaultProtocol._
+
+ lazy val write = streams map { (s: TaskStreams) =&gt;
+ // define some data
+ val myData = (3, &quot;asdf&quot;)
+ // get the stream to write to
+ val out: BufferedOutputStream = s.binary(&quot;data&quot;)
+ // write the data to the stream using SBinary
+ Operations.write(out , myData)
+ }
+
+ // get the 'data' stream for the 'write' task
+ lazy val read = write.binary(&quot;data&quot;) { (stream: BufferedInputStream) =&gt;
+ // read in the data using SBinary
+ val (i, st) = Operations.read[(Int,String)]( stream )
+ // show it
+ println(&quot;i: &quot; + i)
+ println(&quot;st: &quot; + st)
+ }</pre>
+ <p>Example output: </p>
+ <pre class="prettyprint">&gt; read
+i: 3
+st: asdf</pre>
+ <p>Like with the result of a <tt>Task</tt>, multiple tasks can read a task's streams (they are not consumed by the first task to read from them), so you could have multiple <tt>read</tt>-like tasks in the same execution. </p>
+ <p>For the last example with <tt>SBinary</tt>, <tt>write</tt> could have just returned <tt>(3, &quot;asdf&quot;)</tt> as its result. Also, in the examples shown so far, reading a task's streams forces that task to run first. Because the stream is persisted, this is not a strict requirement. The task could be a 'soft' dependency, where it would only run if some other task needs it to. This is how 'last' is implemented. However, because 'flatMap' was included in the task model, it is difficult to properly integrate soft dependencies and so they are not really ready for general use. Another pending addition is access to the underlying <tt>File</tt>. This would allow <tt>Streams</tt> to be used as the backing for caches. </p>
+ <h1><a name="Notes"></a>Notes<a href="#Notes" class="section_anchor"></a></h1>
+ <ol>
+ <li><tt>command</tt> is the initial, continuous run of symbolic characters or of alphanumeric characters (but not mixed). </li>
+ <li>This is accomplished by a transformation on tasks that depend on <tt>streams</tt>. Several features of the task engine are implemented this way. </li>
+ <li>This means you can't pass around a reference to the <tt>InputStream/Logger/OutputStream</tt>, although that would be considered poor practice anyway. </li>
+ </ol>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
202 0.7.7/docs/090p4tour.html
@@ -0,0 +1,202 @@
+<html>
+ <head>
+ <title>090p4tour</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">090p4tour</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <p></p>
+ <ul>
+ <li><a href="#Introduction">Introduction</a></li>
+ <li><a href="#Single_project_incremental_compilation">Single project incremental compilation</a></li>
+ <li><a href="#Multi-project_incremental_compilation">Multi-project incremental compilation</a></li>
+ <li><a href="#Incremental_Recompilation_Details">Incremental Recompilation Details</a></li>
+ <li><a href="#Discovery">Discovery</a></li>
+ <li><a href="#External_Projects">External Projects</a></li>
+ <li><a href="#Dependency_Management">Dependency Management</a></li>
+ <li><a href="#Aggregation">Aggregation</a></li>
+ <li><a href="#Outlook">Outlook</a></li>
+ </ul>
+ <p></p>
+ <h1><a name="Introduction"></a>Introduction<a href="#Introduction" class="section_anchor"></a></h1>
+ <p>This is the last preview of major new aspects in 0.9.x. Aspects presented in earlier previews were a redone <a href="090p1tour">command system</a>, a new <a href="090p2tour">task model</a>, and a new <a href="090p3tour">logging and I/O system called streams</a>. This preview introduces the new multi-project incremental compilation, redesigned multi-project dependency management, and redesigned overall multi-project support, including better control over execution vs. classpath dependencies, support for external projects. If you only ever work on single projects, the new incremental compilation should still benefit you as well as the potential future support for remote projects. </p>
+ <h1><a name="Single_project_incremental_compilation"></a>Single project incremental compilation<a href="#Single_project_incremental_compilation" class="section_anchor"></a></h1>
+ <p>Create a new project. Add <tt>project/Single.scala</tt> with these contents: </p>
+ <pre class="prettyprint">import sbt._
+class Single(info: ProjectInfo) extends DefaultProject(info)
+{
+ // haven't gotten to reading from build.properties yet
+ override def name = &quot;single&quot;
+}</pre>
+ <p>Create a couple of source files in the root directory (or <tt>src/main/scala</tt> if you prefer): </p>
+ <p><tt>A.scala</tt> </p>
+ <pre class="prettyprint">object A
+{
+ val x = 3
+}</pre>
+ <p><tt>B.scala</tt> </p>
+ <pre class="prettyprint">object B
+{
+ val x = A.x
+}</pre>
+ <p>You can see the <tt>B</tt> uses <tt>A</tt> and that the inferred type of <tt>B.x</tt> will be the type of <tt>A.x</tt>. Go ahead and startup sbt, load the project definition, and run an initial compilation: </p>
+ <pre class="prettyprint">$ xsbt shell
+&gt; loadp
+&gt; compile</pre>
+ <p>Now change the value for <tt>A.x</tt> to be <tt>5</tt> instead of <tt>3</tt>. sbt prior to 0.9 would recompile both <tt>A.scala</tt> and <tt>B.scala</tt> because it only knew that the file had changed, not what changed inside. Now, sbt recompiles the modified files and only recompiles dependencies if the public API changes. So, if you run another <tt>compile</tt>, sbt will only recompile <tt>A.scala</tt>. However, if you change <tt>A.x</tt> to be <tt>true</tt> instead of <tt>5</tt>, you will notice that sbt recompiles <tt>A.scala</tt>, realizes it affects <tt>B.scala</tt> and recompiles that as well. Perhaps most usefully, this works across multiple projects as well. </p>
+ <h1><a name="Multi-project_incremental_compilation"></a>Multi-project incremental compilation<a href="#Multi-project_incremental_compilation" class="section_anchor"></a></h1>
+ <p>Now, let's create a new project to demonstrate multi-project recompilation. Add <tt>project/Multi.scala</tt>: </p>
+ <pre class="prettyprint">import sbt._
+class Multi(info: ProjectInfo) extends DefaultProject(info)
+{
+ override def name = &quot;root&quot;
+
+ // unlike in 0.7.4, this only declares subA as an execution dependency
+ // That is, it is not placed on the classpath of the root project, but aggregate commands are executed on it.
+ // Also unlike 0.7.4, commands are not aggregate by default. This will be shown later.
+ val subA = project(&quot;a&quot;, &quot;A&quot;, (i: ProjectInfo) =&gt; new DefaultProject { val info = i })
+
+ // so, to declare it as a classpath dependency, we say we want it as a 'compile' dependency
+ // with that, 'A' is compiled first and the result used on 'root's classpath.
+ val subADep = subA % &quot;compile&quot;
+}</pre>
+ <p>Let's create the same source files, but in separate projects. We'll put <tt>A.scala</tt> in the subproject and <tt>B.scala</tt> in the root project. </p>
+ <p><tt>a/A.scala</tt> </p>
+ <pre class="prettyprint">object A
+{
+ val x = 3
+}</pre>
+ <p><tt>B.scala</tt> </p>
+ <pre class="prettyprint">object B
+{
+ val x = A.x
+}</pre>
+ <p>Now, we execute <tt>compile</tt> for the initial compile (after starting up sbt and loading the project definition with <tt>loadp</tt>). Then, make the changes as before. Modify <tt>A.x</tt> to be <tt>5</tt> and note that <tt>B.scala</tt> is not recompiled. Modify <tt>A.x</tt> to be <tt>true</tt> and note that <tt>B.scala</tt> is recompiled. </p>
+ <p>You can list project with <tt>projects</tt> and move between them with <tt>project &lt;name&gt;</tt> (tab completion is not there yet). </p>
+ <h1><a name="Incremental_Recompilation_Details"></a>Incremental Recompilation Details<a href="#Incremental_Recompilation_Details" class="section_anchor"></a></h1>
+ <p>The full details would comprise a long article, but here is a short summary. </p>
+ <p>sbt now inserts an additional compiler phase after <tt>typer</tt> that extracts the API of compiled classes as an immutable data structure that tries to correspond as closely as possible to the Scala specification, especially Ch. 3 on types. This data structure is persisted so that it can be used between jvm invocations. Additionally it is available as the output of the <tt>compile</tt> task. A later section shows one way this can be used from your project definition. </p>
+ <p>As before, sbt checks which sources are modified or are out of date because of changes to binary dependencies (jars). What is new is that dependencies on other projects are tracked by their source API instead of the last modified time of the binary (either a class file or a jar). So, sbt will check whether the API for a dependency has changed and if it has, invalidate the dependent source (schedule it for recompilation). The first compilation run is then performed on these modified or invalidated sources. Note that within the project, transitive dependencies are not recompiled at this time. </p>
+ <p>During this compilation the new API for the sources is determined and checked against the previous API. If the public API has changed, then transitive dependencies of the changed source are recompiled. Note that the steps of determining the changes and propagating the changes are separate. That is, sbt does not determine what additional files to recompile based on what changed, only that there were changes. </p>
+ <h1><a name="Discovery"></a>Discovery<a href="#Discovery" class="section_anchor"></a></h1>
+ <p>As sbt users probably know, sbt 0.7.4 auto-detects test classes during compilation. Because the API of sources is now extracted and available after compilation, this discovery is now done after compilation. In fact, you can fairly easily do your own discovery. The following example shows how to detect subclasses of the marker interface <tt>DiscoveryTest</tt>. </p>
+ <p>Add the following task definition to one of the project definitions above (and reload the project definition with <tt>loadp</tt>): </p>
+ <pre class="prettyprint"> lazy val find = compile map { analysis =&gt;
+ build.Build.discover(analysis, None, build.Auto.Subclass, &quot;DiscoverTest&quot;)
+ }</pre>
+ <p>You can restrict the results to modules by using <tt>Some(true)</tt> instead of <tt>None</tt> or to only classes with <tt>Some(false)</tt>. You could detect annotations instead by using <tt>build.Auto.Annotation</tt> instead of <tt>build.Auto.Subclass</tt>. You can do more advanced processing, but you'd have to implement that yourself. The <tt>discover</tt> method is only for the relatively simple needs of test discovery. </p>
+ <p>Try it out by defining the marker interface, having one of the objects implement it (the object should be in the project defining <tt>find</tt>), and then running <tt>show find</tt>. (<tt>show</tt> will print the result of <tt>find</tt>. We could have also used a <tt>println</tt> in the definition of <tt>find</tt> if we wanted.) </p>
+ <pre class="prettyprint">object B extends DiscoverTest
+trait DiscoverTest</pre>
+ <h1><a name="External_Projects"></a>External Projects<a href="#External_Projects" class="section_anchor"></a></h1>
+ <p>External projects are fully supported in 0.9. There are no longer any restrictions with respect to location on the local filesystem. There is no longer the requirement that there be a single point of definition. That is, you can call <tt>project(&quot;sub&quot;)</tt> in multiple projects and <tt>sub</tt> will only be loaded once. The tradeoff is that <tt>project(&quot;sub&quot;)</tt> no longer loads and returns the <tt>Project</tt> instance immediately, but instead returns a descriptor that can later be used to obtain the <tt>Project</tt> instance. A bonus of this approach is that I believe it would be straightforward to add simple support for remote projects, like <tt>project(&quot;git://github.com/harrah/sbinary&quot;)</tt>. It would be more work to properly generalize it to allow arbitrary handlers, control updating the local copy, and so forth, but if you are interested in this, let me know and I'll try to point you in the right direction. </p>
+ <p>With that said, let's look at an example. We will add an additional sub project to our multi-project example. Because it is an external project, we need to make a full new project. Create this new project some other directory than the current project (this is not mandatory, it is just to demonstrate that it works outside of the project hierarchy). Add a project definition in this new project in <tt>project/External.scala</tt>: </p>
+ <pre class="prettyprint">import sbt._
+class External(info: ProjectInfo) extends DefaultProject(info)
+{
+ override def name = &quot;external&quot;
+}</pre>
+ <p>and a new source in <tt>E.scala</tt> (in the new project's root directory or in <tt>src/main/scala</tt>): </p>
+ <pre class="prettyprint">object E
+{
+ val x = false
+}</pre>
+ <p>Change <tt>B.x</tt> from before to refer to <tt>E.x</tt>: </p>
+ <pre class="prettyprint">object B
+{
+ val x = E.x
+}</pre>
+ <p>Add the dependency to <tt>MultiProject.scala</tt>: </p>
+ <pre class="prettyprint"> val ext = project(new File(&quot;/path/to/external&quot;))
+ val extDep = ext % &quot;compile&quot;</pre>
+ <p>You can start sbt in the external project directory (<tt>xsbt shell</tt>), load the project definition (<tt>loadp</tt>), and run <tt>compile</tt>. Here you are working directly on this project. You can then exit out of sbt and head back to the original project directory, startup sbt, load the project definition, and run <tt>compile</tt> there. Now, you are working with the project as an external project. </p>
+ <p>Modify <tt>E</tt> to be </p>
+ <pre class="prettyprint">object E
+{
+ val x = &quot;a string&quot;
+}</pre>
+ <p>Run <tt>compile</tt>. <tt>B.scala</tt> is recompiled again. Change <tt>E.x</tt> to return a different string. Note that <tt>E.scala</tt> is recompiled, but <tt>B.scala</tt> is not. </p>
+ <p>Note that the <tt>sbt.version</tt> setting for an external project is ignored. sbt should really check that it is the same or do something else more intelligent, but it doesn't. Also, I don't remember if cycles between projects are detected. </p>
+ <h1><a name="Dependency_Management"></a>Dependency Management<a href="#Dependency_Management" class="section_anchor"></a></h1>
+ <p><a title="multi-project dependency management" class="closed_ref" href="/p/simple-build-tool/issues/detail?id=44">&nbsp;Issue #44&nbsp;</a> describes a design flaw in sbt's inter-project dependency management. Consider a project A that depends on a project B. B declares a dependency on library L version 1.0. A declares a dependency on L 1.0.1. What goes on the compile classpath for B? How about A? Assume conflicts are resolved by the newest version available, as is the default in Ivy. Then, B should compile against L 1.0 and A should compile against L 1.0.1 and B, but L 1.0 should not be on A's classpath. Both L 1.0 and L 1.0.1 are on A's classpath in sbt 0.7.4. This is fixed in 0.9, but required an overhaul of how sbt does dependency management. </p>
+ <p>Previously, each project's dependencies were resolved independently and for each configuration separately. That is, A's 'compile' dependencies would be resolved without B entering the picture. The dependencies were retrieved to <tt>lib_managed/compile</tt> for each project. When the 'compile' classpath was required for A, the jars in A's <tt>lib_managed/compile</tt> were combined with those in B's <tt>lib_managed/compile</tt>. Clearly, this gives rise to the issue mentioned previously. </p>
+ <p>The fix is to resolve A's dependencies with the information that B is a dependency of A. For various reasons, the current way of laying out <tt>lib_managed</tt> is no longer reasonable. The current implementation of <tt>update</tt> returns a map from a configuration to the list of dependency locations in the Ivy cache. There are many good reasons not to use dependencies out of the cache, but ease of implementation is no longer one of them. I expect to implement the option of retrieving to <tt>lib_managed</tt>, but it will not be in the same layout (because it is incorrect). It is, however, straightforward to get the locations of dependencies from the <tt>update</tt> task. Consider the following multi-project definition: </p>
+ <pre class="prettyprint">import sbt._
+class DepDemo(info: ProjectInfo) extends DefaultProject(info)
+{
+ override def name = &quot;root&quot;
+
+ val sub = project(&quot;sub&quot;, &quot;Sub&quot;, new Sub(_))
+ val subDep = sub % &quot;compile&quot;
+
+ val ju = &quot;junit&quot; % &quot;junit&quot; % &quot;4.4&quot; % &quot;compile&quot;
+
+ class Sub(info: ProjectInfo) extends DefaultProject(info)
+ {
+ override def name = &quot;sub&quot;
+
+ val ju = &quot;junit&quot; % &quot;junit&quot; % &quot;4.5&quot; % &quot;compile&quot;
+ }
+}</pre>
+ <p>Start sbt, <tt>loadp</tt>, and run <tt>show update</tt>. You can see that the result of the <tt>update</tt> task is a mapping from configuration to dependency locations. Note that this does not include project dependencies; these are handled separately. You may have noticed from running <tt>compile</tt> that the <tt>compile</tt> task runs <tt>update</tt> first. It does this to get the mapping that <tt>update</tt> provides. Currently, <tt>update</tt> does a full run each time. However, the intention is for <tt>update</tt> to only run if the inputs have changed. sbt 0.9 provides much better mechanisms for implementing this behavior, which has been discussed before. If you are interested in implementing this feature, send an email to the mailing list. </p>
+ <h1><a name="Aggregation"></a>Aggregation<a href="#Aggregation" class="section_anchor"></a></h1>
+ <p>This final section will highlight the refined semantics of project dependencies. Project dependencies are now separated into execution and classpath dependencies. If a project A has an execution dependency on project B, an aggregate task <tt>act</tt> in <tt>A</tt> has an implicit dependency on the <tt>act</tt> task in B (if it exists). An aggregate task is a task that can be executed across projects. In 0.9, tasks are not aggregate by default. This can be enabled by calling the <tt>implies</tt> method. For example: </p>
+ <pre class="prettyprint">import sbt._
+class AggDemo(info: ProjectInfo) extends DefaultProject(info)
+{
+ override def name = &quot;root&quot;
+
+ // declare an execution dependency on 'sub'
+ val sub = project(&quot;sub&quot;, &quot;Sub&quot;, new Sub(_))
+
+ // make it an aggregate task
+ lazy val hiAgg = task { println(&quot;Hello 1&quot;) } implies;
+ // not an aggregate task
+ lazy val hiPlain = task { println(&quot;Hello 2&quot;) }
+
+ class Sub(info: ProjectInfo) extends DefaultProject(info)
+ {
+ lazy val hiAgg = task { println(&quot;Hello Sub 1&quot;) } implies;
+ lazy val hiPlain = task { println(&quot;Hello Sub 2&quot;) }
+ }
+}</pre>
+ <p>Start sbt, <tt>loadp</tt>, and run: </p>
+ <pre class="prettyprint">&gt; hiAgg
+Hello Sub 1
+Hello 1
+&gt; hiPlain
+Hello 2
+&gt; project Sub
+&gt; hiPlain
+Hello Sub 2</pre>
+ <p>The reason that aggregation is no longer the default is that now that tasks return values, you will usually explicitly <tt>map</tt> the output of dependent tasks that might have previously been implicit. For example, <tt>compile</tt> depends on the classpath tasks of the enclosing project's classpath dependencies. These will in turn depend on the <tt>compile</tt> task in their respective projects. So, there is no need for an implicit dependency between <tt>compile</tt> tasks. </p>
+ <p>As shown in the <a href="#Dependency_Management">Dependency Management</a> section, classpath project dependencies are project that are used in a project's classpath and are enabled by declaring the configuration mapping, which is usually &quot;compile&quot; for a compile dependency (it will also be available in tests and at runtime) or &quot;test&quot; to only use the dependency in test code. This latter use case was a bit more verbose and fragile in previous versions of sbt. </p>
+ <p>If you want only a classpath dependency and not an execution dependency, make the initial val private: </p>
+ <pre class="prettyprint"> private val sub = project(&quot;sub&quot;, &quot;Sub&quot;, new Sub(_))
+
+ val subDep = sub % &quot;compile&quot;</pre>
+ <p>Tasks in <tt>sub</tt> will still get run when there are explicit dependencies on them, as for <tt>compile</tt>. If you run <tt>update</tt>, however, it will only update the current project. </p>
+ <h1><a name="Outlook"></a>Outlook<a href="#Outlook" class="section_anchor"></a></h1>
+ <p>This preview concludes the presentation of the major, open-ended, long-term architectural designs/redesigns that have come to fruition in 0.9. (The new task engine has been in progress for over a year and so has multi-project aggressive incremental recompilation with API extraction. <a title="multi-project dependency management" class="closed_ref" href="/p/simple-build-tool/issues/detail?id=44">&nbsp;Issue #44&nbsp;</a> has been pending for about a year as well.) With this, I believe 0.9.0 is almost ready. Rather than work until 0.9.0 is nearly a drop-in replacement for 0.7.4, I'd like to release it now (well, very soon) essentially with the features presented so far. The features for 0.9.1 will probably be 'test', 'console', and 'run'. </p>
+ <p>Beyond that, I have some ideas. However, I think now is a great time to get involved. Some people have inquired about this and I'd very much like to help people get involved and working on interesting projects. Certainly I can drive the 0.9.x experimental series to become the stable 0.10.0 release myself, but I think the result will be more interesting and useful with others building on the systems I have described so far. The next article you can expect to see is a discussion of some opportunities for working on sbt, including what needs to be done or could be done. </p>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
130 0.7.7/docs/0_6_Summary.html
@@ -0,0 +1,130 @@
+<html>
+ <head>
+ <title>0_6_Summary</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">0_6_Summary</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <h1><a name="Introduction"></a>Introduction<a href="#Introduction" class="section_anchor"></a></h1>
+ <p>The sbt 0.6.x series attempts to merge ideas from <tt>xsbt</tt> (experimental <tt>sbt</tt> components) into the main <tt>sbt</tt>. It should be considered less stable currently than 0.5.x because of extensive internal changes to <tt>sbt</tt>. </p>
+ <p>Please point out gaps in the documentation, areas that need clarification, or anything you'd like more details about. Your time experimenting is appreciated! </p>
+ <p>There are currently three major improvements in 0.6.x over previous versions: </p>
+ <ol>
+ <li>Generalize the launcher to be able to launch applications other than <tt>sbt</tt>. Additionally, the launcher configuration for <tt>sbt</tt> can be customized. </li>
+ <li>Separate the version of Scala used to build a project from the version used to run <tt>sbt</tt> and the project definition. The benefit of this is that <tt>sbt</tt> no longer has to be built against the version of Scala you are using for your project. </li>
+ <li>Support test frameworks through the uniform test interface. The benefit of this is that you should not have to wait for <tt>sbt</tt> to be updated to support new versions of test frameworks. Also, the version of Scala used by a test framework should not matter to <tt>sbt</tt>. In particular, this should let you use test frameworks compiled against 2.8. </li>
+ </ol>
+ <p></p>
+ <p>The ongoing aim for the rest of the series is to further modularize <tt>sbt</tt> and address issues that will come up due to these changes. </p>
+ <h1><a name="0.6"></a>0.6<a href="#0.6" class="section_anchor"></a></h1>
+ <h2><a name="New_Launcher"></a>New Launcher<a href="#New_Launcher" class="section_anchor"></a></h2>
+ <p>The launcher has been substantially rewritten so that it is not specific to <tt>sbt</tt>. For complete details on it, see 0_6_Launcher. That page describes the new launcher, including how to make an application launchable. Basically, you provide a configuration file to the launcher and have your application entry point implement an interface. </p>
+ <p>The following can now be done by modifying the default <tt>sbt</tt> configuration file for the launcher: </p>
+ <ul>
+ <li>Specify the default values for properties for new projects, such as the project name and version, the <tt>sbt</tt> version, and the Scala version </li>
+ <li>Control which repositories are used for downloading Scala versions and <tt>sbt</tt> </li>
+ <li>Fix the Scala version for project definitions and the <tt>sbt</tt> version for all projects on your machine, regardless of the settings for project/build.properties. </li>
+ <li>Configure project searching (previously configurable by system property) </li>
+ <li>Configure the location of the boot directory, including making it shared across a machine. </li>
+ </ul>
+ <p></p>
+ <p>You can also set up separate scripts to use different configuration files. For example, you might have a 'sbt-quick' script. The configuration file used could specify that new projects are set up without prompting, but instead use your specified defaults for properties. </p>
+ <h3><a name="Compatibility"></a>Compatibility<a href="#Compatibility" class="section_anchor"></a></h3>
+ <p>The new launcher can only launch the new 0.6.x series of <tt>sbt</tt> and the new series of <tt>sbt</tt> requires the new launcher. </p>
+ <h3><a name="Size/Speed"></a>Size/Speed<a href="#Size/Speed" class="section_anchor"></a></h3>
+ <p>I've managed to keep the launcher jar the same size and start up in the same time. However, the corresponding version of <tt>sbt</tt> is about 30% slower on startup and is bigger in size. This is partly due to a temporary duplication of some functionality between <tt>sbt</tt> and the new <tt>xsbt</tt> components during the transition. </p>
+ <h3><a name="Usability"></a>Usability<a href="#Usability" class="section_anchor"></a></h3>
+ <p>Now is a good time for users to point out usability issues and possible improvements related to launching- startup, reload, and retrieving sbt and Scala. The Ivy &quot;errors&quot; about unknown resolvers that are especially apparent in the launcher (including the previous version of the launcher) is a known issue to the Ivy developers. See issue IVY-758 as reported by the Gradle developers. </p>
+ <h2><a name="Scala_Version_Handling"></a>Scala Version Handling<a href="#Scala_Version_Handling" class="section_anchor"></a></h2>
+ <p>The new launcher provides essential support for implementing the separation of Scala versions. It also provided an opportunity to clean up cross-building and project reloading. Please note the changes in the following section on compatibility. </p>
+ <h3><a name="Compatibility"></a>Compatibility<a href="#Compatibility" class="section_anchor"></a></h3>
+ <ul>
+ <li>The compiler can no longer be forked. It should not be necessary anymore. </li>
+ <li>Forking the <tt>run</tt> action requires a new approach. See the section below (after Configuring Versions) </li>
+ <li>The <tt>reboot</tt> action is gone. <tt>reload</tt> now implies a <tt>reboot</tt>. </li>
+ <li>The <tt>scala.version</tt> property has been split into <tt>build.scala.versions</tt> and <tt>def.scala.version</tt>. This is explained in more detail in the next section. </li>
+ <li>The <tt>ScalaVersion</tt> object is gone. Use the <tt>buildScalaVersion</tt> method to obtain the version of Scala currently being used to build the project. </li>
+ <li><tt>build.scala.versions</tt> has to be read in <tt>sbt.Project</tt>, which means that all properties are read in <tt>sbt.Project</tt>. Therefore, properties need to be declared with <tt>lazy val</tt> and not just <tt>val</tt> (or else they will not be initialized and an error will be generated). If you do not declare custom properties, this does not affect you. </li>
+ </ul>
+ <h3><a name="Configuring_Versions"></a>Configuring Versions<a href="#Configuring_Versions" class="section_anchor"></a></h3>
+ <p>The version used to run <tt>sbt</tt> and used for compiling the project definition is set by the build property <tt>def.scala.version</tt>. The only valid value for this property is 2.7.7. This means that <tt>sbt</tt> runs in 2.7.7 and your project definition is compiled against 2.7.7. As described below, the version of Scala used to build your project is independent of this version. </p>
+ <p>The 'build.scala.versions' property is a whitespace separated list of versions to use when cross building (that is, when doing '+compile' or similar). The first version in the list is used for single-version actions (actions not prefixed with '+'). Allowed versions should (in theory) be any Scala version 2.7.2 or later, including <tt>2.8.0.Beta1-RC6</tt>, <tt>2.8.0-SNAPSHOT</tt>, and <tt>2.8.0-20091230.025722-+</tt>. </p>
+ <p>To change the version of Scala used for building at the interactive prompt or as part of a sequence of commands from the command line, use '++version'. 'version' does not need to be listed in 'build.scala.versions'. To set the version and run an action, use '++version action' (space between version and action). In both cases, the new version is used until the next '++' or on 'reload' or a restart. '+action' is now expanded to '++v1 action', '++v2 action', ... for versions <tt>v1,v2,...</tt> in 'build.scala.versions'. </p>
+ <p>It should be easy to use locally built Scala versions now. Declare local versions by overriding the 'localScala' method in your project definition. This method should return a <tt>Seq[ScalaInstance]</tt>, where the 'defineScala' method is used to create <tt>ScalaInstance</tt>s. The two variants are: </p>
+ <ul>
+ <li><tt>defineScala(label: String, scalaHome: File)</tt> </li>
+ <li><tt>defineScala(scalaHome: File)</tt> </li>
+ </ul>
+ <tt>label</tt> is the string to use to refer to the Scala instance in
+ <tt>build.scala.versions</tt> or with the
+ <tt>++version</tt>command. The label cannot contain spaces. For example, you might use
+ <tt>2.8.0-quick</tt> or
+ <tt>2.8.0-local</tt> as labels for a locally built Scala. The single argument variant uses the version in the Scala jars for the label. To see the version to use in this case, you can do:
+ <p></p>
+ <pre class="prettyprint"> &gt; console-project
+...
+ &gt; localScala</pre>
+ <p>As an example, assume <tt>scalaHome</tt> is appropriately set. The following registers the result of 'ant quick' with <tt>sbt</tt>: </p>
+ <pre class="prettyprint"> override def localScala =
+ defineScala(&quot;2.8.0-quick&quot;, (scalaHome / &quot;build&quot; / &quot;pack&quot; ).asFile) :: Nil</pre>
+ <p>You could then include '2.8.0-quick' in <tt>build.scala.versions</tt> or as a valid version to switch to as in: </p>
+ <pre class="prettyprint">++2.8.0-quick console</pre>
+ <h3><a name="Forking_run"></a>Forking <tt>run</tt><a href="#Forking_run" class="section_anchor"></a></h3>
+ <p>Because the build and definition Scala versions are now separated, the way to declare the options for forking the <tt>run</tt> action has changed. The following examples demonstrate the new way: </p>
+ <pre class="prettyprint"> override def fork = forkRun
+ override def fork =
+ forkRun(new File(&quot;different-working-directory&quot;))
+ override def fork =
+ forkRun(&quot;-Xmx8G&quot; :: Nil)
+ override def fork =
+ forkRun(
+ Some(new File(&quot;different-working-directory&quot;)),
+ forkRun(&quot;-Xmx8G&quot; :: Nil)
+ )</pre>
+ <h2><a name="Uniform_Test_Interface"></a>Uniform Test Interface<a href="#Uniform_Test_Interface" class="section_anchor"></a></h2>
+ <p><tt>sbt</tt> now supports test frameworks through the <a href="http://github.com/harrah/test-interface" rel="nofollow">uniform test interface</a>, which itself is a work in progress. This should make <tt>sbt</tt> more independent of test frameworks that can implement the test interface. <tt>sbt</tt> only needs to know the name of the class implementing the interface. <tt>sbt</tt> no longer needs to be recompiled in order to support new frameworks, new versions of frameworks, or frameworks compiled against different Scala versions. </p>
+ <p>Josh Cough has implemented this interface for ScalaTest and Sweet, Rickard Nilsson has done it for ScalaCheck, and Eric Torreborre has done it for specs. You will need the latest snapshots of these libraries. </p>
+ <p>Other test frameworks that implement the interface will be added to <tt>sbt</tt>'s list of known frameworks. It is easy enough to use a framework not yet known to <tt>sbt</tt>, however. For example, if a new test framework implements the interface and <tt>sbt</tt> has not been updated to know about it yet, use that snapshot as a normal library in your project and add the following to your project definition: </p>
+ <pre class="prettyprint">override def testFrameworks = super.testFrameworks ++
+ new TestFramework(&quot;org.example.ExampleFramework&quot;)</pre>
+ <p>where <tt>org.example.ExampleFramework</tt> is replaced with the name of the class that implements the test interface. </p>
+ <h1><a name="Using_0.6.x"></a>Using 0.6.x<a href="#Using_0.6.x" class="section_anchor"></a></h1>
+ <p>To use the 0.6.x series, you need to get the new launcher and set up a script to run it as before. I call my script <tt>xsbt</tt> to avoid confusion with the stable 0.5.x series. Something like: </p>
+ <pre class="prettyprint"> java -jar xsbt-launch-0.6.9.jar &quot;$@&quot;</pre>
+ <p>On an existing project, you need to set <tt>sbt.version</tt> to 0.6.9. You will be prompted for the version(s) of Scala to use for your project, since this is a new property (<tt>build.scala.versions</tt>, as mentioned in the Scala Version Handling section). Check the Compatibility section above when using 0.6.x on an existing project. Again, there are some unavoidable, but hopefully minor, incompatibilies so try it out on a test project or a branch. </p>
+ <h1><a name="Building_Locally"></a>Building Locally<a href="#Building_Locally" class="section_anchor"></a></h1>
+ <p>The procedure for building <tt>sbt</tt> locally has changed, but it still uses the last stable <tt>sbt</tt> release (0.5.6) to build. <tt>sbt</tt> is currently split across two projects for this experiment, so there are two <tt>'publish-local'</tt>s that need to be run. From scratch, setting up <tt>sbt</tt> 0.6.x locally would look like: </p>
+ <pre class="prettyprint">$ git clone git://github.com/harrah/xsbt.git
+$ cd xsbt
+$ sbt update proguard &quot;project Compile&quot; publish-local &quot;project Test&quot; publish-local
+
+$ cd ..
+$ git clone git://github.com/harrah/sbt.git
+$ cd sbt
+$ git checkout --track -b using-xsbt origin/using-xsbt
+$ cd scripted
+$ sbt update publish-local
+$ cd ..
+$ sbt update publish-local</pre>
+ <p>The launcher jar created by the <tt>proguard</tt> action is located at <tt>xsbt/target/xsbt-launch-0.6.x.jar</tt>. </p>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
71 0.7.7/docs/ActionContent.html
@@ -0,0 +1,71 @@
+<html>
+ <head>
+ <title>ActionContent</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">ActionContent</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <p></p>
+ <ul>
+ <li><a href="#Introduction">Introduction</a></li>
+ <li><a href="#Error_Handling">Error Handling</a></li>
+ <li><a href="#File_Utilities">File Utilities</a></li>
+ <ul>
+ <li><a href="#Jar/Zip/GZip_Files">Jar/Zip/GZip Files</a></li>
+ <li><a href="#Pack200">Pack200</a></li>
+ <li><a href="#Signing_Jars">Signing Jars</a></li>
+ <li><a href="#Copying/Downloading">Copying/Downloading</a></li>
+ <li><a href="#Creating_Directories_and_Files">Creating Directories and Files</a></li>
+ <li><a href="#Removing_Directories_and_Files">Removing Directories and Files</a></li>
+ <li><a href="#Temporary_Directories">Temporary Directories</a></li>
+ <li><a href="#General_I/O">General I/O</a></li>
+ <li><a href="#Access_to_Jars">Access to Jars</a></li>
+ </ul>
+ </ul>
+ <p></p>
+ <h1><a name="Introduction"></a>Introduction<a href="#Introduction" class="section_anchor"></a></h1>
+ <p>This page provides assistance writing the code that defines the work of an action. To use external libraries or reuse code between projects, see <a href="SbtPlugins">SbtPlugins</a>. You can also directly put libraries in <tt>project/build/lib</tt> and they can be used from your project definition. </p>
+ <h1><a name="Error_Handling"></a>Error Handling<a href="#Error_Handling" class="section_anchor"></a></h1>
+ <p>This section describes error handling in <tt>sbt</tt>. When you create a task, you pass code that returns <tt>None</tt> if the action executes normally or <tt>Some(errorMessage)</tt> if an error occurs. This is the way <tt>sbt</tt> works with errors internally and how it indicates recoverable errors when you use utility methods. Note that if you throw an exception in your code, <tt>sbt</tt> will handle it. </p>
+ <p>There are methods in <tt>sbt.Control</tt> for working with code that can throw exceptions. </p>
+ <h1><a name="File_Utilities"></a>File Utilities<a href="#File_Utilities" class="section_anchor"></a></h1>
+ <p><tt>sbt</tt> includes several methods for dealing with the filesystem in <tt>sbt.FileUtilities</tt>. Their capabilities are described below. The <a href="http://simple-build-tool.googlecode.com/svn/artifacts/latest/api/sbt/FileUtilities$object.html" rel="nofollow">API documentation</a> describes the details of using the methods. </p>
+ <h2><a name="Jar/Zip/GZip_Files"></a>Jar/Zip/GZip Files<a href="#Jar/Zip/GZip_Files" class="section_anchor"></a></h2>
+ <p><tt>FileUtilities</tt> contains methods to create jar, zip or gzip files and for unzipping files. You can unzip from a <tt>Path</tt>, <tt>URL</tt>, <tt>File</tt>, or <tt>InputStream</tt> and you can optionally filter the files that are extracted using a <tt>NameFilter</tt>. You can jar, zip, or gzip the files selected by a <tt>PathFinder</tt> and optionally descend into directories recursively, which is useful if you just want to specify the directories to archive. (See Path for details on <tt>Path</tt>, <tt>PathFinder</tt> and <tt>NameFilter</tt>). </p>
+ <h2><a name="Pack200"></a>Pack200<a href="#Pack200" class="section_anchor"></a></h2>
+ <p>This is not in <tt>FileUtilities</tt>, but is in <tt>sbt.Pack</tt>. You can pack and unpack a jar file with either default options or explicitly specified options as given in the <tt>java.util.jar.Pack200.Packer</tt> class. </p>
+ <h2><a name="Signing_Jars"></a>Signing Jars<a href="#Signing_Jars" class="section_anchor"></a></h2>
+ <p>This is not in <tt>FileUtilities</tt>, but is in <tt>sbt.SignJar</tt>. It signs or verifies a jar file using the <tt>jarsigner</tt> executable, which must be on the system path. </p>
+ <h2><a name="Copying/Downloading"></a>Copying/Downloading<a href="#Copying/Downloading" class="section_anchor"></a></h2>
+ <p>There are several methods for copying files and data. You can transfer data from an <tt>InputStream</tt> to an <tt>OutputStream</tt> and optionally close the <tt>InputStream</tt> on completion. You can download data from a <tt>URL</tt> to a <tt>File</tt>. You can copy a single file or a single directory (recursively). There are also methods to copy a list of files to a directory, optionally flattening the file hierarchy in the process. Additionally, there is a method to mirror/synchronize the contents of two directories. </p>
+ <h2><a name="Creating_Directories_and_Files"></a>Creating Directories and Files<a href="#Creating_Directories_and_Files" class="section_anchor"></a></h2>
+ <p>There are methods to create a directory and all parent directories and to &quot;touch&quot; a file (create it if it doesn't exist or update its last modified time if it does). </p>
+ <h2><a name="Removing_Directories_and_Files"></a>Removing Directories and Files<a href="#Removing_Directories_and_Files" class="section_anchor"></a></h2>
+ <p>There is a method to recursively delete directories and files. </p>
+ <h2><a name="Temporary_Directories"></a>Temporary Directories<a href="#Temporary_Directories" class="section_anchor"></a></h2>
+ <p>There is a method to create a temporary directory and a method to execute code using a temporary directory that is automatically deleted after the code completes. </p>
+ <h2><a name="General_I/O"></a>General I/O<a href="#General_I/O" class="section_anchor"></a></h2>
+ <p>There are methods to read from, write to, and append to files, streams, and readers/writers and let <tt>FileUtilities</tt> open and close the streams, readers, or writers. There are convenience methods to read or write text or an array of bytes to or from a <tt>File</tt>. </p>
+ <h2><a name="Access_to_Jars"></a>Access to Jars<a href="#Access_to_Jars" class="section_anchor"></a></h2>
+ <p>There are methods to get the jar file or directory containing a given class. </p>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
73 0.7.7/docs/Artifacts.html
@@ -0,0 +1,73 @@
+<html>
+ <head>
+ <title>Artifacts</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">Artifacts</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <h1><a name="Artifacts"></a>Artifacts<a href="#Artifacts" class="section_anchor"></a></h1>
+ <h2><a name="Defining_Artifacts"></a>Defining Artifacts<a href="#Defining_Artifacts" class="section_anchor"></a></h2>
+ <p>By default, the published artifact is a war for <tt>DefaultWebProject</tt> and a jar for <tt>DefaultProject</tt>. You can declare other types of artifacts to publish by defining <tt>Artifact</tt> instances in your project definition. Multiple artifacts are allowed. </p>
+ <p>The basic constructions look like: </p>
+ <pre class="prettyprint"> val art = Artifact(&quot;name&quot;, &quot;type&quot;, &quot;extension&quot;)
+ val art2 = Artifact(&quot;name&quot;, &quot;classifier&quot;)
+ val art3 = Artifact(&quot;name&quot;, url: URL)
+ val art4 = Artifact(&quot;name&quot;, Map(&quot;extra1&quot; -&gt; &quot;value1&quot;, &quot;extra2&quot; -&gt; &quot;value2&quot;))</pre>
+ <p>For example: </p>
+ <pre class="prettyprint"> val myZip = Artifact(&quot;myproject&quot;, &quot;zip&quot;, &quot;zip&quot;)
+ val myImg = Artifact(&quot;myproject&quot;, &quot;image&quot;, &quot;jpg&quot;)
+ val for15 = Artifact(&quot;myproject&quot;, &quot;jdk15&quot;)</pre>
+ <p>See the <a href="http://ant.apache.org/ivy/history/2.1.0/ivyfile/dependency-artifact.html" rel="nofollow">Ivy documentation</a> for more details on artifacts. See the <a href="http://simple-build-tool.googlecode.com/svn/artifacts/latest/api/sbt/Artifact$object.html" rel="nofollow">Artifact API documentation</a> for combining the parameters above and specifying <a href="ManagedConfigurations">configurations</a> and extra attributes. </p>
+ <h3><a name="Details"></a>Details<a href="#Details" class="section_anchor"></a></h3>
+ <p>These declarations are collected and are made available under the <tt>artifacts</tt> method of your project definition. You could alternatively define your artifacts directly by overriding <tt>artifacts</tt>: </p>
+ <pre class="prettyprint"> override def artifacts =
+ Artifact(&quot;myproject&quot;, &quot;zip&quot;, &quot;zip&quot;) ::
+ Artifact(&quot;myproject&quot;, &quot;jdk15&quot;) ::
+ Nil</pre>
+ <p>To specify artifacts directly in addition to reflective definitions as above, add the artifacts to <tt>super.artifacts</tt>: </p>
+ <pre class="prettyprint"> override def artifacts =
+ super.artifacts ++ Seq( Artifact(&quot;myproject&quot;, &quot;zip&quot;, &quot;zip&quot;) )</pre>
+ <p>The <tt>artifacts</tt> method is then used to attach the artifacts to the project ID: </p>
+ <pre class="prettyprint"> def projectID =
+ ModuleID(organization, moduleID, version.toString) artifacts(artifacts : _*)</pre>
+ <p>Another alternative is to directly override <tt>projectID</tt> to specify your artifacts. </p>
+ <h2><a name="Sources/Docs"></a>Sources/Docs<a href="#Sources/Docs" class="section_anchor"></a></h2>
+ <p>A common need is to publish source and doc artifacts. The declarations would look like: </p>
+ <pre class="prettyprint"> // make the jar names have the expected format
+ override def packageDocsJar = defaultJarPath(&quot;-javadoc.jar&quot;)
+ override def packageSrcJar= defaultJarPath(&quot;-sources.jar&quot;)
+
+ // define the artifacts
+ val sourceArtifact = Artifact.sources(artifactID)
+ val docsArtifact = Artifact.javadoc(artifactID)</pre>
+ <p>See <a href="Publishing">Publishing</a> for the full details on publishing sources and docs. </p>
+ <h2><a name="Using_Dependencies_with_Artifacts"></a>Using Dependencies with Artifacts<a href="#Using_Dependencies_with_Artifacts" class="section_anchor"></a></h2>
+ <p>To specify the artifacts to use from a dependency that has custom or multiple artifacts, use the <tt>artifacts</tt> method on your dependencies. For example: </p>
+ <pre class="prettyprint"> val dep = &quot;org&quot; % &quot;name&quot; % &quot;rev&quot; artifacts(Artifact(&quot;name&quot;, &quot;type&quot;, &quot;ext&quot;))</pre>
+ <p>The <tt>from</tt> and <tt>classifer</tt> methods (described on the <a href="http://code.google.com/p/simple-build-tool/wiki/LibraryManagement" rel="nofollow">Basics page</a>) are actually convenience methods that translate to <tt>artifacts</tt>: </p>
+ <pre class="prettyprint"> def from(url: String) = artifacts( Artifact(name, new URL(url)) )
+ def classifier(c: String) = artifacts( Artifact(name, c) )</pre>
+ <p>That is, the following two dependency declarations are equivalent: </p>
+ <pre class="prettyprint"> val testng = &quot;org.testng&quot; % &quot;testng&quot; % &quot;5.7&quot; classifier &quot;jdk15&quot;
+ val testng = &quot;org.testng&quot; % &quot;testng&quot; % &quot;5.7&quot; artifacts( Artifact(&quot;testng&quot;, &quot;jdk15&quot;) )</pre>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
40 0.7.7/docs/Build.html
@@ -0,0 +1,40 @@
+<html>
+ <head>
+ <title>Build</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">Build</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <h1><a name="Building_sbt"></a>Building <tt>sbt</tt><a href="#Building_sbt" class="section_anchor"></a></h1>
+ <h2><a name="Background"></a>Background<a href="#Background" class="section_anchor"></a></h2>
+ <p><tt>sbt</tt> now uses git for version control. You can find the source on github. As of 0.7.2, <tt>sbt</tt> is at <a href="http://github.com/harrah/xsbt" rel="nofollow">http://github.com/harrah/xsbt</a>. The 'master' branch is for 0.7.x stable releases, while the 0.9 branch is for the 0.9.x development series. </p>
+ <p>Test support was separated out to work across a <a href="http://github.com/harrah/test-interface" rel="nofollow">uniform test interface</a>. Because of this, <tt>sbt</tt> no longer needs to be compiled against test frameworks. New test frameworks that implement the uniform test interface can be used by <tt>sbt</tt> without needing to recompile <tt>sbt</tt>, as was the case previously. In order to provide compatibility with <tt>sbt</tt> 0.5.6, there is <a href="http://github.com/harrah/test-compat" rel="nofollow">an implementation</a> of the test interface for Scala test frameworks released before the interface existed. </p>
+ <h2><a name="Instructions"></a>Instructions<a href="#Instructions" class="section_anchor"></a></h2>
+ <p>The latest <tt>sbt</tt> release (0.7.7) is used to build. From scratch, building <tt>sbt</tt> locally looks like: </p>
+ <pre class="prettyprint">$ git clone git://github.com/harrah/xsbt.git
+$ cd xsbt
+$ sbt update proguard &quot;project Simple Build Tool&quot; publish-local</pre>
+ <p>The launcher jar created by the <tt>proguard</tt> action is located at <tt>xsbt/target/sbt-launch-0.7.x.jar</tt>. </p>
+ <h2><a name="Usage"></a>Usage<a href="#Usage" class="section_anchor"></a></h2>
+ <p>Set the <tt>sbt.version</tt> in the project you want to use this in to be <tt>0.7.8-SNAPSHOT</tt>. If you rebuild sbt, you'll need to remove <tt>project/boot</tt> for that project because <tt>sbt</tt> does not recheck a version once it is retrieved to a project. </p>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
198 0.7.7/docs/BuildConfiguration.html
@@ -0,0 +1,198 @@
+<html>
+ <head>
+ <title>BuildConfiguration</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">BuildConfiguration</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <h1><a name="Introduction"></a>Introduction<a href="#Introduction" class="section_anchor"></a></h1>
+ <p>This page describes build configuration for when the default actions or paths are not sufficient or appropriate for your project. </p>
+ <p></p>
+ <ul>
+ <li><a href="#Introduction">Introduction</a></li>
+ <li><a href="#Example">Example</a></li>
+ <li><a href="#Configuration_Details">Configuration Details</a></li>
+ <li><a href="#Specifying_Options">Specifying Options</a></li>
+ <ul>
+ <li><a href="#Compile_Options">Compile Options</a></li>
+ <li><a href="#Run_Options">Run Options</a></li>
+ <li><a href="#Package_Options">Package Options</a></li>
+ <li><a href="#Document_Options">Document Options</a></li>
+ <li><a href="#Test_Options">Test Options</a></li>
+ </ul>
+ <li><a href="#Changing_Paths">Changing Paths</a></li>
+ </ul>
+ <p></p>
+ <h1><a name="Example"></a>Example<a href="#Example" class="section_anchor"></a></h1>
+ <p><tt>sbt</tt> is configured by creating a project definition in the <tt>project/build</tt> directory. A project definition is a class (written in Scala) that implements <tt>sbt.Project</tt>. This is usually done by extending <tt>sbt.DefaultProject</tt>. The following is an example of adding a Hello World task to your build. It assumes you have already initialized your project as described on the <a href="Setup">Setup</a> page. </p>
+ <p><tt>project/build/HelloWorld.scala</tt> </p>
+ <pre class="prettyprint">import sbt._
+
+class HelloWorldProject(info: ProjectInfo) extends DefaultProject(info)
+{
+ lazy val hi = task { println(&quot;Hello World&quot;); None }
+}</pre>
+ <p>If you have <tt>sbt</tt> running, you need to reload the project with the new project definition: </p>
+ <pre class="prettyprint">&gt; reload</pre>
+ <p>Otherwise, start up sbt. Execute <tt>hi</tt>: </p>
+ <pre class="prettyprint">&gt; hi
+...
+Hello World
+...</pre>
+ <p>The details of writing tasks are described on the <a href="CustomActions">Creating/Modifying Actions</a> page. </p>
+ <h1><a name="Configuration_Details"></a>Configuration Details<a href="#Configuration_Details" class="section_anchor"></a></h1>
+ <p><tt>sbt</tt> only recompiles a project definition on startup or when invoking the interactive command <tt>reload</tt>. Therefore, if you are running in interactive mode, invoke <tt>reload</tt> after making changes to your project definition for the changes to take effect. </p>
+ <p>The <tt>project/build</tt> directory is a project itself. Therefore, you can add jars to the <tt>project/build/lib</tt> directory to use from your project definition. You can also use multiple sources for your project definition. The only requirement is there must be exactly one public, concrete subclass of <tt>Project</tt> with a constructor that accepts a <tt>ProjectInfo</tt> instance. <tt>sbt</tt> finds this subclass when it compiles the project definition, so the names of source files and classes are not important. </p>
+ <h1><a name="Specifying_Options"></a>Specifying Options<a href="#Specifying_Options" class="section_anchor"></a></h1>
+ <p>The general way to configure your build is to override one or more methods in your project definition. For example, the default options for the <tt>compile</tt> task are defined in the <tt>compileOptions</tt> method: </p>
+ <pre class="prettyprint"> def compileOptions: Seq[CompileOption] = Deprecation :: Nil</pre>
+ <p><tt>Deprecation</tt> is a val in <tt>ScalaProject</tt> that is an instance of <tt>CompileOption</tt> and represents the command line <tt>scalac</tt> option <tt>-deprecation</tt>. To additionally specify the <tt>-unchecked</tt> command line option, override <tt>compileOptions</tt> in your project definition (class <tt>TestProject</tt> above): </p>
+ <pre class="prettyprint"> override def compileOptions = super.compileOptions ++ Seq(Unchecked)</pre>
+ <p>The currently available options for tasks are listed below. </p>
+ <h2><a name="Compile_Options"></a>Compile Options<a href="#Compile_Options" class="section_anchor"></a></h2>
+ <p>Method <tt>compileOptions</tt> specifies additional options for task <tt>compile</tt> to pass to the Scala compiler. It has type <tt>Seq[CompileOption]</tt>. There is a similar method <tt>testCompileOptions</tt> for <tt>test-compile</tt>. Provided options are: </p>
+ <ul>
+ <li><tt>Deprecation</tt> </li>
+ <li><tt>Unchecked</tt> </li>
+ <li><tt>ExplainTypes</tt> </li>
+ <li><tt>Optimize</tt> </li>
+ <li><tt>Verbose</tt> </li>
+ <li><tt>DisableWarnings</tt> </li>
+ <li><tt>target(t: Target.Value)</tt> (accepts values of the <tt>Target</tt> enumeration: <tt>Java1_5</tt>, <tt>Java1_4</tt>, <tt>Msil</tt>) </li>
+ <li><tt>MaxCompileErrors(max: Int)</tt> Specifies the maximum number of compiler errors to show. The default value is 100. </li>
+ <li><tt>compileOptions(options: String*)</tt> (for arbitrary options). Example: </li>
+ <p></p>
+ <pre class="prettyprint"> override def compileOptions = super.compileOptions ++
+ compileOptions(&quot;-encoding&quot;, &quot;utf8&quot;)</pre>
+ </ul>
+ <p>Method <tt>javaCompileOptions</tt> specifies the options passed to the Java compiler by the <tt>compile</tt> task. There is a similar method <tt>testJavaCompileOptions</tt> for <tt>test-compile</tt>. Currently, all options are specified by: </p>
+ <ul>
+ <li><tt>javaCompileOptions(option: String*)</tt> </li>
+ </ul>
+ <p></p>
+ <h2><a name="Run_Options"></a>Run Options<a href="#Run_Options" class="section_anchor"></a></h2>
+ <p>Method <tt>mainClass</tt> is of type <tt>Option[String]</tt> and specifies an optional main class to run when the <tt>run</tt> task is invoked. The default implementation specifies no main class (<tt>None</tt>). When <tt>mainClass</tt> is not specified, the <tt>run</tt> task will determine which class to run automatically. If exactly one main class is detected, it is run. If multiple main classes are detected, the user is prompted for which one to run. </p>
+ <h2><a name="Package_Options"></a>Package Options<a href="#Package_Options" class="section_anchor"></a></h2>
+ <p>If defined, the <tt>mainClass</tt> method specifies the value of the <tt>Main-Class</tt> attribute in the manifest. The <tt>manifestClassPath</tt>method, if defined, specifies the value of <tt>Class-Path</tt> attribute. Method <tt>packageOptions</tt> specifies general options for task <tt>package</tt> and is of type <tt>Seq[PackageOption]</tt>. Provided options are: </p>
+ <ul>
+ <li><tt>MainClass(mainClassName: String)</tt> Specifies the <tt>Main-Class</tt> attribute in the manifest. By default, this option is included with the value of the <tt>mainClass</tt> method if it is defined. When <tt>mainClass</tt> is not specified explicitly, the <tt>package</tt> task will try to determine which class to use automatically. If exactly one main class is detected, it is used. If multiple main classes are detected, a warning is printed and no <tt>Main-Class</tt> attribute is added to the manifest. </li>
+ <li><tt>ManifestAttributes(attributes: (java.util.jar.Attributes.Name, String)*)</tt> or <tt>ManifestAttributes(attributes: (String, String)*)</tt> Defines main attributes to add to the manifest. </li>
+ <li><tt>JarManifest(m: Manifest)</tt> Specifies the manifest to use for the jar. The default manifest includes the <tt>Main-Class</tt> attribute if <tt>mainClass</tt> (as described above) is not empty and the <tt>Class-Path</tt> attribute if <tt>manifestClassPath</tt> is not empty. </li>
+ </ul>
+ <p></p>
+ <h2><a name="Document_Options"></a>Document Options<a href="#Document_Options" class="section_anchor"></a></h2>
+ <p>Method <tt>documentOptions</tt> specifies the options for the API documentation tasks <tt>doc</tt> and <tt>docTests</tt>. Provided options are: </p>
+ <ul>
+ <li><tt>LinkSource</tt> </li>
+ <li><tt>NoComment</tt> </li>
+ <li><tt>access(access: Access.Value)</tt> </li>
+ <li><tt>documentBottom(bottomText: String)</tt> </li>
+ <li><tt>documentCharset(charset: String)</tt> </li>
+ <li><tt>documentTitle(title: String)</tt> </li>
+ <li><tt>documentFooter(footerText: String)</tt> </li>
+ <li><tt>documentHeader(headerText: String)</tt> </li>
+ <li><tt>stylesheetFile(path: Path)</tt> </li>
+ <li><tt>documentTop(topText: String)</tt> </li>
+ <li><tt>windowTitle(title: String)</tt> </li>
+ </ul>
+ <p></p>
+ <p>By default, a window and document title are specified in 2.7 and a document title is specified in 2.8 (window title does not exist at this time). </p>
+ <h2><a name="Test_Options"></a>Test Options<a href="#Test_Options" class="section_anchor"></a></h2>
+ <p>Method <tt>testOptions</tt> specifies the options for the <tt>test</tt> action. </p>
+ <ul>
+ <li><tt>ExcludeTests(tests: Iterable[String])</tt> Specifies the class names of tests that should not be run. </li>
+ <li><tt>TestFilter(filter: String =&gt; Boolean)</tt> Specifies a function that returns <tt>true</tt> if the test should be run. </li>
+ <li><tt>TestListeners(listeners: Iterable[TestReportListener])</tt> Specifies the reporters used when running tests. <tt>testOptions</tt> by default includes a reporter that sends output to the project logger. </li>
+ <li><tt>TestArgument(args: String*)</tt> Specifies arguments to pass to the test framework when running tests. </li>
+ <li><tt>TestArgument(tf: TestFramework, args: String*)</tt> Specifies arguments to pass to a specific test framework when running tests. </li>
+ </ul>
+ <p></p>
+ <h1><a name="Changing_Paths"></a>Changing Paths<a href="#Changing_Paths" class="section_anchor"></a></h1>
+ <p>The only paths in <tt>sbt</tt> that are completely fixed are the locations of the files in the <tt>project</tt> directory. The other paths, such as the path to sources, jars, and outputs, are configurable. Overriding the default paths is described in this section. See <a href="Paths">Paths</a> for details on constructing paths. </p>
+ <p>Paths in <tt>sbt</tt> are incrementally built up out of path components so that you can easily rename any directory in the path or modify the path structure. You should always refer to a path by its <tt>sbt</tt> method instead of constructing a <tt>Path</tt> literal. For example, always refer to the output directory as <tt>outputPath</tt> instead of <tt>path(&quot;target&quot;)</tt> and refer to the directory that classes are compiled to as <tt>mainCompilePath</tt> instead of <tt>&quot;target&quot; / &quot;classes&quot;</tt>. </p>
+ <p>The paths and the names used to construct them are defined in <tt>BasicProjectPaths</tt>, which is mixed into the default project definition, as members that you can override. If you only want to rename a directory, override the member that specifies the name. For example, to rename the output directory from <tt>target</tt> to <tt>build</tt>, </p>
+ <pre class="prettyprint"> override def outputDirectoryName = &quot;build&quot;</pre>
+ <p>The outputs for compilation and API documentation are defined as: </p>
+ <pre class="prettyprint"> def outputPath = crossPath(outputDirectoryName)
+
+ def mainCompilePath = outputPath / compileDirectoryName
+ def docPath = outputPath / docDirectoryName
+ def analysisPath = outputPath / analysisDirectoryName</pre>
+ <p>and so the directory name will be used by subpaths as well. </p>
+ <p>Similarly, you could rearrange the source directory from </p>
+ <pre class="prettyprint">src/
+ main/
+ scala/
+ resources/
+ test/
+ scala/
+ resources/</pre>
+ <p>to </p>
+ <pre class="prettyprint">src/
+resources/
+test-src/
+test-resources/</pre>
+ <p>by specifying the following in your project definition: </p>
+ <pre class="prettyprint"> override def mainScalaSourcePath = &quot;src&quot;
+ override def mainResourcesPath = &quot;resources&quot;
+
+ override def testScalaSourcePath = &quot;test-src&quot;
+ override def testResourcesPath = &quot;test-resources&quot;</pre>
+ <p>The paths directly used by the default actions are listed below. Other paths are only used to build up these paths. If redefined, care should be taken to keep these paths distinct from each other. </p>
+ <ul>
+ <li><tt>dependencyPath</tt>- This is the location of manually managed jars. </li>
+ <li><tt>managedDependencyPath</tt> - This is the location that automatic dependency management puts downloaded artifacts. When executed, the <tt>clean-lib</tt> action removes this directory. </li>
+ <li><tt>mainScalaSourcePath</tt> - The path to Scala sources comprising the project. </li>
+ <li><tt>mainJavaSourcePath</tt>: The path to the main Java sources for the project. </li>
+ <li><tt>mainResourcesPath</tt> - The path to resources to include in the project jar. </li>
+ <li><tt>testScalaSourcePath</tt> - The path to Scala sources defining tests. </li>
+ <li><tt>testJavaSourcePath</tt>: The path to the test Java sources for the project. </li>
+ <li><tt>testResourcesPath</tt> - The path to resources to include in the test jar. </li>
+ <li><tt>outputPath</tt> - The path containing all <tt>sbt</tt>-generated files (besides the managed artifacts that go in <tt>managedDependencyPath</tt>). All files generated by tasks should go in this directory. When executed, the <tt>clean</tt> action removes this directory. The following are subpaths of <tt>outputPath</tt>: </li>
+ <ul>
+ <li><tt>mainDocPath</tt> - The directory where API documentation for main sources is generated. </li>
+ <li><tt>testDocPath</tt> - The directory where API documentation for test sources is generated. </li>
+ <li><tt>mainCompilePath</tt> - The directory containing compiled main classes. </li>
+ <li><tt>testCompilePath</tt> - The directory containing compiled test classes. </li>
+ <li><tt>mainAnalysisPath</tt> - The directory used to store the analysis done at compile time. This includes files that record dependencies between source files. </li>
+ <li><tt>testAnalysisPath</tt> - The directory used to store the analysis done at test compile time. This includes files that record dependencies between source files and the class names of tests. </li>
+ </ul>
+ </ul>
+ <p></p>
+ <p>Additionally, web applications use these paths defined in <tt>sbt.WebProjectPaths</tt>: </p>
+ <ul>
+ <li><tt>webappPath</tt> - The location of web application resources. </li>
+ <li><tt>temporaryWarPath</tt> - The intermediate location used to create a war file or to run Jetty. It should be a subpath of <tt>outputPath</tt>. </li>
+ </ul> Webstart applications use the paths defined in
+ <tt>sbt.WebstartPaths</tt>:
+ <ul>
+ <li><tt>webstartOutputDirectory</tt> - The directory that the webstart products are created in. </li>
+ <li><tt>webstartMainJar</tt> - The jar that contains the entry point to the application. </li>
+ <li><tt>webstartLibDirectory</tt> - The directory that libraries will go in. </li>
+ <li><tt>jnlpFile</tt> - The location in the webstart output directory to write the JNLP XML file to. </li>
+ <li><tt>webstartZip</tt> - <tt>Some</tt> containing the location to write the zipped output directory to or <tt>None</tt> if no zip of the output directory should be created </li>
+ <li><tt>jnlpPath</tt> - The directory containing resources to copy to the webstart output directory. </li>
+ <li><tt>jnlpResourcesPath</tt> - The resources to include in the webstart output directory. By default this is everything in <tt>jnlpPath</tt> </li>
+ </ul>
+ <p></p>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
217 0.7.7/docs/ChangeDetectionAndTesting.html
@@ -0,0 +1,217 @@
+<html>
+ <head>
+ <title>ChangeDetectionAndTesting</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">ChangeDetectionAndTesting</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <p></p>
+ <ul>
+ <li><a href="#Introduction">Introduction</a></li>
+ <li><a href="#Partial_Recompilation">Partial Recompilation</a></li>
+ <ul>
+ <li><a href="#Example">Example</a></li>
+ </ul>
+ <li><a href="#Testing">Testing</a></li>
+ <li><a href="#Scripts">Scripts</a></li>
+ <ul>
+ <li><a href="#Syntax">Syntax</a></li>
+ <li><a href="#Example">Example</a></li>
+ <li><a href="#Commands">Commands</a></li>
+ <li><a href="#Further_Examples">Further Examples</a></li>
+ </ul>
+ <li><a href="#Running_Tests">Running Tests</a></li>
+ </ul>
+ <p></p>
+ <h1><a name="Introduction"></a>Introduction<a href="#Introduction" class="section_anchor"></a></h1>
+ <p>A general guideline for a build tool is that you should be able to trust its outputs. This is especially relevant to compiling Scala sources because the Scala compiler is slow and so there is a sizable amount of code in <tt>sbt</tt> to speed up compilation times. </p>
+ <p>One simple way <tt>sbt</tt> speeds up compilation is to run the compiler in the same virtual machine each time. (Note that this is not quite the same as <tt>fsc</tt>, which reuses the same compiler instance.) This approach results in a speedup by a factor of 2 after the first compile. </p>
+ <p>A second way to speed up compilation times is to only recompile sources that are out of date. This approach requires some work to do properly. A sign of failing to do it properly is users running <tt>clean</tt> as part of their normal development cycle. The motivation behind <tt>sbt</tt>'s scripted test framework is to try to find bugs in <tt>sbt</tt>'s partial recompilation so that compilation works as expected and <tt>clean</tt> is something you don't need to do to get correct outputs. </p>
+ <p>The basic steps to create a scripted test are: </p>
+ <ol>
+ <li>Create a project that will form the base </li>
+ <li>Determine the changes to make to that project and any actions to invoke on the project </li>
+ <li>Create the files comprising the changes </li>
+ <li>Create a script that consists of statements that apply the changes and invoke actions on the project, declaring whether the actions should succeed or fail. </li>
+ </ol>
+ <p></p>
+ <p>The first part discusses partial recompilation in <tt>sbt</tt> and the second part describes scripted tests. </p>
+ <h1><a name="Partial_Recompilation"></a>Partial Recompilation<a href="#Partial_Recompilation" class="section_anchor"></a></h1>
+ <p>You have a set of Scala source files that you would like to compile. After the initial compilation, you typically only modify some of those files before recompiling. This section describes how <tt>sbt</tt> determines which files have been changed and which files need to be recompiled. </p>
+ <p>The steps to partial recompilation are generally: </p>
+ <ol>
+ <li>Determine which sources have been modified. </li>
+ <li>Determine which sources need to be recompiled. </li>
+ <li>Remove outdated classes. </li>
+ <li>Recompile. </li>
+ </ol>
+ <p></p>
+ <p>There are a few indications that a source has changed: </p>
+ <ol>
+ <li>It no longer exists. </li>
+ <li>Its last modified time is more recent than the timestamp for the last compile. </li>
+ <li>Its last modified time is more recent than the last modified time of one of the classes produced from it. </li>
+ <li>Its SHA or MD5 hash is different from the hash computed when the last compile was done. </li>
+ <li>One of the classes generated from it does not exist anymore. </li>
+ <li>Its last modified time is older than that of one of the libraries it depends on </li>
+ </ol>
+ <p></p>
+ <p>Once a source is detected as out of date, there are three recompilation strategies: </p>
+ <ol>
+ <li>Recompile only the sources directly out of date. </li>
+ <li>Recompile the sources directly out of date and all sources that (transitively) depend on them. </li>
+ <li>Recompile all sources. </li>
+ </ol>
+ <p></p>
+ <p>Finally, when a source is out of date (directly or indirectly), its classes should be deleted. </p>
+ <p>Through version 0.3.6, <tt>sbt</tt> used methods 1, 3, 5, and 6 combined to detect changes and recompilation strategy 2. Version 0.3.7 and higher of <tt>sbt</tt> substitutes change detection method 4 (comparing hashes) for method 3 (comparing last modified times) because of the following problems with method 3: </p>
+ <ol>
+ <li>Changes to a source that produces no classes are not detected (works properly with change detection method 2 or 4). </li>
+ <li>Changes to a source between starting a compilation and finishing it are not detected (works properly with 2 or 4). </li>
+ <li>The resolution of the last modified time of a file can be as coarse as 1 second for many filesystems (addressed by 4). </li>
+ </ol>
+ <p>The last issue was especially a problem when implementing the scripted tests. An automated test script could setup, compile, update, and compile again within a second. The second compile wouldn't detect any changes because the last modified times were the same. </p>
+ <p>One problem with hashing, though, is that it reads in every source file to calculate its hash. As a rough idea, this might take about 1 second per 10 MB of sources on a local filesystem. This mainly affects how long it takes to run <tt>compile</tt> on a project without any changes. Of course, change detection is configurable, so you can use the last modified method if desired. </p>
+ <h2><a name="Example"></a>Example<a href="#Example" class="section_anchor"></a></h2>
+ <p>As an example, consider the following two definitions: </p>
+ <p><tt>A.scala</tt> </p>
+ <pre class="prettyprint">object A {
+ val x = B.y
+}</pre>
+ <p><tt>B.scala</tt> </p>
+ <pre class="prettyprint">object B {
+ val y = 5
+}</pre>
+ <p>Now, consider what happens if you were to delete <tt>B.scala</tt> but do not update <tt>A.scala</tt>. When you recompile, you should get an error because <tt>B</tt> no longer exists for <tt>A</tt> to reference. </p>
+ <p>The first problem occurs if you do not recompile <tt>A.scala</tt>. This would happen if you do not take source dependencies into account and you only recompile directly modified sources (here, <tt>A.scala</tt> is out of date because it depends on <tt>B.scala</tt>, but <tt>A.scala</tt> is not directly modified). A solution for a build system without source dependency tracking would be to recompile all sources. Alternatively, it could omit <tt>A.scala</tt> from recompilation and consequently require the user to do a full clean and then compile in order to get a proper build. </p>
+ <p>The second problem is that if you do not delete the classes for <tt>B</tt>, the compiler will still find the classes for <tt>B</tt> in the output directory. So, there will not be a compiler error even though you have recompiled <tt>A.scala</tt>. This shows that it is necessary to track the classes generated from a source file. You want to delete the classes for the sources being recompiled but not delete the classes for the sources not being recompiled. </p>
+ <h1><a name="Testing"></a>Testing<a href="#Testing" class="section_anchor"></a></h1>
+ <p>The scripted test framework is used to verify that <tt>sbt</tt> handles cases such as that described above. The steps to create a test are: </p>
+ <ol>
+ <li>Create an initial project in <tt>src/sbt-test/&lt;test-group&gt;/&lt;test-name&gt;/</tt> </li>
+ <li>Determine a set of changes to apply to the project (put any new or modified files in a sub-directory called <tt>changes/</tt>) </li>
+ <li>Create a script called <tt>test</tt> in the project directory that modifies the project and runs actions on the project </li>
+ <li>Run the tests with the <tt>scripted</tt> action </li>
+ </ol>
+ <p>The directory structure for a test that verifies correctness in the case mentioned in the previous section might look like: </p>
+ <pre class="prettyprint"> src/sbt-test/change-detection/remove-test/
+ project/
+ build.properties
+ src/main/scala/
+ A.scala
+ B.scala
+ test</pre>
+ <p>The <tt>scripted</tt> action runs the test by copying the directory to the temporary directory for your system, loads the project, and runs the <tt>test</tt> script. For example, on a unix system, the above test might be run from <tt>/tmp/sbt_f723ecf/remove-test/</tt>, where the <tt>f723ecf</tt> part is randomly generated. </p>
+ <p>The next section describes scripts and provides an example of the <tt>test</tt> script. </p>
+ <h1><a name="Scripts"></a>Scripts<a href="#Scripts" class="section_anchor"></a></h1>
+ <h2><a name="Syntax"></a>Syntax<a href="#Syntax" class="section_anchor"></a></h2>
+ <pre class="prettyprint">script ::= (comment | statement)+
+comment ::= '#' comment-text EOL
+statement ::= expected-result (action | command)
+
+action ::= '&gt;' name
+command ::= '$' name argument*
+
+expected-result ::= '' | '-'</pre>
+ <h2><a name="Example"></a>Example<a href="#Example" class="section_anchor"></a></h2>
+ <pre class="prettyprint">&gt; compile
+
+$ delete src/main/scala/B.scala
+
+-&gt; compile</pre>
+ <h2><a name="Commands"></a>Commands<a href="#Commands" class="section_anchor"></a></h2>
+ <p>All paths are relative to the project directory. </p>
+ <p><tt>copy-file fromPath toPath</tt> </p>
+ <blockquote>
+ Copies the file given by
+ <tt>fromPath</tt> to
+ <tt>toPath</tt>.
+ </blockquote>
+ <tt>copy fromPath+ toDirectoryPath</tt>
+ <blockquote>
+ Copies the files given by
+ <tt>fromPaths</tt> to the
+ <tt>toDirectoryPath</tt> directory. The directory structure relative to the project directory is preserved.
+ </blockquote>
+ <tt>sync fromDirectory toDirectory</tt>
+ <blockquote>
+ Synchronizes
+ <tt>fromDirectory</tt> and
+ <tt>toDirectory</tt> so that the contents of
+ <tt>toDirectory</tt> are identical to that of
+ <tt>fromDirectory</tt>.
+ </blockquote>
+ <tt>delete path+</tt>
+ <blockquote>
+ Deletes the files given by
+ <tt>path</tt>s.
+ </blockquote>
+ <tt>touch path+</tt>
+ <blockquote>
+ Creates or updates the last modified time of the given
+ <tt>path</tt>s.
+ </blockquote>
+ <tt>exists path+</tt>
+ <blockquote>
+ Succeeds if the given
+ <tt>path</tt>s exist, fails otherwise.
+ </blockquote>
+ <tt>absent path+</tt>
+ <blockquote>
+ Succeeds if the given
+ <tt>path</tt>s do not exist, fails otherwise.
+ </blockquote>
+ <tt>exec command args*</tt>
+ <blockquote>
+ Executes the given command in a separate process.
+ </blockquote>
+ <tt>pause</tt>
+ <blockquote>
+ Pauses until enter is pressed. It is useful for inspecting the current test state. As noted above, the project directory for tests is copied to the temporary directory and run from there.
+ </blockquote>
+ <tt>sleep time</tt>
+ <blockquote>
+ Calls
+ <tt>Thread.sleep(time)</tt>.
+ </blockquote>
+ <tt>newer source target</tt>
+ <blockquote>
+ Succeeds if the last modification time of
+ <tt>source</tt> is more recent than that of
+ <tt>target</tt> or if
+ <tt>target</tt> does not exist. Fails otherwise.
+ </blockquote>
+ <tt>mkdir path+</tt>
+ <blockquote>
+ Creates directories at the given
+ <tt>path</tt>s.
+ </blockquote>
+ <p></p>
+ <h2><a name="Further_Examples"></a>Further Examples<a href="#Further_Examples" class="section_anchor"></a></h2>
+ <p>See the existing tests for more examples. They are in the <a href="http://github.com/harrah/xsbt/tree/master/sbt/src/sbt-test" rel="nofollow">src/sbt-test/</a> directory. </p>
+ <h1><a name="Running_Tests"></a>Running Tests<a href="#Running_Tests" class="section_anchor"></a></h1>
+ <ol>
+ <li>Run the <tt>scripted</tt> action on the sbt project. You can run selected tasks by using the <tt>scripted-only</tt> task like the <tt>test-only</tt> task. </li>
+ <li><a href="http://groups.google.com/group/simple-build-tool" rel="nofollow">Contribute</a> your tests! </li>
+ </ol>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
71 0.7.7/docs/ChangeSummary0_3_5.html
@@ -0,0 +1,71 @@
+<html>
+ <head>
+ <title>ChangeSummary0_3_5</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">ChangeSummary0_3_5</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <h1><a name="Improvements/Features"></a>Improvements/Features<a href="#Improvements/Features" class="section_anchor"></a></h1>
+ <h3><a name="General"></a>General<a href="#General" class="section_anchor"></a></h3>
+ <ul>
+ <li>Added prompt to retry project loading if compilation of project definition fails. </li>
+ <li><tt>package</tt> action now only executes when inputs have changed. </li>
+ <li>Added <tt>help</tt> command that displays an informative message and describes the commands available at the interactive prompt. </li>
+ <li>Added <tt>reload</tt> command to reread the project definition without having to restart sbt. </li>
+ <li>Added <tt>console-quick</tt> action for when you want fast access to the Scala interpreter but don't need your project compiled. </li>
+ <li>Added <tt>clean-cache</tt> action to delete Ivy's artifact and metadata cache. </li>
+ </ul>
+ <h3><a name="Integration_Testing"></a>Integration Testing<a href="#Integration_Testing" class="section_anchor"></a></h3>
+ <ul>
+ <li>Added integration test support with <tt>integration-test</tt> action. </li>
+ <li>Behaves like <tt>test</tt> but takes its test sources from <tt>src/it</tt> (by default). </li>
+ <li>Use it by mixing in <tt>BasicScalaIntegrationTesting</tt> to your project definition. </li>
+ </ul>
+ <h3><a name="Dependency_Management"></a>Dependency Management<a href="#Dependency_Management" class="section_anchor"></a></h3>
+ <ul>
+ <li>Added ability to specify inline Ivy XML configuration in project definition (see towards the bottom of the <a href="LibraryManagement">Library Management</a> page). </li>
+ <li>Can specify Ivy configurations as fourth piece of inline dependencies <tt>(... % &quot;runtime-&gt;compile&quot;)</tt>. </li>
+ </ul>
+ <h3><a name="Custom_Actions"></a>Custom Actions<a href="#Custom_Actions" class="section_anchor"></a></h3>
+ <ul>
+ <li>Added <tt>fileTask</tt> methods for tasks that execute when the inputs/outputs are out of date (see <a href="CustomActions">Creating/Modifying Actions</a> page). </li>
+ <li><tt>sbt.FileUtilities</tt> is cleaned up and ready for general use: </li>
+ <ul>
+ <li>Provides zip, unzip, temporary directories, copying, ... </li>
+ <li>see the <a href="ActionContent">Implementing actions</a> page for an overview of capabilities or the <a href="http://simple-build-tool.googlecode.com/svn/artifacts/0.3.5/api/sbt/FileUtilities$object.html" rel="nofollow">API Documentation</a> for details. </li>
+ </ul>
+ </ul>
+ <h3><a name="Web_Applications"></a>Web Applications<a href="#Web_Applications" class="section_anchor"></a></h3>
+ <ul>
+ <li><tt>package</tt> action creates war file. </li>
+ <li>Added <tt>jetty-run</tt> and <tt>jetty-stop</tt> actions. </li>
+ <li>See <a href="WebApplications">web applications</a> page for more information. </li>
+ </ul>
+ <p> </p>
+ <h1><a name="Fixes"></a>Fixes<a href="#Fixes" class="section_anchor"></a></h1>
+ <ul>
+ <li>Fixed <a title="build.properties keeps getting modified" class="closed_ref" href="/p/simple-build-tool/issues/detail?id=11">&nbsp;bug #11&nbsp;</a> (project/build.properties unnecessarily updated). </li>
+ <li>Fixed problem with dependencies where source jars would be used instead of binary jars. </li>
+ <li>Fixed scala-tools not being used by default for inline configurations. </li>
+ </ul>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
50 0.7.7/docs/ChangeSummary0_3_7.html
@@ -0,0 +1,50 @@
+<html>
+ <head>
+ <title>ChangeSummary0_3_7</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">ChangeSummary0_3_7</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <h1><a name="Improvements/Features"></a>Improvements/Features<a href="#Improvements/Features" class="section_anchor"></a></h1>
+ <h3><a name="Change_Detection"></a>Change Detection<a href="#Change_Detection" class="section_anchor"></a></h3>
+ <ul>
+ <li>The previous method for detecting changes to sources was to compare last modified times. This method is still available, but is no longer the default. Now, SHA hashes of the sources are compared. This addresses several issues but could be slower for large projects. Please provide feedback if you notice that running <tt>compile</tt> with no modified sources is slower. See <a href="ChangeDetectionAndTesting">Change Detection and Testing</a> for details. </li>
+ </ul>
+ <h3><a name="General"></a>General<a href="#General" class="section_anchor"></a></h3>
+ <ul>
+ <li><tt>sbt</tt> now exits with a nonzero exit code if an action fails in batch mode. </li>
+ <li><tt>trace</tt> is no longer a logging level but is instead a flag to determine whether stack traces are printed. </li>
+ <li>Hidden files and files that start with '.' are excluded by default (previously, <tt>.svn</tt> and <tt>.cvs</tt> directories were excluded by default). <tt>'.*'</tt> is necessary in addition to the hidden file requirement because subversion does not mark <tt>.svn</tt> directories hidden on Windows. </li>
+ <li>Added continuous compilation command <tt>cc</tt> that polls for changes to your source files and runs <tt>test-compile</tt> when they change. </li>
+ </ul>
+ <p> </p>
+ <h3><a name="Testing_sbt"></a>Testing sbt<a href="#Testing_sbt" class="section_anchor"></a></h3>
+ <ul>
+ <li>There is now a scripted test framework for functional testing of <tt>sbt</tt>. Writing tests for <tt>sbt</tt> is as straightforward as creating a project, determining changes to make to the project (e.g. add/remove/modify a file), and a simple script to run the project and make the changes. Please see <a href="ChangeDetectionAndTesting">Change Detection and Testing</a> for details. </li>
+ </ul>
+ <h1><a name="Fixes"></a>Fixes<a href="#Fixes" class="section_anchor"></a></h1>
+ <ul>
+ <li>Fixed <a title="path parsing broken" class="closed_ref" href="/p/simple-build-tool/issues/detail?id=12">&nbsp;bug #12&nbsp;</a> (manifests for jars not generated). </li>
+ <li>Fixed scala-tools releases not being used by default. </li>
+ </ul>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
70 0.7.7/docs/ChangeSummary_0_4.html
@@ -0,0 +1,70 @@
+<html>
+ <head>
+ <title>ChangeSummary_0_4</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">ChangeSummary_0_4</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <h1><a name="Changes_from_0.3.7_to_0.4"></a>Changes from 0.3.7 to 0.4<a href="#Changes_from_0.3.7_to_0.4" class="section_anchor"></a></h1>
+ <p>This release includes a number of new features and improvements. They are summarized below. Comments, questions, and suggestions are welcome! </p>
+ <h2><a name="Major_Features"></a>Major Features<a href="#Major_Features" class="section_anchor"></a></h2>
+ <ul>
+ <li>New loader architecture that enables Scala and <tt>sbt</tt> versions to be specified per project. See <a href="Loader">Sbt Loader</a> for details. </li>
+ <li>Webstart project support. See <a href="Webstart">Webstart</a> for details. </li>
+ <li>Automatic reloading of web application run with <tt>jetty-run</tt>. See <a href="WebApplications">WebApplications</a>. </li>
+ <li>Triggered execution of any action by prefixing the line with <tt>~</tt>. The action will run when any Scala source files are modified. Thanks to Mikko for the work on continuous compilation that made this feature possible! See <a href="TriggeredExecution">Triggered Execution</a>. </li>
+ <li>Method tasks, which take arguments and produce the task to run. See <a href="MethodTasks">Method Tasks</a>. </li>
+ <li>Added <tt>test-quick</tt>, <tt>test-failed</tt>, and <tt>test-only</tt> methods. See <a href="TriggeredExecution">Triggered Execution</a> for details. </li>
+ <li>Reworked task execution model across multiple projects. See the Multi-Project Tasks Details section below. </li>
+ </ul>
+ <h2><a name="Improvements"></a>Improvements<a href="#Improvements" class="section_anchor"></a></h2>
+ <ul>
+ <li>Added <tt>jetty-restart</tt> action, which first executes <tt>jetty-stop</tt> and then executes <tt>jetty-run</tt> </li>
+ <li>Added project organization as a property that defaults to inheriting from the parent project. Project creation organization now prompts for organization, which can be left blank </li>
+ <li><tt>help</tt>, <tt>actions</tt>, and <tt>methods</tt> commands are now available when executing <tt>sbt</tt> batch style </li>
+ <li>Modified logging subsystem for improved labeling of logging by action and project and for better support for buffered logging from actors. </li>
+ <li><tt>run</tt> now accepts arguments to pass to the <tt>main</tt> method of the class being run. </li>
+ <li>Added <tt>publish-local</tt> action for publishing to the local Ivy repository. </li>
+ </ul>
+ <h2><a name="Fixes"></a>Fixes<a href="#Fixes" class="section_anchor"></a></h2>
+ <ul>
+ <li>Fixed <a title="Resources not added to classpath" class="closed_ref" href="/p/simple-build-tool/issues/detail?id=17">&nbsp;bug #17&nbsp;</a> - resources not added to classpath. </li>
+ <li>Fixed issue with <tt>build.properties</tt> being unnecessarily updated in sub-projects during startup. </li>
+ <li>Fixed problem with nested modules being detected as tests (as occurred when testing specs itself). </li>
+ </ul>
+ <h2><a name="Multi-Project_Task_Execution_Details"></a>Multi-Project Task Execution Details<a href="#Multi-Project_Task_Execution_Details" class="section_anchor"></a></h2>
+ <p>There have been some changes in how tasks are executed, mainly with respect to multiple projects. </p>
+ <ul>
+ <li>Tasks can now explicitly depend on tasks in other projects. </li>
+ <li>A task (call it T) implicitly depends on tasks in projects that T's project depends on that have the same name as T. </li>
+ <li>Methods and interactive tasks (such as <tt>run</tt> and <tt>console</tt>) must be executed directly on the desired project. </li>
+ </ul>
+ <p></p>
+ <p>Some consequences of these changes are: </p>
+ <ul>
+ <li>Tasks will run in parallel within a given project if <tt>parallelExecution</tt> is set to <tt>true</tt>. Previously, only one task per project could run at a time. </li>
+ <li>Tasks are run breadth-first. For example, the default project type defines a <tt>package</tt> task that depends on a <tt>compile</tt> task. If you execute <tt>package</tt> on multiple projects, <tt>compile</tt> will be run across all projects first and then <tt>package</tt> will be run across all projects. Previously, the specified action (<tt>package</tt> in this case) would be executed on each project in the order required by project-level dependencies. This resulted in depth-first execution. </li>
+ <li>Tasks no longer have to be explicitly called to have implicit dependencies across multiple projects. For example, the web application project type defines the <tt>jetty-run</tt> action. One of its dependencies is <tt>compile</tt>. Previously, <tt>compile</tt> would not be invoked in other projects that did not have a <tt>jetty-run</tt> task. This would be the case if you had one web application subproject that depended on another subproject that was not a web application. </li>
+ </ul>
+ <p></p>
+ </div>
+ </div> </td>
+ </tr>
+ <tr>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <script type="text/javascript" src="http://www.gstatic.com/codesite/ph/5509366563142316864/js/dit_scripts.js"></script>
+ </body>
+</html>
View
88 0.7.7/docs/ChangeSummary_0_4_3.html
@@ -0,0 +1,88 @@
+<html>
+ <head>
+ <title>ChangeSummary_0_4_3</title>
+ </head>
+ <body>
+ <div id="wikipage">
+ <table>
+ <tbody>
+ <tr>
+ <td style="vertical-align:top; padding-left:5px">
+ <div id="wikiheader">
+ <span style="font-size:120%;font-weight:bold">ChangeSummary_0_4_3</span> &nbsp;
+ <div>
+ </div>
+ </div>
+ <div id="wikicontent">
+ <div class="vt" id="wikimaincol">
+ <h1><a name="Changes_from_0.4_to_0.4.3"></a>Changes from 0.4 to 0.4.3<a href="#Changes_from_0.4_to_0.4.3" class="section_anchor"></a></h1>
+ <p>The changes in this release are mainly minor improvements and fixes in support of the new launcher. There is one important change to managing Scala jars that should be noted before updating. See the Scala Jars and Dependency Management section below and please ask if you have any questions about it. </p>
+ <h2><a name="New_Features"></a>New Features<a href="#New_Features"