mirror of https://github.com/sbt/sbt.git
Group "getting started" pages by prefix and directory
The directory will allow a separate _Sidebar.md for the Getting Started. The redundant prefixes are required because gollum URLs don't have the directory.
Havoc Pennington
parent
2de2a8d99f
commit
8716a9af66
|
|
@ -67,4 +67,4 @@ libraryDependencies <<= (scalaVersion, libraryDependencies) { (sv, deps) =>
|
|||
|
||||
This works because your project definition is reloaded for each version of Scala you are building against. `scalaVersion` contains the current version of Scala being used to build the project.
|
||||
|
||||
As a final note, you can use `++ <version>` to temporarily switch the Scala version currently being used to build (see [[Running]] for details).
|
||||
As a final note, you can use `++ <version>` to temporarily switch the Scala version currently being used to build (see [[Running|Getting Started Running]] for details).
|
||||
|
|
|
|||
|
|
@ -159,7 +159,7 @@ Additionally, there are implicit conversions `URI => RootProject` and `File => R
|
|||
External, remote builds are retrieved or checked out to a staging directory in the user's `.sbt` directory so that they can be manipulated like local builds.
|
||||
Examples of using project references follow in the next sections.
|
||||
|
||||
When using external projects, the `sbt.boot.directory` should be set (see [[Setup]]) so that unnecessary recompilations do not occur (see [#35]).
|
||||
When using external projects, the `sbt.boot.directory` should be set (see [[Setup|Getting Started Setup]]) so that unnecessary recompilations do not occur (see [#35]).
|
||||
|
||||
### Execution Dependency
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
# Basic Build Definition
|
||||
|
||||
This page describes sbt build definitions, including some "theory" and the
|
||||
syntax of `build.sbt`. It assumes you know how to [[use sbt|Running]] and
|
||||
syntax of `build.sbt`. It assumes you know how to [[use sbt|Getting Started Running]] and
|
||||
have read the previous pages in the Getting Started category.
|
||||
|
||||
## Basic vs. Full Definition
|
||||
|
|
@ -17,7 +17,7 @@ use `.scala` files only to contain what can't be done in `.sbt`:
|
|||
- to define nested sub-projects
|
||||
|
||||
This page discusses "basic" build definition, that is, `.sbt` files. See
|
||||
[[Full Build Definition]] (later in Getting Started) for more on full build
|
||||
[[full build definition|Getting Started Full Def]] (later in Getting Started) for more on full build
|
||||
files and how they relate to basic build files.
|
||||
|
||||
## What is a build definition?
|
||||
|
|
@ -109,16 +109,16 @@ Keys are just fields in an object called [Keys]. A `build.sbt` implicitly
|
|||
has an `import sbt.Keys._`, so `sbt.Keys.name` can be referred to as `name`.
|
||||
|
||||
Custom keys could also be defined in a
|
||||
[[full build definition|Full Build Definition]] or a [[plugin|Using Plugins]].
|
||||
[[full build definition|Getting Started Full Def]] or a [[plugin|Getting Started Using Plugins]].
|
||||
|
||||
## Other ways to transform settings
|
||||
|
||||
Replacement with `:=` is the simplest transformation, but there are several
|
||||
others. For example you can append to a list value with `+=`.
|
||||
|
||||
The other transformations require an understanding of [[scopes|Scopes]], so the
|
||||
[[next section|Scopes]] is about scopes and the
|
||||
[[section after that|More About Settings]] goes into more detail about settings.
|
||||
The other transformations require an understanding of [[scopes|Getting Started Scopes]], so the
|
||||
[[next section|Getting Started Scopes]] is about scopes and the
|
||||
[[section after that|Getting Started More About Settings]] goes into more detail about settings.
|
||||
|
||||
## Task Keys
|
||||
|
||||
|
|
@ -164,7 +164,7 @@ creates a value of type `T` when the task executes.
|
|||
|
||||
The `T` vs. `Task[T]` type difference has this implication: a setting key
|
||||
can't depend on a task key, because a setting key is cached, and not
|
||||
re-run. More on this in [[More About Settings]], coming up soon.
|
||||
re-run. More on this in [[more about settings|Getting Started More About Settings]], coming up soon.
|
||||
|
||||
## Keys in sbt interactive mode
|
||||
|
||||
|
|
@ -203,11 +203,11 @@ import Process._
|
|||
import Keys._
|
||||
```
|
||||
|
||||
(In addition, if you have a [[full build definition|Full Build Definition]],
|
||||
(In addition, if you have a [[full build definition|Getting Started Full Def]],
|
||||
the contents of any `Build` or `Plugin` objects in that definition will be
|
||||
imported. More on that when we get to
|
||||
[[full build definitions|Full Build Definition]].)
|
||||
[[full build definitions|Getting Started Full Def]].)
|
||||
|
||||
## Next
|
||||
|
||||
Move on to [[learn about scopes|Scopes]].
|
||||
Move on to [[learn about scopes|Getting Started Scopes]].
|
||||
|
|
@ -7,7 +7,7 @@
|
|||
This page gets you started creating your own settings and tasks.
|
||||
|
||||
Be sure you've read earlier pages in the Getting Started series, especially
|
||||
[[build.sbt|Basic Build Definition]] and [[More About Settings]], before
|
||||
[[build.sbt|Getting Started Basic Def]] and [[more about settings|Getting Started More About Settings]], before
|
||||
reading this page.
|
||||
|
||||
## Defining a key
|
||||
|
|
@ -16,7 +16,7 @@ reading this page.
|
|||
keys. Most of the keys are implemented in [Defaults].
|
||||
|
||||
Keys have one of three types. `SettingKey` and `TaskKey` are described in
|
||||
[[Basic Build Definition]]. Read about `InputKey` on the [[Input Tasks]]
|
||||
[[basic build definition|Getting Started Basic Def]]. Read about `InputKey` on the [[Input Tasks]]
|
||||
page.
|
||||
|
||||
Some examples from [Keys]:
|
||||
|
|
@ -30,16 +30,16 @@ The `Key` constructors have two string parameters: the name of the key
|
|||
(`"scala-version"`) and a documentation string (`"The version of scala used for
|
||||
building."`).
|
||||
|
||||
Remember from [[Basic Build Definition]] that the type parameter `T` in `SettingKey[T]`
|
||||
Remember from [[basic build definition|Getting Started Basic Def]] that the type parameter `T` in `SettingKey[T]`
|
||||
indicates the type of value a setting has. `T` in `TaskKey[T]` indicates the
|
||||
type of the task's result. Also remember from [[Basic Build Definition]]
|
||||
type of the task's result. Also remember from [[basic build definition|Getting Started Basic Def]]
|
||||
that a setting has a fixed value cached forever, while a task is re-computed
|
||||
for every "task execution" (every time someone types a command at the sbt
|
||||
interactive prompt or in batch mode).
|
||||
|
||||
Keys may be defined in a `.scala` file (as described in
|
||||
[[Full Build Definition]]), or in a plugin (as described in
|
||||
[[Using Plugins]]).
|
||||
[[full build definition|Getting Started Full Def]]), or in a plugin (as described in
|
||||
[[using plugins|Getting Started Using Plugins]]).
|
||||
|
||||
## Implementing a task
|
||||
|
||||
|
|
@ -59,13 +59,13 @@ sampleIntTask := {
|
|||
```
|
||||
|
||||
If the task has dependencies, you'd use `<<=` instead of course, as
|
||||
discussed in [[More About Settings]].
|
||||
discussed in [[more about settings|Getting Started More About Settings]].
|
||||
|
||||
The hardest part about implementing tasks is often not sbt-specific; tasks
|
||||
are just Scala code. The hard part could be writing the "meat" of your task
|
||||
that does whatever you're trying to do. For example, maybe you're trying to
|
||||
format HTML in which case you might want to use an HTML library (you would
|
||||
[[add a library dependency to your build definition|Using Plugins]] and
|
||||
[[add a library dependency to your build definition|Getting Started Using Plugins]] and
|
||||
write code based on the HTML library, perhaps).
|
||||
|
||||
sbt has some utility libraries and convenience functions, in particular you
|
||||
|
|
@ -89,7 +89,7 @@ intTask ~= { (value: Int) => value + 1 }
|
|||
If you find you have a lot of custom code in `.scala` files, consider moving
|
||||
it to a plugin for re-use across multiple projects.
|
||||
|
||||
It's very easy to create a plugin, as [[teased earlier|Using Plugins]] and
|
||||
It's very easy to create a plugin, as [[teased earlier|Getting Started Using Plugins]] and
|
||||
[[discussed at more length here|Plugins]].
|
||||
|
||||
## Next
|
||||
|
|
@ -97,4 +97,4 @@ It's very easy to create a plugin, as [[teased earlier|Using Plugins]] and
|
|||
This page has been a quick taste; there's much much more about custom tasks
|
||||
on the [[Tasks]] page.
|
||||
|
||||
You're at the end of Getting Started! There's a [[brief recap|Summary]].
|
||||
You're at the end of Getting Started! There's a [[brief recap|Getting Started Summary]].
|
||||
|
|
@ -2,13 +2,13 @@
|
|||
|
||||
# Directory structure
|
||||
|
||||
This page assumes you've [[installed sbt|Setup]] and seen the [[Hello, World|Hello World]].
|
||||
This page assumes you've [[installed sbt|Getting Started Setup]] and seen the [[Hello, World|Getting Started Hello]].
|
||||
|
||||
## Base directory
|
||||
|
||||
In sbt's terminology, the "base directory" is the directory containing the
|
||||
project. So if you created a project `hello` containing `hello/build.sbt`
|
||||
and `hello/hw.scala` as in the [[Hello, World|Hello World]] example, `hello`
|
||||
and `hello/hw.scala` as in the [[Hello, World|Getting Started Hello]] example, `hello`
|
||||
is your base directory.
|
||||
|
||||
## Source code
|
||||
|
|
@ -46,7 +46,7 @@ You've already seen `build.sbt` in the project's base directory. Other sbt
|
|||
files appear in a `project` subdirectory.
|
||||
|
||||
`project` can contain `.scala` files, also called
|
||||
[[full build definitions|Full Build Definition]], when you're doing
|
||||
[[full build definitions|Getting Started Full Def]], when you're doing
|
||||
something too complex for a `.sbt` file.
|
||||
|
||||
sbt-launch.jar automatically downloads the Scala compiler, sbt itself, and
|
||||
|
|
@ -64,7 +64,7 @@ have much in `project/boot`.
|
|||
|
||||
You may see `.sbt` files inside `project/` but they are not equivalent to
|
||||
`.sbt` files in the project's base directory. Explaining this will
|
||||
[[come later|Full Build Definition]], since you'll need some background
|
||||
[[come later|Getting Started Full Def]], since you'll need some background
|
||||
information first.
|
||||
|
||||
## Build products
|
||||
|
|
@ -84,4 +84,4 @@ These directories are automatically created and managed by sbt and need not be k
|
|||
|
||||
# Next
|
||||
|
||||
Learn about [[running sbt|Running]].
|
||||
Learn about [[running sbt|Getting Started Running]].
|
||||
|
|
@ -1,8 +1,8 @@
|
|||
# Full Build Definition
|
||||
|
||||
This page is part of a Getting Started series, and it assumes you've read
|
||||
previous pages in the series, _especially_ [[Basic Build Definition]] and
|
||||
[[More About Settings]].
|
||||
previous pages in the series, _especially_ [[basic build definition|Getting Started Basic Def]] and
|
||||
[[more about settings|Getting Started More About Settings]].
|
||||
|
||||
## sbt is recursive
|
||||
|
||||
|
|
@ -79,7 +79,7 @@ _`.sbt` files in the base directory for a project become part of the
|
|||
`project` build definition project also located in that base directory._
|
||||
|
||||
`build.sbt`, also known as a
|
||||
[[basic build definition|Basic Build Definition]], is a convenient shorthand
|
||||
[[basic build definition|Getting Started Basic Def]], is a convenient shorthand
|
||||
for adding settings to the build definition project.
|
||||
|
||||
A _full build definition_ is a build definition that includes `.scala` files
|
||||
|
|
@ -207,7 +207,8 @@ nested project inside your main project. `.sbt` ("basic") and `.scala`
|
|||
("full") files are compiled together to create that single definition.
|
||||
|
||||
`.scala` files are also required to define multiple projects in a single
|
||||
build. More on that is coming up in [[Multi-Project Builds]].
|
||||
build. More on that is coming up in
|
||||
[[Multi-Project Builds|Getting Started Multi-Project]].
|
||||
|
||||
## The build definition project in interactive mode
|
||||
|
||||
|
|
@ -246,7 +247,7 @@ this order:
|
|||
- Settings from `Build.settings` and `Project.settings` in your `.scala` files.
|
||||
- Your user-global settings; for example in `~/.sbt/build.sbt` you can
|
||||
define settings affecting _all_ your projects.
|
||||
- Settings injected by plugins, see [[Using Plugins]] coming up next.
|
||||
- Settings injected by plugins, see [[using plugins|Getting Started Using Plugins]] coming up next.
|
||||
- Settings from `.sbt` files in the project.
|
||||
- FIXME parse this: "settings that configure the global plugin definition for a
|
||||
project-level plugin definition as if it were declared locally"
|
||||
|
|
@ -256,4 +257,4 @@ build definition.
|
|||
|
||||
## Next
|
||||
|
||||
Move on to [[Using Plugins]].
|
||||
Move on to [[using plugins|Getting Started Using Plugins]].
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
|
||||
# Hello, World
|
||||
|
||||
This page assumes you've [[installed sbt|Setup]].
|
||||
This page assumes you've [[installed sbt|Getting Started Setup]].
|
||||
|
||||
## Create a project directory with source code
|
||||
|
||||
|
|
@ -54,7 +54,7 @@ version := "1.0"
|
|||
scalaVersion := "2.9.1"
|
||||
```
|
||||
|
||||
In [[Basic Build Definition]] you'll learn more about how to write a `build.sbt` file.
|
||||
In [[basic build definition|Getting Started Basic Def]] you'll learn more about how to write a `build.sbt` file.
|
||||
|
||||
If you plan to package your project in a jar, you will want to set at least
|
||||
the name and version in a `build.sbt`.
|
||||
|
|
@ -74,5 +74,5 @@ confusion.
|
|||
|
||||
# Next
|
||||
|
||||
Learn about the [[file and directory layout|Directory Structure]] of an sbt project.
|
||||
Learn about the [[file and directory layout|Getting Started Directories]] of an sbt project.
|
||||
|
||||
|
|
@ -10,7 +10,8 @@
|
|||
# Library Dependencies
|
||||
|
||||
This page assumes you've read the earlier Getting Started pages, in particular
|
||||
[[Basic Build Definition]], [[Scopes]], and [[More About Settings]].
|
||||
[[basic build definition|Getting Started Basic Def]],
|
||||
[[scopes|Getting Started Scopes]], and [[more about settings|Getting Started More About Settings]].
|
||||
|
||||
Library dependencies can be added in two ways:
|
||||
|
||||
|
|
@ -34,7 +35,7 @@ Dependencies in `lib` go on all the classpaths (for `compile`, `test`,
|
|||
those, you would adjust `dependencyClasspath in Compile` or
|
||||
`dependencyClasspath in Runtime` for example. You could use `~=` to get the
|
||||
previous classpath value, filter some entries out, and return a new
|
||||
classpath value. See [[More About Settings]] for details of `~=`.
|
||||
classpath value. See [[more about settings|Getting Started More About Settings]] for details of `~=`.
|
||||
|
||||
There's nothing to add to `build.sbt` to use unmanaged dependencies, though
|
||||
you could change the `unmanaged-base` key if you'd like to use a different
|
||||
|
|
@ -48,7 +49,7 @@ unmanagedBase <<= baseDirectory { base => base / "custom_lib" }
|
|||
|
||||
`baseDirectory` is the project's root directory, so here you're changing
|
||||
`unmanagedBase` depending on `baseDirectory`, using `<<=` as explained in
|
||||
[[More About Settings]].
|
||||
[[more about settings|Getting Started More About Settings]].
|
||||
|
||||
There's also an `unmanaged-jars` task which lists the jars from the
|
||||
`unmanaged-base` directory. If you wanted to use multiple directories or do
|
||||
|
|
@ -226,4 +227,4 @@ dependencies [[on this page|Library-Management]], if you didn't find an
|
|||
answer on this introductory page.
|
||||
|
||||
If you're reading Getting Started in order, for now, you might move on to
|
||||
read [[Full Build Definition]].
|
||||
read [[full build definition|Getting Started Full Def]].
|
||||
|
|
@ -4,18 +4,18 @@
|
|||
# More Kinds of Setting
|
||||
|
||||
This page explains other ways to create a `Setting`, beyond the basic `:=`
|
||||
method. It assumes you've read [[Basic Build Definition]] and [[Scopes]].
|
||||
method. It assumes you've read [[basic build definition|Getting Started Basic Def]] and [[scopes|Getting Started Scopes]].
|
||||
|
||||
## Refresher: Settings
|
||||
|
||||
[[Remember|Basic Build Definition]], a build definition creates a list of
|
||||
[[Remember|Getting Started Basic Def]], a build definition creates a list of
|
||||
`Setting`, which is then used to transform sbt's description of the build
|
||||
(which is a map of key-value pairs). A `Setting` is a transformation with
|
||||
sbt's earlier map as input and a new map as output. The new map becomes
|
||||
sbt's new state.
|
||||
|
||||
Different settings transform the map in different
|
||||
ways. [[Earlier|Basic Build Definition]], you read about the `:=` method.
|
||||
ways. [[Earlier|Getting Started Basic Def]], you read about the `:=` method.
|
||||
|
||||
The `Setting` which `:=` creates puts a fixed, constant value in the new,
|
||||
transformed map. For example, if you transform a map with the setting
|
||||
|
|
@ -24,7 +24,7 @@ transformed map. For example, if you transform a map with the setting
|
|||
|
||||
Settings must end up in the master list of settings to do any good (all
|
||||
lines in a `build.sbt` automatically end up in the list, but in a
|
||||
[[full build definition|Full Build Definition]] you can get it wrong).
|
||||
[[full build definition|Getting Started Full Def]] you can get it wrong).
|
||||
|
||||
## Appending to previous values: `+=` and `++=`
|
||||
|
||||
|
|
@ -264,14 +264,14 @@ Whenever a setting uses `~=` or `<<=` to create a dependency on itself or
|
|||
another key's value, the value it depends on must exist. If it does not,
|
||||
sbt will complain. It might say _"Reference to undefined setting"_, for
|
||||
example. When this happens, be sure you're using the key in the
|
||||
[[scope|Scopes]] that defines it.
|
||||
[[scope|Getting Started Scopes]] that defines it.
|
||||
|
||||
It's possible to create cycles, which is an error; sbt will tell you if you
|
||||
do this.
|
||||
|
||||
### Tasks with dependencies
|
||||
|
||||
As noted in [[Basic Build Definition]], task keys create a
|
||||
As noted in [[more about settings|Getting Started Basic Def]], task keys create a
|
||||
`Setting[Task[T]]` rather than a `Setting[T]` when you build a setting with
|
||||
`:=`, `<<=`, etc. Similarly, task keys are instances of
|
||||
`Initialize[Task[T]]` rather than `Initialize[T]` and `<<=` on a task key
|
||||
|
|
@ -404,4 +404,4 @@ cleanFiles <+= (name) { n => file("coverage-report-" + n + ".txt") }
|
|||
|
||||
At this point you know how to get things done with settings, so we can move
|
||||
on to a specific key that comes up often: `libraryDependencies`.
|
||||
[[Learn about library dependencies|Library Dependencies]].
|
||||
[[Learn about library dependencies|Getting Started Library Dependencies]].
|
||||
|
|
@ -4,7 +4,7 @@ This page introduces multiple projects in a single build.
|
|||
|
||||
It's part of a Getting Started series. Please read the earlier pages in the
|
||||
series first, in particular you need to understand
|
||||
[[build.sbt|Basic Build Definition]] and [[Full Build Definition]] before
|
||||
[[build.sbt|Getting Started Basic Def]] and [[full build definition|Getting Started Full Def]] before
|
||||
reading this page.
|
||||
|
||||
## Multiple projects
|
||||
|
|
@ -47,7 +47,7 @@ with type `Project` in the `Build` object.
|
|||
Because project `hello-foo` is defined with `base = file("foo")`, it will be
|
||||
contained in the subdirectory `foo`. Its sources could be directly under
|
||||
`foo`, like `foo/Foo.scala`, or in `foo/src/main/scala`. The usual sbt
|
||||
[[directory structure|Directory Structure]] applies underneath `foo` with
|
||||
[[directory structure|Getting Started Directories]] applies underneath `foo` with
|
||||
the exception of build definition files.
|
||||
|
||||
Any `.sbt` files in `foo`, say `foo/build.sbt`, will be merged with the
|
||||
|
|
@ -73,7 +73,7 @@ defined):
|
|||
`hello-foo/*:version` was defined in `hello/foo/build.sbt`,
|
||||
`hello-bar/*:version` was defined in `hello/bar/build.sbt`, and
|
||||
`hello/*:version` was defined in `hello/build.sbt`. Remember the
|
||||
[[syntax for scoped keys|Scopes]]. Each `version` key is scoped to a
|
||||
[[syntax for scoped keys|Getting Started Scopes]]. Each `version` key is scoped to a
|
||||
project, based on the location of the `build.sbt`. But all three `build.sbt`
|
||||
are part of the same build definition.
|
||||
|
||||
|
|
@ -107,7 +107,7 @@ aggregate in update := false
|
|||
```
|
||||
|
||||
`aggregate in update` is the `aggregate` key scoped to the `update` task,
|
||||
see [[Scopes]].
|
||||
see [[scopes|Getting Started Scopes]].
|
||||
|
||||
Note: aggregation will run the aggregated tasks in parallel and with no defined
|
||||
ordering.
|
||||
|
|
@ -161,4 +161,4 @@ have to compile the root project, you could compile only a subproject.
|
|||
|
||||
## Next
|
||||
|
||||
Move on to create [[Custom Settings and Tasks]].
|
||||
Move on to create [[custom settings|Getting Started Custom Settings]].
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
# Running
|
||||
|
||||
This page describes how to use `sbt` once you have set up your project. It
|
||||
assumes you've [[installed sbt|Setup]] and created a [[Hello, World|Hello World]] or other project.
|
||||
assumes you've [[installed sbt|Getting Started Setup]] and created a [[Hello, World|Getting Started Hello]] or other project.
|
||||
|
||||
## Interactive mode
|
||||
|
||||
|
|
@ -107,4 +107,4 @@ commands are also supported:
|
|||
|
||||
## Next
|
||||
|
||||
Move on to [[understanding build.sbt|Basic Build Definition]].
|
||||
Move on to [[understanding build.sbt|Getting Started Basic Def]].
|
||||
|
|
@ -5,11 +5,11 @@ http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism
|
|||
# Scopes
|
||||
|
||||
This page describes scopes. It assumes you've read and understood the
|
||||
previous page, [[Basic Build Definition]].
|
||||
previous page, [[basic build definition|Getting Started Basic Def]].
|
||||
|
||||
## The whole story about keys
|
||||
|
||||
[[Previously|Basic Build Definition]] we pretended that a key like `name`
|
||||
[[Previously|Getting Started Basic Def]] we pretended that a key like `name`
|
||||
corresponded to one entry in sbt's map of key-value pairs. This was a
|
||||
simplification.
|
||||
|
||||
|
|
@ -32,7 +32,7 @@ according to scope.
|
|||
However, there is a single value for a given _scoped_ key.
|
||||
|
||||
If you think about sbt processing a list of settings to generate a key-value
|
||||
map describing the project, as [[discussed earlier|Basic Build Definition]],
|
||||
map describing the project, as [[discussed earlier|Getting Started Basic Def]],
|
||||
the keys in that key-value map are _scoped_ keys. Each setting defined in
|
||||
the build definition (for example in `build.sbt`) applies to a scoped key as
|
||||
well.
|
||||
|
|
@ -53,7 +53,7 @@ There are three scope axes:
|
|||
|
||||
### Scoping by project axis
|
||||
|
||||
If you [[put multiple projects in a single build|Multi-Project Builds]], each
|
||||
If you [[put multiple projects in a single build|Getting Started Multi-Project]], each
|
||||
project needs its own settings. That is, keys can be scoped according to the
|
||||
project.
|
||||
|
||||
|
|
@ -66,7 +66,7 @@ setting.
|
|||
|
||||
A _configuration_ defines a flavor of build, potentially with its own
|
||||
classpath, sources, generated packages, etc. The configuration concept comes
|
||||
from Ivy, which sbt uses for [[managed dependencies|Library Dependencies]], and
|
||||
from Ivy, which sbt uses for [[managed dependencies|Getting Started Library Dependencies]], and
|
||||
from [MavenScopes].
|
||||
|
||||
Some configurations you'll see in sbt:
|
||||
|
|
@ -188,7 +188,7 @@ $ sbt
|
|||
```
|
||||
|
||||
On the first line, you can see this is a task (as opposed to a setting, as
|
||||
explained in [[Basic Build Definition]]). The value resulting from the task
|
||||
explained in [[basic build definition|Getting Started Basic Def]]). The value resulting from the task
|
||||
will have type `scala.collection.Seq[sbt.Attributed[java.io.File]]`.
|
||||
|
||||
"Provided by" points you to the scoped key that defines the value, in this
|
||||
|
|
@ -197,7 +197,7 @@ is the `full-classpath` key scoped to the `test` configuration and the
|
|||
`{file:/home/hp/checkout/hello/}default-aea33a` project).
|
||||
|
||||
"Dependencies" may not make sense yet; stay tuned for the
|
||||
[[next section|More About Settings]].
|
||||
[[next section|Getting Started More About Settings]].
|
||||
|
||||
You can also see the delegates; if the value were not defined, sbt would
|
||||
search through:
|
||||
|
|
@ -245,7 +245,7 @@ Run sbt and `inspect name` to see that it's provided by
|
|||
|
||||
`build.sbt` always defines settings for a single project, so the "current
|
||||
project" is the project you're defining in that particular `build.sbt`.
|
||||
(For [[multi-project builds|Multi-Project Builds]], each project has its own
|
||||
(For [[multi-project builds|Getting Started Multi-Project]], each project has its own
|
||||
`build.sbt`.)
|
||||
|
||||
Keys have an overloaded method called `in` used to set the scope. The
|
||||
|
|
@ -317,4 +317,4 @@ project, global config, global task).
|
|||
|
||||
## Next
|
||||
|
||||
Now that you understand scopes, you can [[learn more about settings|More About Settings]].
|
||||
Now that you understand scopes, you can [[learn more about settings|Getting Started More About Settings]].
|
||||
|
|
@ -11,11 +11,11 @@ Please go in order! Later pages assume you're familiar with earlier concepts.
|
|||
To create an sbt project, you'll need to take these steps:
|
||||
|
||||
- Install sbt and create a script to launch it.
|
||||
- Setup a simple [[Hello World]] project
|
||||
- Setup a simple [[hello world|Getting Started Hello]] project
|
||||
- Create a project directory with source files in it.
|
||||
- Create your build definition.
|
||||
- Move on to [[Running]] to learn how to run sbt.
|
||||
- Then move on to [[Basic Build Definition]] to learn more about build definitions.
|
||||
- Move on to [[running|Getting Started Running]] to learn how to run sbt.
|
||||
- Then move on to [[basic build definition|Getting Started Basic Def]] to learn more about build definitions.
|
||||
|
||||
# Installing sbt
|
||||
|
||||
|
|
@ -54,4 +54,4 @@ If you have any trouble running `sbt`, see [[Setup Notes]] on terminal encodings
|
|||
|
||||
## Next
|
||||
|
||||
Move on to [[create a simple project|Hello World]].
|
||||
Move on to [[create a simple project|Getting Started Hello]].
|
||||
|
|
@ -15,7 +15,7 @@ to know.
|
|||
- the basics of Scala. It's undeniably helpful to be familiar with Scala
|
||||
syntax. [Programming in Scala](http://www.artima.com/shop/programming_in_scala_2ed)
|
||||
written by the creator of Scala is a great introduction.
|
||||
- [[Basic Build Definition]]
|
||||
- [[Basic build definition|Getting Started Basic Def]]
|
||||
- your build definition is one big list of `Setting` objects, where a
|
||||
`Setting` transforms the set of key-value pairs sbt uses to perform tasks.
|
||||
- to create a `Setting`, call one of a few methods on a `Key` (the `:=` and
|
||||
|
|
@ -27,7 +27,7 @@ to know.
|
|||
- _tasks_ are special settings where the computation to produce the key's
|
||||
value will be re-run each time you kick off a task. Non-tasks compute the
|
||||
value once and cache it.
|
||||
- [[Scopes]]
|
||||
- [[Scopes|Getting Started Scopes]]
|
||||
- each key may have multiple values, in distinct scopes.
|
||||
- scoping may use three axes: configuration, project, and task.
|
||||
- a configuration is a kind of build, such as the main one (`Compile`) or
|
||||
|
|
@ -36,14 +36,14 @@ to know.
|
|||
per-task, or per-configuration.
|
||||
- the per-project axis also supports "entire build" scope.
|
||||
- scopes "fall back to" or delegate to more general scopes.
|
||||
- Basic vs. [[Full Build Definition]]
|
||||
- Basic vs. [[Full|Getting Started Full Def]]
|
||||
- put most of your settings in basic (`build.sbt`), but use the full
|
||||
build definition to
|
||||
[[define multiple subprojects|Multi-Project Builds]], and to factor out
|
||||
[[define multiple subprojects|Getting Started Multi-Project]], and to factor out
|
||||
common values, objects, and methods.
|
||||
- the build definition is an sbt project in its own right,
|
||||
rooted in the `project` directory.
|
||||
- [[Plugins|Using Plugins]] are extensions to the build definition
|
||||
- [[Plugins|Getting Started Using Plugins]] are extensions to the build definition
|
||||
- add plugins with the `addSbtPlugin` method in `project/build.sbt` (NOT
|
||||
`build.sbt` in the project's base directory).
|
||||
|
||||
|
|
@ -2,8 +2,8 @@
|
|||
|
||||
This page is part of a Getting Started series. Please read the earlier pages
|
||||
in the series first, in particular you need to understand
|
||||
[[build.sbt|Basic Build Definition]], [[Library Dependencies]], and
|
||||
[[Full Build Definition]] before reading this page.
|
||||
[[build.sbt|Getting Started Basic Def]], [[library dependencies|Getting Started Library Dependencies]], and
|
||||
[[full build definition|Getting Started Full Def]] before reading this page.
|
||||
|
||||
## What is a plugin?
|
||||
|
||||
|
|
@ -33,8 +33,8 @@ So that's how you do it... read on to understand what's going on.
|
|||
### How it works
|
||||
|
||||
Be sure you understand the
|
||||
[[recursive nature of sbt projects|Full Build Definition]] described
|
||||
earlier and how to add a [[managed dependency|Library Dependencies]].
|
||||
[[recursive nature of sbt projects|Getting Started Full Def]] described
|
||||
earlier and how to add a [[managed dependency|Getting Started Library Dependencies]].
|
||||
|
||||
#### Dependencies for the build definition
|
||||
|
||||
|
|
@ -110,7 +110,7 @@ def addSbtPlugin(dependency: ModuleID): Setting[Seq[ModuleID]] =
|
|||
libraryDependencies <+= (sbtVersion in update,scalaVersion) { (sbtV, scalaV) => sbtPluginExtra(dependency, sbtV, scalaV) }
|
||||
```
|
||||
|
||||
Remember from [[More About Settings]] that `<+=` combines `<<=` and `+=`, so
|
||||
Remember from [[more about settings|Getting Started More About Settings]] that `<+=` combines `<<=` and `+=`, so
|
||||
this builds a value based on other settings, and then appends it to
|
||||
`libraryDependencies`. The value is based on `sbtVersion in update` (sbt's
|
||||
version scoped to the `update` task) and `scalaVersion` (the version of
|
||||
|
|
@ -168,7 +168,7 @@ If a plugin defines settings in the `settings` field of a `Plugin` object,
|
|||
you don't have to do anything to add them.
|
||||
|
||||
However, plugins often avoid this because you could not control which
|
||||
projects in a [[multi-project build|Multi-Project Builds]] would use the plugin.
|
||||
projects in a [[multi-project build|Getting Started Multi-Project]] would use the plugin.
|
||||
|
||||
sbt provides a method called `seq` which adds a whole batch of settings at
|
||||
once. So if a plugin has something like this:
|
||||
|
|
@ -229,4 +229,4 @@ Some especially popular plugins are:
|
|||
|
||||
## Next
|
||||
|
||||
Move on to [[multi-project builds|Multi-Project Builds]].
|
||||
Move on to [[multi-project builds|Getting Started Multi-Project]].
|
||||
10
Home.md
10
Home.md
|
|
@ -2,8 +2,8 @@ sbt is a build tool for Scala and Java projects that aims to do the basics well.
|
|||
|
||||
## Features
|
||||
* Easy to set up for simple projects
|
||||
* [[Basic build definition|Basic Build Definition]] uses a Scala-based "domain-specific language" (DSL)
|
||||
* More advanced [[full build definitions|Full Build Definition]] and [[extensions|Custom Settings and Tasks]] use the full flexibility of unrestricted Scala code
|
||||
* [[Basic build definition|Getting Started Basic Def]] uses a Scala-based "domain-specific language" (DSL)
|
||||
* More advanced [[full build definitions|Getting Started Full Def]] and [[extensions|Getting Started Custom Settings]] use the full flexibility of unrestricted Scala code
|
||||
* Accurate incremental recompilation using information extracted from the compiler
|
||||
* Continuous compilation and testing with [[triggered execution|Triggered Execution]]
|
||||
* Packages and publishes jars
|
||||
|
|
@ -11,21 +11,21 @@ sbt is a build tool for Scala and Java projects that aims to do the basics well.
|
|||
* Supports mixed Scala/[[Java|Java Sources]] projects
|
||||
* Supports [[Testing|testing]] with ScalaCheck, specs, and ScalaTest (JUnit is supported by a plugin)
|
||||
* Starts the Scala REPL with project classes and dependencies on the classpath
|
||||
* [[Sub-project|Multi-Project Builds]] support (put multiple packages in one project)
|
||||
* [[Sub-project|Getting Started Multi-Project]] support (put multiple packages in one project)
|
||||
* [[External project|External Projects]] support (list a git repository as a dependency!)
|
||||
* Parallel task execution, including parallel test execution
|
||||
* [[Library management support|Library Management]]: inline declarations, external Ivy or Maven configuration files, or manual management
|
||||
|
||||
## Getting Started
|
||||
|
||||
To get started, start with [[Setup]], and continue through the other Getting
|
||||
To get started, start with [[Setup|Getting Started Setup]], and continue through the other Getting
|
||||
Started pages listed in the sidebar on the right. It's best to read in
|
||||
order, as later pages in the Getting Started series build on concepts
|
||||
introduced earlier.
|
||||
|
||||
_Please read the Getting Started pages._ You will save yourself a _lot_ of
|
||||
time if you have the right understanding of the big picture
|
||||
up-front. [[Start with setup|Setup]].
|
||||
up-front. [[Start with setup|Getting Started Setup]].
|
||||
|
||||
If you are familiar with 0.7.x, please see the
|
||||
[[migration page|Migrating from sbt 0.7.x to 0.10.x]]. Documentation for
|
||||
|
|
|
|||
4
Index.md
4
Index.md
|
|
@ -33,7 +33,7 @@
|
|||
# Index
|
||||
|
||||
This is an index of common methods, types, and values you might find in an sbt build definition.
|
||||
For command names, see [[Running]].
|
||||
For command names, see [[Running|Getting Started Running]].
|
||||
For available plugins, see [[sbt 0.10 plugins list]].
|
||||
|
||||
## Values and Types
|
||||
|
|
@ -128,4 +128,4 @@ The methods to combine processes start with `#` so that they share the same prec
|
|||
* `run`, `!`, `!!`, `!<`, `lines`, `lines_!` are different ways to start a process once it has been defined. The `lines` variants produce a `Stream[String]` to obtain the output lines.
|
||||
* `#<`, `#<<`, `#>` are used to get input for a process from a source or send the output of a process to a sink.
|
||||
* `#|` is used to pipe output from one process into the input of another.
|
||||
* `#||`, `#&&`, `###` sequence processes in different ways.
|
||||
* `#||`, `#&&`, `###` sequence processes in different ways.
|
||||
|
|
|
|||
|
|
@ -208,7 +208,7 @@ ivyXML :=
|
|||
### Ivy Home Directory
|
||||
|
||||
By default, sbt uses the standard Ivy home directory location `${user.home}/.ivy2/`.
|
||||
This can be configured machine-wide, for use by both the sbt launcher and by projects, by setting the system property `sbt.ivy.home` in the sbt startup script (described in [[Setup]]).
|
||||
This can be configured machine-wide, for use by both the sbt launcher and by projects, by setting the system property `sbt.ivy.home` in the sbt startup script (described in [[Setup|Getting Started Setup]]).
|
||||
|
||||
For example:
|
||||
|
||||
|
|
@ -313,4 +313,4 @@ Maven support is dependent on Ivy's support for Maven POMs.
|
|||
Known issues with this support:
|
||||
|
||||
* Specifying `relativePath` in the `parent` section of a POM will produce an error.
|
||||
* Ivy ignores repositories specified in the POM. A workaround is to specify repositories inline or in an Ivy `ivysettings.xml` file.
|
||||
* Ivy ignores repositories specified in the POM. A workaround is to specify repositories inline or in an Ivy `ivysettings.xml` file.
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ Or (as most users do) with a shell script like:
|
|||
|
||||
Note, in this script that I have renamed the `sbt-launch.jar` file with the version so that I can continue to use my 0.7.x version for projects that haven't been migrated. I called this script `sbt9`.
|
||||
|
||||
For more details see: [[Setup]].
|
||||
For more details see: [[Setup|Getting Started Setup]].
|
||||
|
||||
# Step 2: A technique for switching an existing project
|
||||
|
||||
|
|
@ -110,7 +110,7 @@ This does mean that existing solutions for sharing libraries with your favoured
|
|||
|
||||
## What are the commands I can use?
|
||||
|
||||
For a list of commands, run `help`. For details on a specific command, run `help <command>`. To view a list of tasks defined on the current project, run `tasks`. Alternatively, see the [[Running]] page for descriptions of common commands and tasks.
|
||||
For a list of commands, run `help`. For details on a specific command, run `help <command>`. To view a list of tasks defined on the current project, run `tasks`. Alternatively, see the [[Running|Getting Started Running]] page for descriptions of common commands and tasks.
|
||||
|
||||
If in doubt start by just trying the old command as it may just work. The built in TAB completion will also assist you, so you can just press TAB at the beginning of a line and see what you get.
|
||||
|
||||
|
|
|
|||
|
|
@ -274,7 +274,7 @@ ivyXML :=
|
|||
### Ivy Home Directory
|
||||
|
||||
By default, sbt uses the standard Ivy home directory location `${user.home}/.ivy2/`.
|
||||
This can be configured machine-wide, for use by both the sbt launcher and by projects, by setting the system property `sbt.ivy.home` in the sbt startup script (described in [[Setup]]).
|
||||
This can be configured machine-wide, for use by both the sbt launcher and by projects, by setting the system property `sbt.ivy.home` in the sbt startup script (described in [[Setup|Getting Started Setup]]).
|
||||
|
||||
For example:
|
||||
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
Nightly builds are currently being published to <http://repo.typesafe.com/typesafe/ivy-snapshots/>.
|
||||
|
||||
To use a nightly build, follow the instructions for normal [[Setup]], except:
|
||||
To use a nightly build, follow the instructions for normal [[Setup|Getting Started Setup]], except:
|
||||
|
||||
1. Download the launcher jar from one of the subdirectories of [sbt-launch]. They should be listed in chronological order, so the most recent one will be last.
|
||||
2. Call your script something like `sbt-nightly` to retain access to a stable `sbt` launcher.
|
||||
|
|
@ -14,4 +14,4 @@ Related to the third point, remember that an `sbt.version` setting in `<build-ba
|
|||
|
||||
A nightly launcher jar should be able to launch previous stable 0.11.x versions of sbt (it is a bug otherwise).
|
||||
|
||||
However, to reduce problems, it is recommended to not use a launcher jar for one nightly version to launch a different nightly version of sbt. That is, if you have launcher `0.11.1-20110828-110226`, only specify `0.11.0` and `0.11.1-20110828-110226` in a `project/build.properties` file.
|
||||
However, to reduce problems, it is recommended to not use a launcher jar for one nightly version to launch a different nightly version of sbt. That is, if you have launcher `0.11.1-20110828-110226`, only specify `0.11.0` and `0.11.1-20110828-110226` in a `project/build.properties` file.
|
||||
|
|
|
|||
|
|
@ -27,4 +27,4 @@ FIXME
|
|||
SBT downloads most of its own dependencies on an as-needed basis, so the startup jar is the only thing you'll need to fetch yourself.
|
||||
|
||||
## Further Reading and Resources
|
||||
See the [[Setup]] page of the wiki for more information.
|
||||
See the [[Setup|Getting Started Setup]] page of the wiki for more information.
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ This will create two scripts: `screpl` and `scalas`.
|
|||
|
||||
## Manual Setup
|
||||
|
||||
Duplicate your standard `sbt` script, which was set up according to [[Setup]], as `scalas` and `screpl` (or whatever names you like).
|
||||
Duplicate your standard `sbt` script, which was set up according to [[Setup|Getting Started Setup]], as `scalas` and `screpl` (or whatever names you like).
|
||||
|
||||
`scalas` is the script runner and its command line should look like:
|
||||
|
||||
|
|
@ -114,4 +114,4 @@ A repository argument looks like:
|
|||
"id at url"
|
||||
```
|
||||
|
||||
This syntax was a quick hack. Feel free to improve it. The relevant class is [IvyConsole].
|
||||
This syntax was a quick hack. Feel free to improve it. The relevant class is [IvyConsole].
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ Tasks that are available for main sources are generally available for test sourc
|
|||
* `test:run`
|
||||
* `test:run-main`
|
||||
|
||||
See [[Running]] for details on these tasks.
|
||||
See [[Running|Getting Started Running]] for details on these tasks.
|
||||
|
||||
# Output
|
||||
|
||||
|
|
|
|||
26
_Sidebar.md
26
_Sidebar.md
|
|
@ -1,18 +1,18 @@
|
|||
* [[Home]] - Overview of sbt
|
||||
* Getting Started
|
||||
* [[Setup]] - Install sbt
|
||||
* [[Hello World]] - Create a simple project
|
||||
* [[Directory Structure]] - Basic project layout
|
||||
* [[Running]] - The command line and interactive mode
|
||||
* [[Basic Build Definition]] - Understanding build.sbt settings
|
||||
* [[Scopes]] - Put settings in context
|
||||
* [[More About Settings]] - Settings based on other settings
|
||||
* [[Library Dependencies]] - Adding jars or managed dependencies
|
||||
* [[Full Build Definition]] - When build.sbt is not enough
|
||||
* [[Using Plugins]] - Adding plugins to the build
|
||||
* [[Multi-Project Builds]] - Adding sub-projects to the build
|
||||
* [[Custom Settings and Tasks]] - Intro to extending sbt
|
||||
* [[Summary]] - What you should know now
|
||||
* [[Setup|Getting Started Setup]] - Install sbt
|
||||
* [[Hello, World|Getting Started Hello]] - Create a simple project
|
||||
* [[Directory Layout|Getting Started Directories]] - Basic project layout
|
||||
* [[Running|Getting Started Running]] - The command line and interactive mode
|
||||
* [[Basic Build Definition|Getting Started Basic Def]] - Understanding build.sbt settings
|
||||
* [[Scopes|Getting Started Scopes]] - Put settings in context
|
||||
* [[More About Settings|Getting Started More About Settings]] - Settings based on other settings
|
||||
* [[Library Dependencies|Getting Started Library Dependencies]] - Adding jars or managed dependencies
|
||||
* [[Full Build Definition|Getting Started Full Def]] - When build.sbt is not enough
|
||||
* [[Using Plugins|Getting Started Using Plugins]] - Adding plugins to the build
|
||||
* [[Multi-Project Builds|Getting Started Multi-Project]] - Adding sub-projects to the build
|
||||
* [[Custom Settings and Tasks|Getting Started Custom Settings]] - Intro to extending sbt
|
||||
* [[Summary|Getting Started Summary]] - What you should know now
|
||||
* Help
|
||||
* [[Migrating from sbt 0.7.x to 0.10.x]]
|
||||
* [[Index]] - Look up common types, values, and methods
|
||||
|
|
|
|||
Loading…
Reference in New Issue