Permalink
Browse files

howto pages

  • Loading branch information...
1 parent 775693c commit c6fe39fa861b6662c3dcc6a650592ad1997fe7a4 @harrah harrah committed Feb 26, 2012
@@ -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.
@@ -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
@@ -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>
+
+
Oops, something went wrong.

0 comments on commit c6fe39f

Please sign in to comment.