Skip to content

Commit

Permalink
updated site
Browse files Browse the repository at this point in the history
  • Loading branch information
@jberkel
jberkel committed Apr 5, 2012
1 parent 6cad087 commit 6fffa9c
Show file tree
Hide file tree
Showing 8 changed files with 858 additions and 53 deletions.
624 changes: 571 additions & 53 deletions howto.html
View file

Large diffs are not rendered by default.

45 changes: 45 additions & 0 deletions howto/generatefiles.html
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -56,10 +56,31 @@ <h4 id="sources">Generate sources</h4>


<p>A source generation task should generate sources in a subdirectory of <code>sourceManaged</code> and return a sequence of files generated. The key to add the task to is called <code>sourceGenerators</code>. It should be scoped according to whether the generated files are main (<code>Compile</code>) or test (<code>Test</code>) sources. This basic structure looks like:</p> <p>A source generation task should generate sources in a subdirectory of <code>sourceManaged</code> and return a sequence of files generated. The key to add the task to is called <code>sourceGenerators</code>. It should be scoped according to whether the generated files are main (<code>Compile</code>) or test (<code>Test</code>) sources. This basic structure looks like:</p>


<div class="highlight"><pre><code class="scala"><span class="n">sourceGenerators</span> <span class="n">in</span> <span class="nc">Compile</span> <span class="o">&lt;+=</span> <span class="o">&lt;</span><span class="n">your</span> <span class="nc">Task</span><span class="o">[</span><span class="kt">Seq</span><span class="o">[</span><span class="kt">File</span><span class="o">]]</span> <span class="n">here</span><span class="o">&gt;</span>
</code></pre>
</div>


<p>For example, assuming a method <code>def makeSomeSources(base: File): Seq[File]</code>,</p> <p>For example, assuming a method <code>def makeSomeSources(base: File): Seq[File]</code>,</p>


<div class="highlight"><pre><code class="scala"><span class="n">sourceGenerators</span> <span class="n">in</span> <span class="nc">Compile</span> <span class="o">&lt;+=</span> <span class="n">sourceManaged</span> <span class="n">in</span> <span class="nc">Compile</span> <span class="n">map</span> <span class="o">{</span> <span class="n">outDir</span><span class="k">:</span> <span class="kt">File</span> <span class="o">=&gt;</span>
<span class="n">makeSomeSources</span><span class="o">(</span><span class="n">outDir</span> <span class="o">/</span> <span class="s">&quot;demo&quot;</span><span class="o">)</span>
<span class="o">}</span>
</code></pre>
</div>


<p>As a specific example, the following generates a hello world source file:</p> <p>As a specific example, the following generates a hello world source file:</p>


<div class="highlight"><pre><code class="scala"><span class="n">sourceGenerators</span> <span class="n">in</span> <span class="nc">Compile</span> <span class="o">&lt;+=</span> <span class="n">sourceManaged</span> <span class="n">in</span> <span class="nc">Compile</span> <span class="n">map</span> <span class="o">{</span> <span class="n">dir</span> <span class="k">=&gt;</span>
<span class="k">val</span> <span class="n">file</span> <span class="k">=</span> <span class="n">dir</span> <span class="o">/</span> <span class="s">&quot;demo&quot;</span> <span class="o">/</span> <span class="s">&quot;Test.scala&quot;</span>
<span class="nc">IO</span><span class="o">.</span><span class="n">write</span><span class="o">(</span><span class="n">file</span><span class="o">,</span> <span class="s">&quot;&quot;&quot;object Test extends App { println(&quot;Hi&quot;) }&quot;&quot;&quot;</span><span class="o">)</span>
<span class="nc">Seq</span><span class="o">(</span><span class="n">file</span><span class="o">)</span>
<span class="o">}</span>
</code></pre>
</div>


<p>Executing 'run' will print "Hi". Change <code>Compile</code> to <code>Test</code> to make it a test source. For efficiency, you would only want to generate sources when necessary and not every run.</p> <p>Executing 'run' will print "Hi". Change <code>Compile</code> to <code>Test</code> to make it a test source. For efficiency, you would only want to generate sources when necessary and not every run.</p>


<p>By default, generated sources are not included in the packaged source artifact. To do so, add them as you would other mappings. See <code>Adding files to a package</code>.</p> <p>By default, generated sources are not included in the packaged source artifact. To do so, add them as you would other mappings. See <code>Adding files to a package</code>.</p>
Expand All @@ -69,10 +90,34 @@ <h4 id="resources">Generate resources</h4>


<p>A resource generation task should generate resources in a subdirectory of <code>resourceManaged</code> and return a sequence of files generated. The key to add the task to is called <code>resourceGenerators</code>. It should be scoped according to whether the generated files are main (<code>Compile</code>) or test (<code>Test</code>) resources. This basic structure looks like:</p> <p>A resource generation task should generate resources in a subdirectory of <code>resourceManaged</code> and return a sequence of files generated. The key to add the task to is called <code>resourceGenerators</code>. It should be scoped according to whether the generated files are main (<code>Compile</code>) or test (<code>Test</code>) resources. This basic structure looks like:</p>


<div class="highlight"><pre><code class="scala"><span class="n">resourceGenerators</span> <span class="n">in</span> <span class="nc">Compile</span> <span class="o">&lt;+=</span> <span class="o">&lt;</span><span class="n">your</span> <span class="nc">Task</span><span class="o">[</span><span class="kt">Seq</span><span class="o">[</span><span class="kt">File</span><span class="o">]]</span> <span class="n">here</span><span class="o">&gt;</span>
</code></pre>
</div>


<p>For example, assuming a method <code>def makeSomeResources(base: File): Seq[File]</code>,</p> <p>For example, assuming a method <code>def makeSomeResources(base: File): Seq[File]</code>,</p>


<div class="highlight"><pre><code class="scala"><span class="n">resourceGenerators</span> <span class="n">in</span> <span class="nc">Compile</span> <span class="o">&lt;+=</span> <span class="n">resourceManaged</span> <span class="n">in</span> <span class="nc">Compile</span> <span class="n">map</span> <span class="o">{</span> <span class="n">outDir</span><span class="k">:</span> <span class="kt">File</span> <span class="o">=&gt;</span>
<span class="n">makeSomeResources</span><span class="o">(</span><span class="n">outDir</span> <span class="o">/</span> <span class="s">&quot;demo&quot;</span><span class="o">)</span>
<span class="o">}</span>
</code></pre>
</div>


<p>As a specific example, the following generates a properties file containing the application name and version:</p> <p>As a specific example, the following generates a properties file containing the application name and version:</p>


<div class="highlight"><pre><code class="scala"><span class="n">resourceGenerators</span> <span class="n">in</span> <span class="nc">Compile</span> <span class="o">&lt;+=</span>
<span class="o">(</span><span class="n">resourceManaged</span> <span class="n">in</span> <span class="nc">Compile</span><span class="o">,</span> <span class="n">name</span><span class="o">,</span> <span class="n">version</span><span class="o">)</span> <span class="n">map</span> <span class="o">{</span> <span class="o">(</span><span class="n">dir</span><span class="o">,</span> <span class="n">n</span><span class="o">,</span> <span class="n">v</span><span class="o">)</span> <span class="k">=&gt;</span>
<span class="k">val</span> <span class="n">file</span> <span class="k">=</span> <span class="n">dir</span> <span class="o">/</span> <span class="s">&quot;demo&quot;</span> <span class="o">/</span> <span class="s">&quot;myapp.properties&quot;</span>
<span class="k">val</span> <span class="n">contents</span> <span class="k">=</span> <span class="s">&quot;name=%s\nversion=%s&quot;</span><span class="o">.</span><span class="n">format</span><span class="o">(</span><span class="n">n</span><span class="o">,</span><span class="n">v</span><span class="o">)</span>
<span class="nc">IO</span><span class="o">.</span><span class="n">write</span><span class="o">(</span><span class="n">file</span><span class="o">,</span> <span class="n">contents</span><span class="o">)</span>
<span class="nc">Seq</span><span class="o">(</span><span class="n">file</span><span class="o">)</span>
<span class="o">}</span>
<span class="o">}</span>
</code></pre>
</div>


<p>Change <code>Compile</code> to <code>Test</code> to make it a test resource. Normally, you would only want to generate resources when necessary and not every run.</p> <p>Change <code>Compile</code> to <code>Test</code> to make it a test resource. Normally, you would only want to generate resources when necessary and not every run.</p>


<p>By default, generated resources are not included in the packaged source artifact. To do so, add them as you would other mappings. See the <code>Adding files to a package</code> section.</p> <p>By default, generated resources are not included in the packaged source artifact. To do so, add them as you would other mappings. See the <code>Adding files to a package</code> section.</p>
Expand Down
31 changes: 31 additions & 0 deletions howto/interactive.html
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -142,6 +142,17 @@ <h4 id="prompt">Configure the prompt string</h4>


<p>Examples:</p> <p>Examples:</p>


<div class="highlight"><pre><code class="scala"><span class="c1">// set the prompt (for this build) to include the project id.</span>
<span class="n">shellPrompt</span> <span class="n">in</span> <span class="nc">ThisBuild</span> <span class="o">:=</span> <span class="o">{</span> <span class="n">state</span> <span class="k">=&gt;</span> <span class="nc">Project</span><span class="o">.</span><span class="n">extract</span><span class="o">(</span><span class="n">state</span><span class="o">).</span><span class="n">currentRef</span><span class="o">.</span><span class="n">project</span> <span class="o">+</span> <span class="s">&quot;&gt; &quot;</span> <span class="o">}</span>

<span class="c1">// set the prompt (for the current project) to include the username</span>
<span class="n">shellPrompt</span> <span class="o">:=</span> <span class="o">{</span> <span class="n">state</span> <span class="k">=&gt;</span> <span class="nc">System</span><span class="o">.</span><span class="n">getProperty</span><span class="o">(</span><span class="s">&quot;user.name&quot;</span><span class="o">)</span> <span class="o">+</span> <span class="s">&quot;&gt; &quot;</span> <span class="o">}</span>
</code></pre>
</div>




<h4 id="history">Using history</h4> <h4 id="history">Using history</h4>




Expand Down Expand Up @@ -169,6 +180,11 @@ <h4 id="history_file">Changing the history file location</h4>
The location can be changed with the <code>historyPath</code> setting, which has type <code>Option[File]</code>. The location can be changed with the <code>historyPath</code> setting, which has type <code>Option[File]</code>.
For example, history can be stored in the root directory for the project instead of the output directory:</p> For example, history can be stored in the root directory for the project instead of the output directory:</p>


<div class="highlight"><pre><code class="scala"><span class="n">historyPath</span> <span class="o">&lt;&lt;=</span> <span class="n">baseDirectory</span><span class="o">(</span><span class="n">t</span> <span class="k">=&gt;</span> <span class="nc">Some</span><span class="o">(</span><span class="n">t</span> <span class="o">/</span> <span class="s">&quot;.history&quot;</span><span class="o">))</span>
</code></pre>
</div>


<p>The history path needs to be set for each project, since sbt will use the value of <code>historyPath</code> for the current project (as selected by the <code>project</code> command).</p> <p>The history path needs to be set for each project, since sbt will use the value of <code>historyPath</code> for the current project (as selected by the <code>project</code> command).</p>


<h4 id="share_history">Use the same history for all projects</h4> <h4 id="share_history">Use the same history for all projects</h4>
Expand All @@ -178,13 +194,28 @@ <h4 id="share_history">Use the same history for all projects</h4>
This setting can be used to share the interactive history among all projects in a build instead of using a different history for each project. This setting can be used to share the interactive history among all projects in a build instead of using a different history for each project.
The way this is done is to set <code>historyPath</code> to be the same file, such as a file in the root project's <code>target/</code> directory:</p> The way this is done is to set <code>historyPath</code> to be the same file, such as a file in the root project's <code>target/</code> directory:</p>


<div class="highlight"><pre><code class="scala"><span class="n">historyPath</span> <span class="o">&lt;&lt;=</span>
<span class="o">(</span><span class="n">target</span> <span class="n">in</span> <span class="nc">LocalRootProject</span><span class="o">)</span> <span class="o">{</span> <span class="n">t</span> <span class="k">=&gt;</span>
<span class="nc">Some</span><span class="o">(</span><span class="n">t</span> <span class="o">/</span> <span class="s">&quot;.history&quot;</span><span class="o">)</span>
<span class="o">}</span>
</code></pre>
</div>


<p>The <code>in LocalRootProject</code> part means to get the output directory for the root project for the build.</p> <p>The <code>in LocalRootProject</code> part means to get the output directory for the root project for the build.</p>


<h4 id="disable_history">Disable interactive history</h4> <h4 id="disable_history">Disable interactive history</h4>




<p>If, for whatever reason, you want to disable history, set <code>historyPath</code> to <code>None</code> in each project it should be disabled in:</p> <p>If, for whatever reason, you want to disable history, set <code>historyPath</code> to <code>None</code> in each project it should be disabled in:</p>


<div class="highlight"><pre><code class="scala"><span class="n">historyPath</span> <span class="o">:=</span> <span class="nc">None</span>
</code></pre>
</div>




<h4 id="pre_commands">Run commands before entering interactive mode</h4> <h4 id="pre_commands">Run commands before entering interactive mode</h4>




Expand Down
43 changes: 43 additions & 0 deletions howto/logging.html
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -75,8 +75,51 @@ <h4 id="last">View logging output of the previously executed command</h4>


<p>For example, the output of <code>run</code> when the sources are uptodate is:</p> <p>For example, the output of <code>run</code> when the sources are uptodate is:</p>


<div class="highlight"><pre><code class="console"><span class="gp">&gt;</span> run
<span class="go">[info] Running A </span>
<span class="go">Hi!</span>
<span class="go">[success] Total time: 0 s, completed Feb 25, 2012 1:00:00 PM</span>
</code></pre>
</div>


<p>The details of this execution can be recalled by running <code>last</code>:</p> <p>The details of this execution can be recalled by running <code>last</code>:</p>


<div class="highlight"><pre><code class="console"><span class="gp">&gt;</span> last
<span class="go">[debug] Running task... Cancelable: false, max worker threads: 4, check cycles: false</span>
<span class="go">[debug] </span>
<span class="go">[debug] Initial source changes: </span>
<span class="go">[debug] removed:Set()</span>
<span class="go">[debug] added: Set()</span>
<span class="go">[debug] modified: Set()</span>
<span class="go">[debug] Removed products: Set()</span>
<span class="go">[debug] Modified external sources: Set()</span>
<span class="go">[debug] Modified binary dependencies: Set()</span>
<span class="go">[debug] Initial directly invalidated sources: Set()</span>
<span class="go">[debug] </span>
<span class="go">[debug] Sources indirectly invalidated by:</span>
<span class="go">[debug] product: Set()</span>
<span class="go">[debug] binary dep: Set()</span>
<span class="go">[debug] external source: Set()</span>
<span class="go">[debug] Initially invalidated: Set()</span>
<span class="go">[debug] Copy resource mappings: </span>
<span class="go">[debug] </span>
<span class="go">[info] Running A </span>
<span class="go">[debug] Starting sandboxed run...</span>
<span class="go">[debug] Waiting for threads to exit or System.exit to be called.</span>
<span class="go">[debug] Classpath:</span>
<span class="go">[debug] /tmp/e/target/scala-2.9.1/classes</span>
<span class="go">[debug] /tmp/e/.sbt/0.12.0/boot/scala-2.9.1/lib/scala-library.jar</span>
<span class="go">[debug] Waiting for thread run-main to exit</span>
<span class="go">[debug] Thread run-main exited.</span>
<span class="go">[debug] Interrupting remaining threads (should be all daemons).</span>
<span class="go">[debug] Sandboxed run complete..</span>
<span class="go">[debug] Exited with code 0</span>
<span class="go">[success] Total time: 0 s, completed Jan 1, 2012 1:00:00 PM</span>
</code></pre>
</div>


<p>Configuration of the logging level for the console and for the backing file are described in following sections.</p> <p>Configuration of the logging level for the console and for the backing file are described in following sections.</p>


<h4 id="tasklast">View the logging output of a specific task</h4> <h4 id="tasklast">View the logging output of a specific task</h4>
Expand Down
43 changes: 43 additions & 0 deletions howto/metadata.html
View file
Original file line number Original file line Diff line number Diff line change
Expand Up @@ -58,24 +58,67 @@ <h2>Project metadata</h2>
<h4 id="name">Set the project name</h4> <h4 id="name">Set the project name</h4>






<div class="highlight"><pre><code class="scala"><span class="n">name</span> <span class="o">:=</span> <span class="s">&quot;Your project name&quot;</span>
</code></pre>
</div>


<p>For published projects, this name is normalized to be suitable for use as an artifact name and dependency ID. This normalized name is stored in <code>normalizedName</code>.</p> <p>For published projects, this name is normalized to be suitable for use as an artifact name and dependency ID. This normalized name is stored in <code>normalizedName</code>.</p>


<h4 id="version">Set the project version</h4> <h4 id="version">Set the project version</h4>








<div class="highlight"><pre><code class="scala"><span class="n">version</span> <span class="o">:=</span> <span class="s">&quot;1.0&quot;</span>
</code></pre>
</div>




<h4 id="organization">Set the project organization</h4> <h4 id="organization">Set the project organization</h4>






<div class="highlight"><pre><code class="scala"><span class="n">organization</span> <span class="o">:=</span> <span class="s">&quot;org.example&quot;</span>
</code></pre>
</div>


<p>By convention, this is a reverse domain name that you own, typically one specific to your project. It is used as a namespace for projects.</p> <p>By convention, this is a reverse domain name that you own, typically one specific to your project. It is used as a namespace for projects.</p>


<p>A full/formal name can be defined in the <code>organizationName</code> setting. This is used in the generated pom.xml. If the organization has a web site, it may be set in the <code>organizationHomepage</code> setting. For example:</p> <p>A full/formal name can be defined in the <code>organizationName</code> setting. This is used in the generated pom.xml. If the organization has a web site, it may be set in the <code>organizationHomepage</code> setting. For example:</p>


<div class="highlight"><pre><code class="scala"><span class="n">organization</span> <span class="o">:=</span> <span class="s">&quot;Example, Inc.&quot;</span>

<span class="n">organizationHomepage</span> <span class="o">:=</span> <span class="s">&quot;org.example&quot;</span>
</code></pre>
</div>




<h4 id="other">Set the project's homepage and other metadata</h4> <h4 id="other">Set the project's homepage and other metadata</h4>







<div class="highlight"><pre><code class="scala"><span class="n">homepage</span> <span class="o">:=</span> <span class="nc">Some</span><span class="o">(</span><span class="n">url</span><span class="o">(</span><span class="s">&quot;http://scala-sbt.org&quot;</span><span class="o">))</span>

<span class="n">startYear</span> <span class="o">:=</span> <span class="nc">Some</span><span class="o">(</span><span class="mi">2008</span><span class="o">)</span>

<span class="n">description</span> <span class="o">:=</span> <span class="s">&quot;A build tool for Scala.&quot;</span>

<span class="n">licenses</span> <span class="o">+=</span> <span class="s">&quot;GPLv2&quot;</span> <span class="o">-&gt;</span> <span class="s">&quot;http://www.gnu.org/licenses/gpl-2.0.html&quot;</span>
</code></pre>
</div>





</div> </div>
</div> </div>
Expand Down
Loading

0 comments on commit 6fffa9c

Please sign in to comment.