Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge branch 'gen-master' of github.com:sbt/sbt.github.com into gen-m…

…aster
  • Loading branch information...
commit 11ff5e6616419481dbb656bb42a23b09efbe4935 2 parents b46a518 + 03f908e
@jsuereth jsuereth authored
View
1  .gitignore
@@ -2,3 +2,4 @@ target
project/boot
project/build/target
project/plugins/target
+.history
View
18 README.md
@@ -8,13 +8,27 @@ The project contains the sources used to generate [http://www.scala-sbt.org/](h
## Requirements
-You need to have `jekyll` installed. Luckily that's quite easy: `gem install jekyll`. If that doesn't work check out the [installation instructions](https://github.com/mojombo/jekyll/wiki/Install "installation instructions").
+You need to have `jekyll` installed. Luckily, that's quite easy: `gem install jekyll rdiscount --no-ri --no-rdoc`. If that doesn't work, check out the [installation instructions](https://github.com/mojombo/jekyll/wiki/Install "installation instructions").
## Usage
You can find the sources in the src/jekyll folder.
-To generate the site simple start an SBT shell and type:
+To generate the site, simply start an SBT shell and type:
> make-site
> ghpages-push-site
+
+When you fire up `sbt`, you _may_ see an error like this:
+
+ [error] AttributeKey ID collisions detected for: 'pgp-signer' (sbt.Task[com.jsuereth.pgp.sbtplugin.PgpSigner], sbt.Task[com.jsuereth.pgp.sbtplugin.PgpSigner]), 'pgp-verifier' (sbt.Task[com.jsuereth.pgp.sbtplugin.PgpVerifier], sbt.Task[com.jsuereth.pgp.sbtplugin.PgpVerifier]), 'pgp-context' (sbt.Task[com.jsuereth.pgp.cli.PgpCommandContext], sbt.Task[com.jsuereth.pgp.cli.PgpCommandContext]), 'check-pgp-signatures' (sbt.Task[com.jsuereth.pgp.sbtplugin.SignatureCheckReport], sbt.Task[com.jsuereth.pgp.sbtplugin.SignatureCheckReport]), 'pgp-static-context' (com.jsuereth.pgp.cli.PgpStaticContext, com.jsuereth.pgp.cli.PgpStaticContext), 'signatures-module' (sbt.Task[com.jsuereth.pgp.sbtplugin.GetSignaturesModule], sbt.Task[com.jsuereth.pgp.sbtplugin.GetSignaturesModule])
+
+If that happens, you probably have a global SBT setting or plugin that
+conflicts with the expectations of this repo's `build.sbt`. In that case, just
+fire up SBT so that it skips your `~/.sbt` directory. e.g.:
+
+ $ sbt -Dsbt.global.base=/tmp
+
+To preview the site, start jekyll and browse to [localhost:4000](http://localhost:4000):
+
+ $ jekyll src/jekyll/ target/jekyll/ --server
View
4 project/project/build.scala
@@ -2,7 +2,5 @@ import sbt._
object PluginDef extends Build {
override def projects = Seq(root)
lazy val root = Project("plugins", file(".")) dependsOn(ghpages)
- // move back to josh's repo after pull requests for git branch key
- // support goes through
- lazy val ghpages = uri("git://github.com/jsuereth/xsbt-ghpages-plugin.git")
+ lazy val ghpages = uri("git://github.com/jsuereth/xsbt-ghpages-plugin.git#e326b5358347a8ab258171e3ed2ac10b9e4914cf")
}
View
1  src/jekyll/_config.yml
@@ -2,3 +2,4 @@ pygments: true
name: Simple Build Tool
description: Homepage for the Simple Build Tool
url: http://scala-sbt.org
+markdown: rdiscount
View
8 src/jekyll/_includes/footer.txt
@@ -1,11 +1,15 @@
-<script type="text/javascript" src="jquery.scrollto.min.js"></script>
+<script type="text/javascript" src="/jquery.scrollto.min.js"></script>
<script type="text/javascript">
(function($){ $(function(){
$("#top").click(function(){ $("#intro").ScrollTo(); })
var applyH = function() {
- $("#intro, .feature").height($(window).height());
+ $("#intro, .feature").each(function (i, elt) {
+ if ($(elt).height() < $(window).height()) {
+ $(elt).height($(window).height());
+ }
+ });
};
$(window).bind('resize', function() { applyH(); });
applyH();
View
4 src/jekyll/_includes/header.txt
@@ -5,8 +5,8 @@
<head>
<title>{% if page.title %}{{ page.title }} - {% endif %}{{ site.title }}</title>
<link href='http://fonts.googleapis.com/css?family=Copse' rel='stylesheet' type='text/css'>
- <link href='resources/site.css' rel='stylesheet' type='text/css'>
- <link href='resources/syntax.css' rel='stylesheet' type='text/css'>
+ <link href='/resources/site.css' rel='stylesheet' type='text/css'>
+ <link href='/resources/syntax.css' rel='stylesheet' type='text/css'>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js">
</script>
</head>
View
6 src/jekyll/_includes/topbar.txt
@@ -5,9 +5,9 @@
<div class="container">
<a class="brand" href="/">SBT</a>
<ul class="nav">
- <li><a href="learn.html">Learn</a>
- <li><a href="download.html">Download</a>
- <li><a href="community.html">Community</a></li>
+ <li><a href="/learn.html">Learn</a>
+ <li><a href="/download.html">Download</a>
+ <li><a href="/community.html">Community</a></li>
<li><a href="#top">Top</a></li>
</ul>
</div>
View
5 src/jekyll/_layouts/content.html
@@ -17,4 +17,7 @@
</div>
-{% include footer.txt %}
+</body>
+</html>
+
+
View
29 src/jekyll/_layouts/howto.html
@@ -0,0 +1,29 @@
+{% include header.txt %}
+
+{% include topbar.txt %}
+
+<div class="cf" id="container">
+ <div class="span2 columns container-spacer"><p>&nbsp;</p></div>
+ <div id="intro" class="span10 columns content">
+ <div id="head" class="cf">
+ <div id="name" class="left">
+ <h1>sbt</h1>
+ <h2>{{page.title}}</h2>
+ </div>
+ </div>
+ <div id="features" class="cf"><div id="feature-list">
+ <ul class="left">
+ {% for section in page.sections %}
+ <li id="feature"><h4><a href="#{{section.id}}">How to {{section.name}}</a></h4></li>
+ {% endfor %}
+ </ul>
+ </div></div>
+ <div id="pagecontent" class="cf">
+ {{ content }}
+ </div>
+ </div>
+ </div>
+</div>
+
+
+{% include footer.txt %}
View
16 src/jekyll/community-plugins.md
@@ -28,6 +28,20 @@ toplinks:
*Note: Your code must abide by the [repository polices](repository-rules.html).*
+ To automatically deploy snapshot/release versions of your plugin use
+ the following configuration:
+
+ publishTo <<= (version) { version: String =>
+ val scalasbt = "http://scalasbt.artifactoryonline.com/scalasbt/"
+ val (name, url) = if (version.contains("-SNAPSHOT"))
+ ("sbt-plugin-snapshots", scalasbt+"sbt-plugin-snapshots")
+ else
+ ("sbt-plugin-releases", scalasbt+"sbt-plugin-releases")
+ Some(Resolver.url(name, new URL(url))(Resolver.ivyStylePatterns))
+ }
+
+ *Note: ivy repositories currently don't support Maven-style snapshots.*
+
- name: 'SBT Organization'
id: 'sbtorg'
content: |
@@ -38,7 +52,7 @@ toplinks:
control over their repository and its access. The Goal of the SBT organization is to
organize SBT software into one central location.
- A side benefit to using the SBT organization for projects is that you can us gh-pages to host websites in the http://scala-sbt.org domain.
+ A side benefit to using the SBT organization for projects is that you can use gh-pages to host websites in the http://scala-sbt.org domain.
- name: 'Community Plugin Build'
id: 'pluginbuild'
View
23 src/jekyll/howto.md
@@ -0,0 +1,23 @@
+---
+layout: content
+title: How to...
+description: How to do common tasks.
+---
+
+{% capture table %}
+{% for page in site.pages %}
+ {% if page.sections %}
+## [{{page.title}}]({{page.url}}) ##
+ {% for section in page.sections %}
+* [How to {{section.name}}]({{page.url | append: "#" | append: section.id}})
+ {% if section.short %} {{section.short | strip_newlines | markdownify}} {% endif %}
+ {% if section.batch %} {% highlight console %} $ sbt {{section.batch | strip_newlines}} {% endhighlight %}{% endif %}
+ {% if section.setting %} {% highlight scala %} {{section.setting | strip_newlines}} {% endhighlight %}{% endif %}
+ {% if section.command %} {% highlight console %} > {{section.command | strip_newlines}} {% endhighlight %}{% endif %}
+ {% if section.commands %} {% highlight console %} {{section.commands}} {% endhighlight %}{% endif %}
+ {% endfor %}
+ {% endif %}
+{% endfor %}
+{% endcapture %}
+
+{{ table | unindent | markdownify }}
View
76 src/jekyll/howto/generatefiles.md
@@ -0,0 +1,76 @@
+---
+layout: howto
+title: Generating files
+sections:
+ - id: sources
+ name: generate sources
+ setting: 'sourceGenerators in Compile <+= <your Task[Seq[File]] here>'
+ - id: resources
+ name: generate resources
+ setting: 'resourceGenerators in Compile <+= <your Task[Seq[File]] here>'
+---
+
+sbt provides standard hooks for adding source or resource generation tasks.
+
+<h4 id="sources">Generate sources</h4>
+
+A source generation task should generate sources in a subdirectory of `sourceManaged` and return a sequence of files generated. The key to add the task to is called `sourceGenerators`. It should be scoped according to whether the generated files are main (`Compile`) or test (`Test`) sources. This basic structure looks like:
+
+{% highlight scala %}
+sourceGenerators in Compile <+= <your Task[Seq[File]] here>
+{% endhighlight %}
+
+For example, assuming a method `def makeSomeSources(base: File): Seq[File]`,
+
+{% highlight scala %}
+sourceGenerators in Compile <+= sourceManaged in Compile map { outDir: File =>
+ makeSomeSources(outDir / "demo")
+}
+{% endhighlight %}
+
+As a specific example, the following generates a hello world source file:
+
+{% highlight scala %}
+sourceGenerators in Compile <+= sourceManaged in Compile map { dir =>
+ val file = dir / "demo" / "Test.scala"
+ IO.write(file, """object Test extends App { println("Hi") }""")
+ Seq(file)
+}
+{% endhighlight %}
+
+Executing 'run' will print "Hi". Change `Compile` to `Test` to make it a test source. For efficiency, you would only want to generate sources when necessary and not every run.
+
+By default, generated sources are not included in the packaged source artifact. To do so, add them as you would other mappings. See `Adding files to a package`.
+
+<h4 id="resources">Generate resources</h4>
+
+A resource generation task should generate resources in a subdirectory of `resourceManaged` and return a sequence of files generated. The key to add the task to is called `resourceGenerators`. It should be scoped according to whether the generated files are main (`Compile`) or test (`Test`) resources. This basic structure looks like:
+
+{% highlight scala %}
+resourceGenerators in Compile <+= <your Task[Seq[File]] here>
+{% endhighlight %}
+
+For example, assuming a method `def makeSomeResources(base: File): Seq[File]`,
+
+{% highlight scala %}
+resourceGenerators in Compile <+= resourceManaged in Compile map { outDir: File =>
+ makeSomeResources(outDir / "demo")
+}
+{% endhighlight %}
+
+As a specific example, the following generates a properties file containing the application name and version:
+
+{% highlight scala %}
+resourceGenerators in Compile <+=
+ (resourceManaged in Compile, name, version) map { (dir, n, v) =>
+ val file = dir / "demo" / "myapp.properties"
+ val contents = "name=%s\nversion=%s".format(n,v)
+ IO.write(file, contents)
+ Seq(file)
+ }
+}
+{% endhighlight %}
+
+Change `Compile` to `Test` to make it a test resource. Normally, you would only want to generate resources when necessary and not every run.
+
+By default, generated resources are not included in the packaged source artifact. To do so, add them as you would other mappings. See the `Adding files to a package` section.
View
179 src/jekyll/howto/interactive.md
@@ -0,0 +1,179 @@
+---
+layout: howto
+title: Interactive mode
+sections:
+ - id: basic_completion
+ name: use tab completion
+ command: 'test-only <TAB>'
+ - id: verbose_completion
+ name: show more tab completion suggestions
+ short: Press tab multiple times.
+ - id: show_keybindings
+ name: view basic JLine keybindings
+ commands: |
+ > console-quick
+ scala> :keybindings
+ - id: change_keybindings
+ name: modify the default JLine keybindings
+ - id: prompt
+ name: configure the prompt string
+ setting: 'shellPrompt := { (s: State) => System.getProperty("user.name") + "> " }'
+ - id: history
+ name: use history
+ command: '!'
+ - id: history_file
+ name: change the location of the interactive history file
+ setting: 'historyPath <<= baseDirectory(t => Some(t / ".history"))'
+ - id: share_history
+ name: share interactive history across projects
+ setting: 'historyPath <<= (target in LocalRootProject) { t => Some(t / ".history") }'
+ - id: disable_history
+ name: disable interactive history
+ setting: 'historyPath := None'
+ - id: pre_commands
+ name: start interactive mode after executing some commands first
+ batch: clean compile shell
+---
+
+[State]: https://github.com/harrah/xsbt/wiki/Build-State
+
+By default, sbt's interactive mode is started when no commands are provided on the command line or when the `shell` command is invoked.
+
+<h4 id="basic_completion">Using tab completion</h4>
+
+As the name suggests, tab completion is invoked by hitting the tab key.
+Suggestions are provided that can complete the text entered to the left of the current cursor position.
+Any part of the suggestion that is unambiguous is automatically appended to the current text.
+Commands typically support tab completion for most of their syntax.
+
+As an example, entering `tes` and hitting tab:
+
+ > tes<TAB>
+
+results in sbt appending a `t`:
+
+ > test
+
+To get further completions, hit tab again:
+
+ > test<TAB>
+ test-frameworks test-listeners test-loader test-only test-options test:
+
+Now, there is more than one possibility for the next character, so sbt prints the available options.
+We will select `test-only` and get more suggestions by entering the rest of the command and hitting tab twice:
+
+ > test-only<TAB><TAB>
+ -- sbt.DagSpecification sbt.EmptyRelationTest sbt.KeyTest sbt.RelationTest sbt.SettingsTest
+
+The first tab inserts an unambiguous space and the second suggests names of tests to run.
+The suggestion of `--` is for the separator between test names and options provided to the test framework.
+The other suggestions are names of test classes for one of sbt's modules.
+Test name suggestions require tests to be compiled first.
+If tests have been added, renamed, or removed since the last test compilation, the completions will be out of date until another successful compile.
+
+<h4 id="verbose_completion">Showing more completions</h4>
+
+Some commands have different levels of completion. Hitting tab multiple times increases the verbosity of completions. (Presently, this feature is rarely used.)
+
+<h4 id="show_keybindings">Showing JLine keybindings</h4>
+
+Both the Scala and sbt command prompts use JLine for interaction. The Scala REPL contains a `:keybindings` command to show many of the keybindings used for JLine. For sbt, this can be used by running one of the `console` commands (`console`, `console-quick`, or `console-project`) and then running `:keybindings`. For example:
+
+ > console-project
+ [info] Starting scala interpreter...
+ ...
+ scala> :keybindings
+ Reading jline properties for default key bindings.
+ Accuracy not guaranteed: treat this as a guideline only.
+
+ 1 CTRL-A: move to the beginning of the line
+ 2 CTRL-B: move to the previous character
+ ...
+
+<h4 id="change_keybindings">Changing JLine keybindings</h4>
+
+JLine, used by both Scala and sbt, uses a configuration file for many of its keybindings.
+The location of this file can be changed with the system property `jline.keybindings`.
+The default keybindings file is included in the sbt launcher and may be used as a starting point for customization.
+
+<h4 id="prompt">Configure the prompt string</h4>
+
+By default, sbt only displays `> ` to prompt for a command.
+This can be changed through the `shellPrompt` setting, which has type `State => String`.
+[State] contains all state for sbt and thus provides access to all build information for use in the prompt string.
+
+Examples:
+{% highlight scala %}
+// set the prompt (for this build) to include the project id.
+shellPrompt in ThisBuild := { state => Project.extract(state).currentRef.project + "> " }
+
+// set the prompt (for the current project) to include the username
+shellPrompt := { state => System.getProperty("user.name") + "> " }
+{% endhighlight %}
+
+<h4 id="history">Using history</h4>
+
+Interactive mode remembers history, even if you exit sbt and restart it.
+The simplest way to access history is with the up arrow key. The following
+commands are also supported:
+
+* `!` Show history command help.
+* `!!` Execute the previous command again.
+* `!:` Show all previous commands.
+* `!:n` Show the last n commands.
+* `!n` Execute the command with index `n`, as shown by the `!:` command.
+* `!-n` Execute the nth command before this one.
+* `!string` Execute the most recent command starting with 'string'
+* `!?string` Execute the most recent command containing 'string'
+
+<h4 id="history_file">Changing the history file location</h4>
+
+By default, interactive history is stored in the `target/` directory for the current project (but is not removed by a `clean`).
+History is thus separate for each subproject.
+The location can be changed with the `historyPath` setting, which has type `Option[File]`.
+For example, history can be stored in the root directory for the project instead of the output directory:
+
+{% highlight scala %}
+historyPath <<= baseDirectory(t => Some(t / ".history"))
+{% endhighlight %}
+
+The history path needs to be set for each project, since sbt will use the value of `historyPath` for the current project (as selected by the `project` command).
+
+<h4 id="share_history">Use the same history for all projects</h4>
+
+The previous section describes how to configure the location of the history file.
+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 `historyPath` to be the same file, such as a file in the root project's `target/` directory:
+
+{% highlight scala %}
+historyPath <<=
+ (target in LocalRootProject) { t =>
+ Some(t / ".history")
+ }
+{% endhighlight %}
+
+The `in LocalRootProject` part means to get the output directory for the root project for the build.
+
+<h4 id="disable_history">Disable interactive history</h4>
+
+If, for whatever reason, you want to disable history, set `historyPath` to `None` in each project it should be disabled in:
+
+{% highlight scala %}
+historyPath := None
+{% endhighlight %}
+
+<h4 id="pre_commands">Run commands before entering interactive mode</h4>
+
+Interactive mode is implemented by the `shell` command.
+By default, the `shell` command is run if no commands are provided to sbt on the command line.
+To run commands before entering interactive mode, specify them on the command line followed by `shell`.
+For example,
+
+ $ sbt clean compile shell
+
+This runs `clean` and then `compile` before entering the interactive prompt.
+If either `clean` or `compile` fails, sbt will exit without going to the prompt.
+To enter the prompt whether or not these initial commands succeed, prepend `-shell`, which means to run `shell` if any command fails.
+For example,
+
+ $ sbt -shell clean compile shell
View
110 src/jekyll/howto/logging.md
@@ -0,0 +1,110 @@
+---
+layout: howto
+title: Configure and use logging
+sections:
+ - id: last
+ name: view the logging output of the previously executed command
+ command: last
+ - id: tasklast
+ name: view the previous logging output of a specific task
+ command: last compile
+ - id: lastgrep
+ name: search the logging output of the previously executed command
+ command: last-grep *Test.jar
+ - id: tasklastgrep
+ name: search the previous logging output of a specific task
+ command: last-grep *Test.jar run
+ - id: level
+ name: change the logging level globally
+ command: set every logLevel := Level.Debug
+ - id: tasklevel
+ name: change the logging level for a specific task, configuration, or project
+ setting: logLevel in compile := Level.Debug
+ - id: trace
+ name: configure printing of stack traces globally
+ command: set every traceLevel := 5`
+ - id: tasktrace
+ name: configure printing of stack traces for a specific task, configuration, or project
+ setting: traceLevel := 5
+ - id: nobuffer
+ name: print the output of tests immediately instead of buffering
+ setting: logBuffered := false
+ - id: custom
+ name: add a custom logger
+ - id: log
+ name: log messages from a task
+---
+
+<h4 id="last">View logging output of the previously executed command</h4>
+
+When a command is run, more detailed logging output is sent to a file than to the screen (by default).
+This output can be recalled for the command just executed by running `last`.
+
+For example, the output of `run` when the sources are uptodate is:
+
+{% highlight console %}
+> run
+[info] Running A
+Hi!
+[success] Total time: 0 s, completed Feb 25, 2012 1:00:00 PM
+{% endhighlight %}
+
+The details of this execution can be recalled by running `last`:
+
+{% highlight console %}
+> last
+[debug] Running task... Cancelable: false, max worker threads: 4, check cycles: false
+[debug]
+[debug] Initial source changes:
+[debug] removed:Set()
+[debug] added: Set()
+[debug] modified: Set()
+[debug] Removed products: Set()
+[debug] Modified external sources: Set()
+[debug] Modified binary dependencies: Set()
+[debug] Initial directly invalidated sources: Set()
+[debug]
+[debug] Sources indirectly invalidated by:
+[debug] product: Set()
+[debug] binary dep: Set()
+[debug] external source: Set()
+[debug] Initially invalidated: Set()
+[debug] Copy resource mappings:
+[debug]
+[info] Running A
+[debug] Starting sandboxed run...
+[debug] Waiting for threads to exit or System.exit to be called.
+[debug] Classpath:
+[debug] /tmp/e/target/scala-2.9.1/classes
+[debug] /tmp/e/.sbt/0.12.0/boot/scala-2.9.1/lib/scala-library.jar
+[debug] Waiting for thread run-main to exit
+[debug] Thread run-main exited.
+[debug] Interrupting remaining threads (should be all daemons).
+[debug] Sandboxed run complete..
+[debug] Exited with code 0
+[success] Total time: 0 s, completed Jan 1, 2012 1:00:00 PM
+{% endhighlight %}
+
+Configuration of the logging level for the console and for the backing file are described in following sections.
+
+<h4 id="tasklast">View the logging output of a specific task</h4>
+
+<h4 id="lastgrep">Search the logging output of the previously executed command</h4>
+
+<h4 id="tasklastgrep">Search the logging output of a specific task</h4>
+
+<h4 id="level">Change the logging level globally</h4>
+
+<h4 id="tasklevel">Change the logging level for a specific task, configuration, or project</h4>
+
+<h4 id="trace">Configure printing of stack traces globally</h4>
+
+<h4 id="tasktrace">Configure printing of stack traces for a specific task, configuration, or project</h4>
+
+<h4 id="nobuffer">Print the output of tests immediately instead of buffering</h4>
+
+<h4 id="custom">Add a custom logger</h4>
+
+<h4 id="log">Log messages in a task</h4>
+
+
View
60 src/jekyll/howto/metadata.md
@@ -0,0 +1,60 @@
+---
+layout: howto
+title: Project metadata
+sections:
+ - id: name
+ name: set the project name
+ setting: name := "demo"
+ - id: version
+ name: set the project version
+ setting: version := "1.0"
+ - id: organization
+ name: set the project organization
+ setting: organization := "org.example"
+ - id: other
+ name: set the project homepage and other metadata used in a published pom.xml
+---
+
+A project should define `name` and `version`. These will be used in various parts of the build, such as the names of generated artifacts. Projects that are published to a repository should also override `organization`.
+
+<h4 id="name">Set the project name</h4>
+
+{% highlight scala %}
+name := "Your project name"
+{% endhighlight %}
+
+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 `normalizedName`.
+
+<h4 id="version">Set the project version</h4>
+
+{% highlight scala %}
+version := "1.0"
+{% endhighlight %}
+
+<h4 id="organization">Set the project organization</h4>
+
+{% highlight scala %}
+organization := "org.example"
+{% endhighlight %}
+
+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.
+
+A full/formal name can be defined in the `organizationName` setting. This is used in the generated pom.xml. If the organization has a web site, it may be set in the `organizationHomepage` setting. For example:
+
+{% highlight scala %}
+organization := "Example, Inc."
+
+organizationHomepage := "org.example"
+{% endhighlight %}
+
+<h4 id="other">Set the project's homepage and other metadata</h4>
+
+{% highlight scala %}
+homepage := Some(url("http://scala-sbt.org"))
+
+startYear := Some(2008)
+
+description := "A build tool for Scala."
+
+licenses += "GPLv2" -> "http://www.gnu.org/licenses/gpl-2.0.html"
+{% endhighlight %}
View
78 src/jekyll/howto/package.md
@@ -0,0 +1,78 @@
+---
+layout: howto
+title: Configure packaging
+sections:
+ - id: export
+ name: use the packaged jar on classpaths instead of class directory
+ setting: exportJars := true
+ - id: manifest
+ name: add manifest attributes
+ setting: 'packageOptions in (Compile, packageBin) += Package.ManifestAttributes( Attributes.Name.SEALED -> "true" )'
+ - id: name
+ name: change the file name of a package
+ - id: contents
+ name: modify the contents of the package
+ setting: 'mappings in (Compile, packageBin) <+= baseDirectory { dir => ( dir / "example.txt") -> "out/example.txt" }'
+---
+
+[mapping files]: https://github.com/harrah/xsbt/wiki/Mapping-Files
+[Artifacts]: https://github.com/harrah/xsbt/wiki/Artifacts
+
+<h4 id="export">Use the packaged jar on classpaths instead of class directory</h4>
+
+By default, a project exports a directory containing its resources and compiled class files. Set `exportJars` to true to export the packaged jar instead. For example,
+
+{% highlight scala %}
+exportJars := true
+{% endhighlight %}
+
+The jar will be used by `run`, `test`, `console`, and other tasks that use the full classpath.
+
+<h4 id="manifest">Add attributes to the manifest</h4>
+
+By default, sbt constructs a manifest for the binary package from settings such as `organization` and `mainClass`. Additional attributes may be added to the `packageOptions` setting scoped by the configuration and package task.
+
+Main attributes may be added with `Package.ManifestAttributes`. There are two variants of this method, once that accepts repeated arguments that map an attribute of type `java.util.jar.Attributes.Name` to a String value and other that maps attribute names (type String) to the String value.
+
+For example,
+
+{% highlight scala %}
+packageOptions in (Compile, packageBin) +=
+ Package.ManifestAttributes( java.util.jar.Attributes.Name.SEALED -> "true" )
+{% endhighlight %}
+
+Other attributes may be added with `Package.JarManifest`.
+
+{% highlight scala %}
+packageOptions in (Compile, packageBin) += {
+ import java.util.jar.{Attributes, Manifest}
+ val manifest = new Manifest
+ manifest.getAttributes("foo/bar/").put(Attributes.Name.SEALED, "false")
+ Package.JarManifest( manifest )
+}
+{% endhighlight %}
+
+Or, to read the manifest from a file:
+
+{% highlight scala %}
+packageOptions in (Compile, packageBin) += {
+ val manifest = Using.fileInputStream( in => new java.util.jar.Manifest(in) )
+ Package.JarManifest( manifest )
+}
+{% endhighlight %}
+
+<h4 id="name">Change the file name of a package</h4>
+
+The `artifactName` setting controls the name of generated packages. See the [Artifacts] page for details.
+
+<h4 id="contents">Modify the contents of the package</h4>
+
+The contents of a package are defined by the `mappings` task, of type `Seq[(File,String)]`. The `mappings` task is a sequence of mappings from a file to include in the package to the path in the package. See the page on [mapping files] for convenience functions for generating these mappings. For example, to add the file `in/example.txt` to the main binary jar with the path "out/example.txt",
+
+{% highlight scala %}
+mappings in (Compile, packageBin) <+= baseDirectory { base =>
+ (base / "in" / "example.txt") -> "out/example.txt"
+}
+{% endhighlight %}
+
+Note that `mappings` is scoped by the configuration and the specific package task. For example, the mappings for the test source package are defined by the `mappings in (Test, packageSrc)` task.
View
70 src/jekyll/howto/runningcommands.md
@@ -0,0 +1,70 @@
+---
+layout: howto
+title: Running commands
+sections:
+ - id: batch
+ name: pass arguments to a command or task in batch mode
+ batch: 'clean "test-only org.example.Test" "run-main demo.Main a b c"'
+ - id: multi
+ name: provide multiple commands to run consecutively
+ command: ';clean ;compile'
+ - id: read
+ name: read commands from a file
+ command: '< /path/to/file'
+ - id: alias
+ name: define an alias for a command or task
+ command: 'alias h=help'
+ - id: eval
+ name: quickly evaluate a Scala expression
+ command: 'eval 2+2'
+---
+
+<h4 id="batch">Pass arguments to a command in batch mode</h4>
+
+sbt interprets each command line argument provided to it as a command together with the command's arguments.
+Therefore, to run a command that takes arguments in batch mode, quote the command and its arguments.
+For example,
+
+ $ sbt 'project X' clean '~ compile'
+
+<h4 id="multi">Provide several commands to run consecutively </h4>
+
+Multiple commands can be scheduled at once by prefixing each command with a semicolon.
+This is useful for specifying multiple commands where a single command string is accepted.
+For example, the syntax for triggered execution is `~ <command>`.
+To have more than one command run for each triggering, use semicolons.
+For example, the following runs `clean` and then `compile` each time a source file changes:
+
+ > ~ ;clean;compile
+
+<h4 id="read">Read commands from a file</h4>
+
+The `<` command reads commands from the files provided to it as arguments. Run `help <` at the sbt prompt for details.
+
+<h4 id="alias">Set, unset, and show aliases for commands</h4>
+
+The `alias` command defines, removes, and displays aliases for commands. Run `help alias` at the sbt prompt for details.
+
+Example usage:
+
+ > alias a=about
+ > alias
+ a = about
+ > a
+ [info] This is sbt ...
+ > alias a=
+ > alias
+ > a
+ [error] Not a valid command: a ...
+
+<h4 id="eval">Quickly evaluate a Scala expression</h4>
+
+The `eval` command compiles and runs the Scala expression passed to it as an argument.
+The result is printed along with its type.
+For example,
+
+ > eval 2+2
+ 4: Int
+
+Variables defined by an `eval` are not visible to subsequent `eval`s, although changes to system properties persist and affect the JVM that is running sbt.
+Use the Scala REPL (`console` and related commands) for full support for evaluating Scala code interactively.
View
136 src/jekyll/howto/scala.md
@@ -0,0 +1,136 @@
+---
+layout: howto
+title: Configure and use Scala
+sections:
+ - id: version
+ name: set the Scala version used for building the project
+ setting: version := "1.0"
+ - id: noauto
+ name: disable the automatic dependency on the Scala library
+ setting: autoScalaLibrary := false
+ - id: temporary
+ name: temporarily switch to a different Scala version
+ command: ++ 2.8.2
+ - id: local
+ name: use a local Scala installation for building a project
+ setting: scalaHome := Some(file("/path/to/scala/home/"))
+ - id: cross
+ name: build a project against multiple Scala versions
+ - id: console-quick
+ name: enter the Scala REPL with a project's dependencies on the classpath, but not the compiled project classes
+ command: console-quick
+ - id: console
+ name: enter the Scala REPL with a project's dependencies and compiled code on the classpath
+ command: console
+ - id: console-project
+ name: enter the Scala REPL with plugins and the build definition on the classpath
+ command: console-project
+ - id: initial
+ name: define the initial commands evaluated when entering the Scala REPL
+ setting: initialCommands in console := """println("Hi!")"""
+ - id: embed
+ name: use the Scala REPL from project code
+---
+
+[console-project]: https://github.com/harrah/xsbt/wiki/Console-Project
+[cross building]: https://github.com/harrah/xsbt/wiki/Cross-Build
+[original proposal]: https://gist.github.com/404272
+
+By default, sbt's interactive mode is started when no commands are provided on the command line or when the `shell` command is invoked.
+
+<h4 id="version">Set the Scala version used for building the project</h4>
+
+The `scalaVersion` configures the version of Scala used for compilation. By default, sbt also adds a dependency on the Scala library with this version. See the next section for how to disable this automatic dependency. If the Scala version is not specified, the version sbt was built against is used. It is recommended to explicitly specify the version of Scala.
+
+For example, to set the Scala version to "2.9.1",
+
+{% highlight scala %}
+scalaVersion := "2.9.1"
+{% endhighlight %}
+
+<h4 id="noauto">Disable the automatic dependency on the Scala library</h4>
+
+sbt adds a dependency on the Scala standard library by default. To disable this behavior, set the `autoScalaLibrary` setting to false.
+
+{% highlight scala %}
+autoScalaLibrary := false
+{% endhighlight %}
+
+<h4 id="temporary">Temporarily switch to a different Scala version</h4>
+
+To set the Scala version in all scopes to a specific value, use the `++` command. For example, to temporarily use Scala 2.8.2, run:
+
+ > ++ 2.8.2
+
+<h4 id="local">Use a local Scala version</h4>
+
+Defining the `scalaHome` setting with the path to the Scala home directory will use that Scala installation. sbt still requires `scalaVersion` to be set when a local Scala version is used. For example,
+
+{% highlight scala %}
+scalaVersion := "2.10.0-local"
+
+scalaHome := Some(file("/path/to/scala/home/"))
+{% endhighlight %}
+
+<h4 id="cross">Build a project against multiple Scala versions</h4>
+
+See [cross building].
+
+<h4 id="console-quick">Enter the Scala REPL with a project's dependencies on the classpath, but not the compiled project classes</h4>
+
+The `console-quick` action retrieves dependencies and puts them on the classpath of the Scala REPL. The project's sources are not compiled, but sources of any source dependencies are compiled. To enter the REPL with test dependencies on the classpath but without compiling test sources, run `test:console-quick`. This will force compilation of main sources.
+
+<h4 id="console">Enter the Scala REPL with a project's dependencies and compiled classes on the classpath</h4>
+
+The `console` action retrieves dependencies and compiles sources and puts them on the classpath of the Scala REPL. To enter the REPL with test dependencies and compiled test sources on the classpath, run `test:console`.
+
+<h4 id="console-project">Enter the Scala REPL with plugins and the build definition on the classpath</h4>
+
+ > console-project
+
+For details, see the [console-project] page.
+
+<h4 id="initial">Define the initial commands evaluated when entering the Scala REPL</h4>
+
+Set `initialCommands in console` to set the initial statements to evaluate when `console` and `console-quick` are run. To configure `console-quick` separately, use `initialCommands in consoleQuick`.
+For example,
+
+{% highlight scala %}
+initialCommands in console := """println("Hello from console")"""
+
+initialCommands in consoleQuick := """println("Hello from console-quick")"""
+{% endhighlight %}
+
+The `console-project` command is configured separately by `initialCommands in consoleProject`. It does not use the value from `initialCommands in console` by default. For example,
+
+{% highlight scala %}
+initialCommands in consoleProject := """println("Hello from console-project")"""
+{% endhighlight %}
+
+<h4 id="embed">Use the Scala REPL from project code</h4>
+
+sbt runs tests in the same JVM as sbt itself and Scala classes are not in the same class loader as the application classes. This is also the case in `console` and when `run` is not forked. Therefore, when using the Scala interpreter, it is important to set it up properly to avoid an error message like:
+
+ Failed to initialize compiler: class scala.runtime.VolatileBooleanRef not found.
+ ** Note that as of 2.8 scala does not assume use of the java classpath.
+ ** For the old behavior pass -usejavacp to scala, or if using a Settings
+ ** object programmatically, settings.usejavacp.value = true.
+
+The key is to initialize the Settings for the interpreter using _embeddedDefaults_. For example:
+
+{% highlight scala %}
+val settings = new Settings
+settings.embeddedDefaults[MyType]
+val interpreter = new Interpreter(settings, ...)
+{% endhighlight %}
+
+Here, MyType is a representative class that should be included on the interpreter's classpath and in its application class loader. For more background, see the [original proposal] that resulted in _embeddedDefaults_ being added.
+
+Similarly, use a representative class as the type argument when using the _break_ and _breakIf_ methods of _ILoop_, as in the following example:
+
+{% highlight scala %}
+def x(a: Int, b: Int) = {
+ import scala.tools.nsc.interpreter.ILoop
+ ILoop.breakIf[MyType](a != b, "a" -> a, "b" -> b )
+}
+{% endhighlight %}
View
66 src/jekyll/howto/triggered.md
@@ -0,0 +1,66 @@
+---
+layout: howto
+title: Triggered execution
+sections:
+ - id: basic
+ name: run a command when sources change
+ command: '~ test'
+ - id: multi
+ name: run multiple commands when sources change
+ command: '~ ;a ;b'
+ - id: sources
+ name: configure the sources that are checked for changes
+ setting: 'watchSources <+= baseDirectory { _ / "examples.txt" }'
+ - id: interval
+ name: set the time interval between checks for changes to sources
+ setting: 'pollInterval := 1000 // in ms'
+---
+
+[Full Configuration](https://github.com/harrah/xsbt/wiki/Full-Configuration)
+
+<h4 id="basic">Run a command when sources change</h4>
+
+You can make a command run when certain files change by prefixing the command with `~`. Monitoring is terminated when `enter` is pressed. This triggered execution is configured by the `watch` setting, but typically the basic settings `watch-sources` and `poll-interval` are modified as described in later sections.
+
+The original use-case for triggered execution was continuous compilation:
+
+{% highlight scala %}
+> ~ test:compile
+
+> ~ compile
+{% endhighlight %}
+
+You can use the triggered execution feature to run any command or task, however. The following will poll for changes to your source code (main or test) and run `test-only` for the specified test.
+
+{% highlight scala %}
+> ~ test-only example.TestA
+{% endhighlight %}
+
+<h4 id="multi">Run multiple commands when sources change</h4>
+
+The command passed to `~` may be any command string, so multiple commands may be run by separating them with a semicolon. For example,
+
+{% highlight scala %}
+> ~ ;a ;b
+{% endhighlight %}
+
+This runs `a` and then `b` when sources change.
+
+<h4 id="sources">Configure the sources checked for changes</h4>
+
+* `watchSources` defines the files for a single project that are monitored for changes. By default, a project watches resources and Scala and Java sources.
+* `watchTransitiveSources` then combines the `watchSources` for the current project and all execution and classpath dependencies (see [Full Configuration] for details on inter-project dependencies).
+
+To add the file `demo/example.txt` to the files to watch,
+
+{% highlight scala %}
+watchSources <+= baseDirectory { _ / "demo" / "examples.txt" }
+{% endhighlight %}
+
+<h4 id="interval">Configure the polling time</h4>
+
+* `pollInterval` selects the interval between polling for changes in milliseconds. The default value is `500 ms`. To change it to `1 s`,
+
+{% highlight scala %}
+pollInterval := 1000 // in ms
+{% endhighlight %}
View
2  src/jekyll/index.html
@@ -11,7 +11,7 @@
<meta http-equiv="Content-Type" content="text/html"; charset="utf-8">
<title>simple build tool</title>
<link href='http://fonts.googleapis.com/css?family=Copse' rel='stylesheet' type='text/css'>
- <link href='resources/site.css' rel='stylesheet' type='text/css'> <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js">
+ <link href='/resources/site.css' rel='stylesheet' type='text/css'> <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js">
</script>
</head>
<body class="cf">
View
6 src/jekyll/learn.md
@@ -4,14 +4,18 @@ title: Learning SBT
tagline: From Basics to Wizardry
description: |
We highly recommend trying the [Getting Started Guide](https://github.com/harrah/xsbt/wiki/Getting-Started-Welcome)
- before diving into sbt. There is also a lot of great introductory [talks](talks.html) available for your viewing pleasure.
+ before diving into sbt. There are also a lot of great introductory [talks](talks.html) available for your viewing pleasure.
toplinks:
- name: 'Getting Started Guide'
link: 'https://github.com/harrah/xsbt/wiki/Getting-Started-Welcome'
+ - name: 'How to ...'
+ link: 'howto.html'
- name: 'Talks'
link: 'talks.html'
- name: 'Wiki'
link: 'https://github.com/harrah/xsbt/wiki'
- name: 'Plugins'
link: 'plugins.html'
+ - name: 'FAQ'
+ link: 'https://github.com/harrah/xsbt/wiki/FAQ'
---
View
1  src/jekyll/plugins.html
@@ -24,6 +24,7 @@
* [coffeescripted-sbt](https://github.com/softprops/coffeescripted-sbt)
* [less-sbt](https://github.com/softprops/less-sbt)
* [sbt-emberjs](https://github.com/stefri/sbt-emberjs)
+ * [sbt-closure](https://github.com/eltimn/sbt-closure)
- name: 'Testing'
id: 'test'
content: |
View
20 src/jekyll/resources/site.css
@@ -23,13 +23,13 @@ p {
h1, h2, h3, h4, h5, #name, #vc { font-family: 'Copse', serif; }
-h1 { font-size:170px; line-height:1em; }
+h1 { font-size:130px; line-height:1em; }
-h2 { color:#bbb; font-size:190%; }
+h2 { color:#bbb; font-size:2.5em; }
-h3 { font-size:4em; line-height:1.5em; }
+h3 { font-size:2em; line-height:1.5em; }
-h4 { font-size:2em; line-height:1.5em; }
+h4 { font-size:1.75em; line-height:1.5em; }
li { margin:1em 0; }
@@ -263,8 +263,8 @@ pre {
white-space:pre-wrap;
text-shadow:0 1px 1px rgba(0, 0, 0, 0.5);
font-family:'Copse', serif;
- font-size:22px;
- font-weight:bold;
+ font-size: 16px;
+ font-weight: normal;
margin:.5em 0;
padding:.25em;
border:1px solid #bbb;
@@ -274,10 +274,6 @@ pre {
background-image:linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0));
color:#fff;
background-color:rgba(0, 0, 0, 0.5);
- background-image:-webkit-linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0));
- background-image:-o-linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0));
- filter:progid:DXImageTransform.Microsoft.gradient(startColorstr='rgba(0, 0, 0, 0.15)', endColorstr='rgba(0, 0, 0, 0)', GradientType=0);
- -ms-filter:"progid:DXImageTransform.Microsoft.gradient(startColorstr='rgba(0, 0, 0, 0.15)', endColorstr='rgba(0, 0, 0, 0)', GradientType=0");
--webkit-box-shadow:inset 0 1px 3px rgba(0, 0, 0, 0.5), 0 1px 0 rgba(255, 255, 255, 0.5);
-box-shadow:inset 0 1px 3px rgba(0, 0, 0, 0.5), 0 1px 0 rgba(255, 255, 255, 0.5);
+ -webkit-box-shadow:inset 0 1px 3px rgba(0, 0, 0, 0.5), 0 1px 0 rgba(255, 255, 255, 0.5);
+ box-shadow:inset 0 1px 3px rgba(0, 0, 0, 0.5), 0 1px 0 rgba(255, 255, 255, 0.5);
}
View
4 src/jekyll/using_sonatype.md
@@ -79,14 +79,14 @@ This might be advantageous if those keys are used also by other plugins (e.g. `l
## Fourth - Adding credentials ##
-The credentails for your Sonatype OSSRH account need to be added somewhere. Common convention is a `~/.sbt/sonatype.sbt` file with the following:
+The credentials for your Sonatype OSSRH account need to be added somewhere. Common convention is a `~/.sbt/sonatype.sbt` file with the following:
credentials += Credentials("Sonatype Nexus Repository Manager",
"oss.sonatype.org",
"<your username>",
"<your password>")
-*Note: The first two strings **must** be `"Sonatype Nexus Repository Manager"` and `"oss.sonatype.org"` for Ivy to use the credentials.*
+*Note: The first two strings must be `"Sonatype Nexus Repository Manager"` and `"oss.sonatype.org"` for Ivy to use the credentials.*
## Finally - Publish ##
Please sign in to comment.
Something went wrong with that request. Please try again.