mirror of https://github.com/sbt/sbt.git
Docs: Add and use custom 🔑 role that links to the val in sxr/sbt/Keys.scala.
This commit is contained in:
Mark Harrah
parent
b8b6426cf9
commit
28a4bb3642
|
|
@ -65,7 +65,7 @@ optional dependencies in our artifact:
|
|||
pomIncludeRepository := { _ => false }
|
||||
|
||||
Next, the POM metadata that isn't generated by sbt must be added. This
|
||||
is done through the `pomExtra` configuration option:
|
||||
is done through the :key:`pomExtra` configuration option:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -96,7 +96,7 @@ the `scala-arm <http://jsuereth.com/scala-arm>`_ project.
|
|||
|
||||
*Note* that sbt will automatically inject `licenses` and `url` nodes
|
||||
if they are already present in your build file. Thus an alternative to
|
||||
the above `pomExtra` is to include the following entries:
|
||||
the above :key:`pomExtra` is to include the following entries:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -105,8 +105,8 @@ the above `pomExtra` is to include the following entries:
|
|||
homepage := Some(url("http://jsuereth.com/scala-arm"))
|
||||
|
||||
This might be advantageous if those keys are used also by other plugins
|
||||
(e.g. `ls`). You **cannot use both** the sbt `licenses` key and the
|
||||
`licenses` section in `pomExtra` at the same time, as this will
|
||||
(e.g. `ls`). You **cannot use both** the sbt :key:`licenses` key and the
|
||||
`licenses` section in :key:`pomExtra` at the same time, as this will
|
||||
produce duplicate entries in the final POM file, leading to a rejection
|
||||
in Sonatype's staging process.
|
||||
|
||||
|
|
@ -134,11 +134,11 @@ Ivy to use the credentials.*
|
|||
Finally - Publish
|
||||
-----------------
|
||||
|
||||
In sbt, run `publish-signed` and you should see something like the following:
|
||||
In sbt, run `publishSigned` and you should see something like the following:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
> publish-signed
|
||||
> publishSigned
|
||||
Please enter your PGP passphrase> ***********
|
||||
[info] Packaging /home/josh/projects/typesafe/scala-arm/target/scala-2.9.1/scala-arm_2.9.1-1.2.jar ...
|
||||
[info] Wrote /home/josh/projects/typesafe/scala-arm/target/scala-2.9.1/scala-arm_2.9.1-1.2.pom
|
||||
|
|
@ -206,7 +206,7 @@ settings:
|
|||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The `sbt-pgp plugin <http://scala-sbt.org/sbt-pgp>`_ allows you to
|
||||
sign and publish your artefacts by running `publish-signed` in sbt:
|
||||
sign and publish your artefacts by running `publishSigned` in sbt:
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
|
|
@ -46,9 +46,9 @@ Modifying default artifacts
|
|||
===========================
|
||||
|
||||
Each built-in artifact has several configurable settings in addition to
|
||||
`publishArtifact`. The basic ones are `artifact` (of type
|
||||
`SettingKey[Artifact]`), `mappings` (of type
|
||||
`TaskKey[(File,String)]`), and `artifactPath` (of type
|
||||
:key:`publishArtifact`. The basic ones are :key:`artifact` (of type
|
||||
`SettingKey[Artifact]`), :key:`mappings` (of type
|
||||
`TaskKey[(File,String)]`), and :key:`artifactPath` (of type
|
||||
`SettingKey[File]`). They are scoped by `(<config>, <task>)` as
|
||||
indicated in the previous section.
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ To modify the type of the main artifact, for example:
|
|||
previous.copy(`type` = "bundle")
|
||||
}
|
||||
|
||||
The generated artifact name is determined by the `artifactName`
|
||||
The generated artifact name is determined by the :key:`artifactName`
|
||||
setting. This setting is of type
|
||||
`(ScalaVersion, ModuleID, Artifact) => String`. The ScalaVersion
|
||||
argument provides the full Scala version String and the binary
|
||||
|
|
@ -69,7 +69,7 @@ compatible part of the version String. The String result is the name of
|
|||
the file to produce. The default implementation is
|
||||
`Artifact.artifactName _`. The function may be modified to produce
|
||||
different local names for artifacts without affecting the published
|
||||
name, which is determined by the `artifact` definition combined with
|
||||
name, which is determined by the :key:`artifact` definition combined with
|
||||
the repository pattern.
|
||||
|
||||
For example, to produce a minimal name without a classifier or cross
|
||||
|
|
@ -84,9 +84,9 @@ path:
|
|||
(Note that in practice you rarely want to drop the classifier.)
|
||||
|
||||
Finally, you can get the `(Artifact, File)` pair for the artifact by
|
||||
mapping the `packagedArtifact` task. Note that if you don't need the
|
||||
mapping the :key:`packagedArtifact` task. Note that if you don't need the
|
||||
`Artifact`, you can get just the File from the package task
|
||||
(`package`, `packageDoc`, or `packageSrc`). In both cases,
|
||||
(:key:`package`, :key:`packageDoc`, or :key:`packageSrc`). In both cases,
|
||||
mapping the task to get the file ensures that the artifact is generated
|
||||
first and so the file is guaranteed to be up-to-date.
|
||||
|
||||
|
|
|
|||
|
|
@ -48,10 +48,10 @@ Generated files
|
|||
~~~~~~~~~~~~~~~
|
||||
|
||||
Write any generated files to a subdirectory of the output directory,
|
||||
which is specified by the `target` setting. This makes it easy to
|
||||
which is specified by the :key:`target` setting. This makes it easy to
|
||||
clean up after a build and provides a single location to organize
|
||||
generated files. Any generated files that are specific to a Scala
|
||||
version should go in `crossTarget` for efficient cross-building.
|
||||
version should go in :key:`crossTarget` for efficient cross-building.
|
||||
|
||||
For generating sources and resources, see :doc:`/Howto/generatefiles`.
|
||||
|
||||
|
|
@ -59,7 +59,7 @@ Don't hard code
|
|||
~~~~~~~~~~~~~~~
|
||||
|
||||
Don't hard code constants, like the output directory `target/`. This
|
||||
is especially important for plugins. A user might change the `target`
|
||||
is especially important for plugins. A user might change the :key:`target`
|
||||
setting to point to `build/`, for example, and the plugin needs to
|
||||
respect that. Instead, use the setting, like:
|
||||
|
||||
|
|
@ -124,7 +124,7 @@ or construct the file from an absolute base:
|
|||
base / "A.scala"
|
||||
|
||||
This is related to the no hard coding best practice because the proper
|
||||
way involves referencing the `baseDirectory` setting. For example, the
|
||||
way involves referencing the :key:`baseDirectory` setting. For example, the
|
||||
following defines the myPath setting to be the `<base>/licenses/`
|
||||
directory.
|
||||
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ Classpaths, sources, and resources
|
|||
==================================
|
||||
|
||||
This page discusses how sbt builds up classpaths for different actions,
|
||||
like `compile`, `run`, and `test` and how to override or augment
|
||||
like :key:`compile`, :key:`run`, and :key:`test` and how to override or augment
|
||||
these classpaths.
|
||||
|
||||
Basics
|
||||
|
|
@ -74,8 +74,8 @@ To insert a named task, which is the better approach for plugins:
|
|||
The `task` method is used to refer to the actual task instead of the
|
||||
result of the task.
|
||||
|
||||
For resources, there are similar keys `resourceGenerators` and
|
||||
`resourceManaged`.
|
||||
For resources, there are similar keys :key:`resourceGenerators` and
|
||||
:key:`resourceManaged`.
|
||||
|
||||
Excluding source files by name
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -107,33 +107,33 @@ Keys
|
|||
|
||||
For classpaths, the relevant keys are:
|
||||
|
||||
- `unmanagedClasspath`
|
||||
- `managedClasspath`
|
||||
- `externalDependencyClasspath`
|
||||
- `internalDependencyClasspath`
|
||||
- :key:`unmanagedClasspath`
|
||||
- :key:`managedClasspath`
|
||||
- :key:`externalDependencyClasspath`
|
||||
- :key:`internalDependencyClasspath`
|
||||
|
||||
For sources:
|
||||
|
||||
- `unmanagedSources` These are by default built up from
|
||||
`unmanagedSourceDirectories`, which consists of `scalaSource`
|
||||
and `javaSource`.
|
||||
- `managedSources` These are generated sources.
|
||||
- `sources` Combines `managedSources` and `unmanagedSources`.
|
||||
- `sourceGenerators` These are tasks that generate source files.
|
||||
- :key:`unmanagedSources` These are by default built up from
|
||||
:key:`unmanagedSourceDirectories`, which consists of :key:`scalaSource`
|
||||
and :key:`javaSource`.
|
||||
- :key:`managedSources` These are generated sources.
|
||||
- :key:`sources` Combines :key:`managedSources` and :key:`unmanagedSources`.
|
||||
- :key:`sourceGenerators` These are tasks that generate source files.
|
||||
Typically, these tasks will put sources in the directory provided by
|
||||
`sourceManaged`.
|
||||
:key:`sourceManaged`.
|
||||
|
||||
For resources
|
||||
|
||||
- `unmanagedResources` These are by default built up from
|
||||
`unmanagedResourceDirectories`, which by default is
|
||||
`resourceDirectory`, excluding files matched by
|
||||
`defaultExcludes`.
|
||||
- `managedResources` By default, this is empty for standard
|
||||
- :key:`unmanagedResources` These are by default built up from
|
||||
:key:`unmanagedResourceDirectories`, which by default is
|
||||
:key:`resourceDirectory`, excluding files matched by
|
||||
:key:`defaultExcludes`.
|
||||
- :key:`managedResources` By default, this is empty for standard
|
||||
projects. sbt plugins will have a generated descriptor file here.
|
||||
- `resourceGenerators` These are tasks that generate resource files.
|
||||
- :key:`resourceGenerators` These are tasks that generate resource files.
|
||||
Typically, these tasks will put resources in the directory provided
|
||||
by `resourceManaged`.
|
||||
by :key:`resourceManaged`.
|
||||
|
||||
Use the :doc:`inspect command </Detailed-Topics/Inspecting-Settings>` for more details.
|
||||
|
||||
|
|
|
|||
|
|
@ -21,60 +21,60 @@ Notes on the command line
|
|||
these values can be shown using `show <task>` to run the task
|
||||
instead of just `<task>`.
|
||||
- In a multi-project build, execution dependencies and the
|
||||
`aggregate` setting control which tasks from which projects are
|
||||
:key:`aggregate` setting control which tasks from which projects are
|
||||
executed. See :doc:`multi-project builds </Getting-Started/Multi-Project>`.
|
||||
|
||||
Project-level tasks
|
||||
-------------------
|
||||
|
||||
- `clean` Deletes all generated files (the `target` directory).
|
||||
- `publishLocal` Publishes artifacts (such as jars) to the local Ivy
|
||||
- :key:`clean` Deletes all generated files (the :key:`target` directory).
|
||||
- :key:`publishLocal` Publishes artifacts (such as jars) to the local Ivy
|
||||
repository as described in :doc:`Publishing`.
|
||||
- `publish` Publishes artifacts (such as jars) to the repository
|
||||
defined by the `publishTo` setting, described in :doc:`Publishing`.
|
||||
- `update` Resolves and retrieves external dependencies as described
|
||||
- :key:`publish` Publishes artifacts (such as jars) to the repository
|
||||
defined by the :key:`publishTo` setting, described in :doc:`Publishing`.
|
||||
- :key:`update` Resolves and retrieves external dependencies as described
|
||||
in :doc:`library dependencies </Getting-Started/Library-Dependencies>`.
|
||||
|
||||
Configuration-level tasks
|
||||
-------------------------
|
||||
|
||||
Configuration-level tasks are tasks associated with a configuration. For
|
||||
example, `compile`, which is equivalent to `compile:compile`,
|
||||
example, :key:`compile`, which is equivalent to `compile:compile`,
|
||||
compiles the main source code (the `compile` configuration).
|
||||
`test:compile` compiles the test source code (test `test`
|
||||
configuration). Most tasks for the `compile` configuration have an
|
||||
equivalent in the `test` configuration that can be run using a
|
||||
`test:` prefix.
|
||||
|
||||
- `compile` Compiles the main sources (in the `src/main/scala`
|
||||
- :key:`compile` Compiles the main sources (in the `src/main/scala`
|
||||
directory). `test:compile` compiles test sources (in the
|
||||
`src/test/scala/` directory).
|
||||
- `console` Starts the Scala interpreter with a classpath including
|
||||
- :key:`console` Starts the Scala interpreter with a classpath including
|
||||
the compiled sources, all jars in the `lib` directory, and managed
|
||||
libraries. To return to sbt, type `:quit`, Ctrl+D (Unix), or Ctrl+Z
|
||||
(Windows). Similarly, `test:console` starts the interpreter with
|
||||
the test classes and classpath.
|
||||
- `consoleQuick` Starts the Scala interpreter with the project's
|
||||
- :key:`consoleQuick` Starts the Scala interpreter with the project's
|
||||
compile-time dependencies on the classpath. `test:consoleQuick`
|
||||
uses the test dependencies. This task differs from `console` in
|
||||
uses the test dependencies. This task differs from :key:`console` in
|
||||
that it does not force compilation of the current project's sources.
|
||||
- `consoleProject` Enters an interactive session with sbt and the
|
||||
- :key:`consoleProject` Enters an interactive session with sbt and the
|
||||
build definition on the classpath. The build definition and related
|
||||
values are bound to variables and common packages and values are
|
||||
imported. See the :doc:`consoleProject documentation <Console-Project>` for more information.
|
||||
- `doc` Generates API documentation for Scala source files in
|
||||
- :key:`doc` Generates API documentation for Scala source files in
|
||||
`src/main/scala` using scaladoc. `test:doc` generates API
|
||||
documentation for source files in `src/test/scala`.
|
||||
- `package` Creates a jar file containing the files in
|
||||
- :key:`package` Creates a jar file containing the files in
|
||||
`src/main/resources` and the classes compiled from
|
||||
`src/main/scala`. `test:package` creates a jar containing the
|
||||
`src/main/scala`. :key:`test:package` creates a jar containing the
|
||||
files in `src/test/resources` and the class compiled from
|
||||
`src/test/scala`.
|
||||
- `packageDoc` Creates a jar file containing API documentation
|
||||
- :key:`packageDoc` Creates a jar file containing API documentation
|
||||
generated from Scala source files in `src/main/scala`.
|
||||
`test:packageDoc` creates a jar containing API documentation for
|
||||
test sources files in `src/test/scala`.
|
||||
- `packageSrc`: Creates a jar file containing all main source files
|
||||
- :key:`packageSrc`: Creates a jar file containing all main source files
|
||||
and resources. The packaged paths are relative to `src/main/scala`
|
||||
and `src/main/resources`. Similarly, `test:packageSrc` operates
|
||||
on test source files and resources.
|
||||
|
|
@ -90,7 +90,7 @@ equivalent in the `test` configuration that can be run using a
|
|||
for details on the use of `System.exit` and
|
||||
multithreading (including GUIs) in code run by this action.
|
||||
`test:runMain` runs the specified main class in the test code.
|
||||
- `test` Runs all tests detected during test compilation. See
|
||||
- :key:`test` Runs all tests detected during test compilation. See
|
||||
:doc:`Testing` for details.
|
||||
- `testOnly <test>*` Runs the tests provided as arguments. `*`
|
||||
(will be) interpreted as a wildcard in the test name. See :doc:`Testing`
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ Compiler Plugin Support
|
|||
=======================
|
||||
|
||||
There is some special support for using compiler plugins. You can set
|
||||
`autoCompilerPlugins` to `true` to enable this functionality.
|
||||
:key:`autoCompilerPlugins` to `true` to enable this functionality.
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -18,14 +18,14 @@ for specifying `plugin` as the configuration for a dependency:
|
|||
|
||||
addCompilerPlugin("org.scala-tools.sxr" %% "sxr" % "0.3.0")
|
||||
|
||||
The `compile` and `testCompile` actions will use any compiler
|
||||
The :key:`compile` and :key:`testCompile` actions will use any compiler
|
||||
plugins found in the `lib` directory or in the `plugin`
|
||||
configuration. You are responsible for configuring the plugins as
|
||||
necessary. For example, Scala X-Ray requires the extra option:
|
||||
|
||||
::
|
||||
|
||||
// declare the main Scala source directory as the base directory
|
||||
// declare the main Scala source directory as the base directory
|
||||
scalacOptions :=
|
||||
scalacOptions.value :+ ("-Psxr:base-directory:" + (scalaSource in Compile).value.getAbsolutePath)
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ For example,
|
|||
|
||||
scalaVersion := "2.10.0"
|
||||
|
||||
This will retrieve Scala from the repositories configured via the `resolvers` setting.
|
||||
This will retrieve Scala from the repositories configured via the :key:`resolvers` setting.
|
||||
It will use this version for building your project: compiling, running, scaladoc, and the REPL.
|
||||
|
||||
Configuring the scala-library dependency
|
||||
|
|
@ -31,7 +31,7 @@ If you want to configure it differently than the default or you have a project w
|
|||
autoScalaLibrary := false
|
||||
|
||||
In order to compile Scala sources, the Scala library needs to be on the classpath.
|
||||
When `autoScalaLibrary` is true, the Scala library will be on all classpaths: test, runtime, and compile.
|
||||
When :key:`autoScalaLibrary` is true, the Scala library will be on all classpaths: test, runtime, and compile.
|
||||
Otherwise, you need to add it like any other dependency.
|
||||
For example, the following dependency definition uses Scala only for tests:
|
||||
|
||||
|
|
@ -51,7 +51,7 @@ For example, to depend on the Scala compiler,
|
|||
|
||||
libraryDependencies += "org.scala-lang" % "scala-compiler" % scalaVersion.value
|
||||
|
||||
Note that this is necessary regardless of the value of the `autoScalaLibrary` setting described in the previous section.
|
||||
Note that this is necessary regardless of the value of the :key:`autoScalaLibrary` setting described in the previous section.
|
||||
|
||||
Configuring Scala tool dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -59,7 +59,7 @@ Configuring Scala tool dependencies
|
|||
In order to compile Scala code, run scaladoc, and provide a Scala REPL, sbt needs the `scala-compiler` jar.
|
||||
This should not be a normal dependency of the project, so sbt adds a dependency on `scala-compiler` in the special, private `scala-tool` configuration.
|
||||
It may be desirable to have more control over this in some situations.
|
||||
Disable this automatic behavior with the `managedScalaInstance` key:
|
||||
Disable this automatic behavior with the :key:`managedScalaInstance` key:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -69,7 +69,7 @@ This will also disable the automatic dependency on `scala-library`.
|
|||
If you do not need the Scala compiler for anything (compiling, the REPL, scaladoc, etc...), you can stop here.
|
||||
sbt does not need an instance of Scala for your project in that case.
|
||||
Otherwise, sbt will still need access to the jars for the Scala compiler for compilation and other tasks.
|
||||
You can provide them by either declaring a dependency in the `scala-tool` configuration or by explicitly defining `scalaInstance`.
|
||||
You can provide them by either declaring a dependency in the `scala-tool` configuration or by explicitly defining :key:`scalaInstance`.
|
||||
|
||||
In the first case, add the `scala-tool` configuration and add a dependency on `scala-compiler` in this configuration.
|
||||
The organization is not important, but sbt needs the module name to be `scala-compiler` and `scala-library` in order to handle those jars appropriately.
|
||||
|
|
@ -91,7 +91,7 @@ For example,
|
|||
"org.scala-lang" % "scala-compiler" % scalaVersion.value % "scala-tool"
|
||||
)
|
||||
|
||||
In the second case, directly construct a value of type `ScalaInstance <../../api/sbt/ScalaInstance.html>`_, typically using a method in the `companion object <../../api/sbt/ScalaInstance$.html>`_, and assign it to `scalaInstance`.
|
||||
In the second case, directly construct a value of type `ScalaInstance <../../api/sbt/ScalaInstance.html>`_, typically using a method in the `companion object <../../api/sbt/ScalaInstance$.html>`_, and assign it to :key:`scalaInstance`.
|
||||
You will also need to add the `scala-library` jar to the classpath to compile and run Scala sources.
|
||||
For example,
|
||||
|
||||
|
|
@ -115,7 +115,7 @@ Using Scala from a local directory
|
|||
|
||||
The result of building Scala from source is a Scala home directory `<base>/build/pack/` that contains a subdirectory `lib/` containing the Scala library, compiler, and other jars.
|
||||
The same directory layout is obtained by downloading and extracting a Scala distribution.
|
||||
Such a Scala home directory may be used as the source for jars by setting `scalaHome`.
|
||||
Such a Scala home directory may be used as the source for jars by setting :key:`scalaHome`.
|
||||
For example,
|
||||
|
||||
::
|
||||
|
|
@ -130,7 +130,7 @@ In these cases, the artifacts for the resolved dependencies will be substituted
|
|||
Mixing with managed dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
As an example, consider adding a dependency on `scala-reflect` when `scalaHome` is configured:
|
||||
As an example, consider adding a dependency on `scala-reflect` when :key:`scalaHome` is configured:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -145,7 +145,7 @@ Using unmanaged dependencies only
|
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Instead of adding managed dependencies on Scala jars, you can directly add them.
|
||||
The `scalaInstance` task provides structured access to the Scala distribution.
|
||||
The :key:`scalaInstance` task provides structured access to the Scala distribution.
|
||||
For example, to add all jars in the Scala home `lib/` directory,
|
||||
|
||||
::
|
||||
|
|
@ -154,7 +154,7 @@ For example, to add all jars in the Scala home `lib/` directory,
|
|||
|
||||
unmanagedJars in Compile ++= scalaInstance.value.jars
|
||||
|
||||
To add only some jars, filter the jars from `scalaInstance` before adding them.
|
||||
To add only some jars, filter the jars from :key:`scalaInstance` before adding them.
|
||||
|
||||
sbt's Scala version
|
||||
===================
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Console Project
|
|||
Description
|
||||
===========
|
||||
|
||||
The `consoleProject` task starts the Scala interpreter with access to
|
||||
The :key:`consoleProject` task starts the Scala interpreter with access to
|
||||
your project definition and to `sbt`. Specifically, the interpreter is
|
||||
started up with these commands already executed:
|
||||
|
||||
|
|
@ -30,7 +30,7 @@ be included in the standard library in Scala 2.9):
|
|||
> "grep -r null src" #|| "echo null-free" !
|
||||
> uri("http://databinder.net/dispatch/About").toURL #> file("About.html") !
|
||||
|
||||
`consoleProject` can be useful for creating and modifying your build
|
||||
:key:`consoleProject` can be useful for creating and modifying your build
|
||||
in the same way that the Scala interpreter is normally used to explore
|
||||
writing code. Note that this gives you raw access to your build. Think
|
||||
about what you pass to `IO.delete`, for example.
|
||||
|
|
@ -98,7 +98,7 @@ Examples
|
|||
--------
|
||||
|
||||
Show the remaining commands to be executed in the build (more
|
||||
interesting if you invoke `consoleProject` like
|
||||
interesting if you invoke :key:`consoleProject` like
|
||||
`; consoleProject ; clean ; compile`):
|
||||
|
||||
.. code-block:: scala
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ Cross-Building a Project
|
|||
========================
|
||||
|
||||
Define the versions of Scala to build against in the
|
||||
`cross-scala-versions` setting. Versions of Scala 2.8.0 or later are
|
||||
:key:`crossScalaVersions` setting. Versions of Scala 2.8.0 or later are
|
||||
allowed. For example, in a `.sbt` build definition:
|
||||
|
||||
::
|
||||
|
|
|
|||
|
|
@ -10,14 +10,14 @@ the current work flow with dependency management in sbt follows.
|
|||
Background
|
||||
==========
|
||||
|
||||
`update` resolves dependencies according to the settings in a build
|
||||
file, such as `libraryDependencies` and `resolvers`. Other tasks use
|
||||
the output of `update` (an `UpdateReport`) to form various
|
||||
classpaths. Tasks that in turn use these classpaths, such as `compile`
|
||||
or `run`, thus indirectly depend on `update`. This means that before
|
||||
`compile` can run, the `update` task needs to run. However,
|
||||
resolving dependencies on every `compile` would be unnecessarily slow
|
||||
and so `update` must be particular about when it actually performs a
|
||||
:key:`update` resolves dependencies according to the settings in a build
|
||||
file, such as :key:`libraryDependencies` and :key:`resolvers`. Other tasks use
|
||||
the output of :key:`update` (an `UpdateReport`) to form various
|
||||
classpaths. Tasks that in turn use these classpaths, such as :key:`compile`
|
||||
or :key:`run`, thus indirectly depend on `update`. This means that before
|
||||
:key:`compile` can run, the :key:`update` task needs to run. However,
|
||||
resolving dependencies on every :key:`compile` would be unnecessarily slow
|
||||
and so :key:`update` must be particular about when it actually performs a
|
||||
resolution.
|
||||
|
||||
Caching and Configuration
|
||||
|
|
@ -30,34 +30,34 @@ Caching and Configuration
|
|||
or changing the version or other attributes of a dependency, will
|
||||
automatically cause resolution to be performed. Updates to locally
|
||||
published dependencies should be detected in sbt 0.12.1 and later and
|
||||
will force an `update`. Dependent tasks like `compile` and
|
||||
`run` will get updated classpaths.
|
||||
3. Directly running the `update` task (as opposed to a task that
|
||||
will force an :key:`update`. Dependent tasks like :key:`compile` and
|
||||
:key:`run` will get updated classpaths.
|
||||
3. Directly running the :key:`update` task (as opposed to a task that
|
||||
depends on it) will force resolution to run, whether or not
|
||||
configuration changed. This should be done in order to refresh remote
|
||||
SNAPSHOT dependencies.
|
||||
4. When `offline := true`, remote SNAPSHOTs will not be updated by a
|
||||
resolution, even an explicitly requested `update`. This should
|
||||
resolution, even an explicitly requested :key:`update`. This should
|
||||
effectively support working without a connection to remote
|
||||
repositories. Reproducible examples demonstrating otherwise are
|
||||
appreciated. Obviously, `update` must have successfully run before
|
||||
appreciated. Obviously, :key:`update` must have successfully run before
|
||||
going offline.
|
||||
5. Overriding all of the above, `skip in update := true` will tell sbt
|
||||
to never perform resolution. Note that this can cause dependent tasks
|
||||
to fail. For example, compilation may fail if jars have been deleted
|
||||
from the cache (and so needed classes are missing) or a dependency
|
||||
has been added (but will not be resolved because skip is true). Also,
|
||||
`update` itself will immediately fail if resolution has not been
|
||||
allowed to run since the last `clean`.
|
||||
:key:`update` itself will immediately fail if resolution has not been
|
||||
allowed to run since the last :key:`clean`.
|
||||
|
||||
General troubleshooting steps
|
||||
=============================
|
||||
|
||||
A. Run `update` explicitly. This will typically fix problems with out
|
||||
A. Run :key:`update` explicitly. This will typically fix problems with out
|
||||
of date SNAPSHOTs or locally published artifacts.
|
||||
|
||||
B. If a file cannot be
|
||||
found, look at the output of `update` to see where Ivy is looking for
|
||||
found, look at the output of :key:`update` to see where Ivy is looking for
|
||||
the file. This may help diagnose an incorrectly defined dependency or a
|
||||
dependency that is actually not present in a repository.
|
||||
|
||||
|
|
@ -66,7 +66,7 @@ C. `last update` contains more information about the most recent
|
|||
high, so you may want to use `lastGrep` (run `help lastGrep` for
|
||||
usage).
|
||||
|
||||
D. Run `clean` and then `update`. If this works, it could
|
||||
D. Run :key:`clean` and then :key:`update`. If this works, it could
|
||||
indicate a bug in sbt, but the problem would need to be reproduced in
|
||||
order to diagnose and fix it.
|
||||
|
||||
|
|
@ -74,7 +74,7 @@ E. Before deleting all of the Ivy cache,
|
|||
first try deleting files in `~/.ivy2/cache` related to problematic
|
||||
dependencies. For example, if there are problems with dependency
|
||||
`"org.example" % "demo" % "1.0"`, delete
|
||||
`~/.ivy2/cache/org.example/demo/1.0/` and retry `update`. This
|
||||
`~/.ivy2/cache/org.example/demo/1.0/` and retry :key:`update`. This
|
||||
avoids needing to redownload all dependencies.
|
||||
|
||||
F. Normal sbt usage
|
||||
|
|
@ -103,10 +103,10 @@ A. Configure offline behavior for all projects on a machine by putting
|
|||
`offline := true` in `~/.sbt/global.sbt`. A command that does this
|
||||
for the user would make a nice pull request. Perhaps the setting of
|
||||
offline should go into the output of `about` or should it be a warning
|
||||
in the output of `update` or both?
|
||||
in the output of :key:`update` or both?
|
||||
|
||||
B. The cache improvements in 0.12.1 address issues in the change detection
|
||||
for `update` so that it will correctly re-resolve automatically in more
|
||||
for :key:`update` so that it will correctly re-resolve automatically in more
|
||||
situations. A problem with an out of date cache can usually be attributed
|
||||
to a bug in that change detection if explicitly running `update` fixes
|
||||
the problem.
|
||||
|
|
@ -114,7 +114,7 @@ B. The cache improvements in 0.12.1 address issues in the change detection
|
|||
C. A common solution to dependency management problems in sbt has been to
|
||||
remove `~/.ivy2/cache`. Before doing this with 0.12.1, be sure to
|
||||
follow the steps in the troubleshooting section first. In particular,
|
||||
verify that a `clean` and an explicit `update` do not solve the
|
||||
verify that a :key:`clean` and an explicit :key:`update` do not solve the
|
||||
issue.
|
||||
|
||||
D. There is no need to mark SNAPSHOT dependencies as `changing()`
|
||||
|
|
|
|||
|
|
@ -2,32 +2,32 @@
|
|||
Forking
|
||||
=======
|
||||
|
||||
By default, the `run` task runs in the same JVM as sbt. Forking is
|
||||
By default, the :key:`run` task runs in the same JVM as sbt. Forking is
|
||||
required under :doc:`certain circumstances <Running-Project-Code>`, however.
|
||||
Or, you might want to fork Java processes when implementing new tasks.
|
||||
|
||||
By default, a forked process uses the same Java and Scala versions being
|
||||
used for the build and the working directory and JVM options of the
|
||||
current process. This page discusses how to enable and configure forking
|
||||
for both `run` and `test` tasks. Each kind of task may be configured
|
||||
for both :key:`run` and :key:`test` tasks. Each kind of task may be configured
|
||||
separately by scoping the relevant keys as explained below.
|
||||
|
||||
Enable forking
|
||||
==============
|
||||
|
||||
The `fork` setting controls whether forking is enabled (true) or not
|
||||
(false). It can be set in the `run` scope to only fork `run`
|
||||
commands or in the `test` scope to only fork `test` commands.
|
||||
The :key:`fork` setting controls whether forking is enabled (true) or not
|
||||
(false). It can be set in the :key:`run` scope to only fork :key:`run`
|
||||
commands or in the :key:`test` scope to only fork :key:`test` commands.
|
||||
|
||||
To fork all test tasks (`test`, `testOnly`, and `testQuick`) and
|
||||
run tasks (`run`, `runMain`, `test:run`, and `test:runMain`),
|
||||
To fork all test tasks (:key:`test`, :key:`testOnly`, and :key:`testQuick`) and
|
||||
run tasks (:key:`run`, :key:`runMain`, `test:run`, and `test:runMain`),
|
||||
|
||||
::
|
||||
|
||||
fork := true
|
||||
|
||||
To enable forking `run` tasks only, set `fork` to `true` in the
|
||||
`run` scope.
|
||||
To enable forking :key:`run` tasks only, set :key:`fork` to `true` in the
|
||||
:key:`run` scope.
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -40,11 +40,11 @@ To only fork `test:run` and `test:runMain`:
|
|||
fork in (Test,run) := true
|
||||
|
||||
Similarly, set `fork in (Compile,run) := true` to only fork the main
|
||||
`run` tasks. `run` and `runMain` share the same configuration and
|
||||
:key:`run` tasks. :key:`run` and :key:`runMain` share the same configuration and
|
||||
cannot be configured separately.
|
||||
|
||||
To enable forking all `test` tasks only, set `fork` to `true` in
|
||||
the `test` scope:
|
||||
To enable forking all :key:`test` tasks only, set :key:`fork` to `true` in
|
||||
the :key:`test` scope:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -77,7 +77,7 @@ Forked JVM options
|
|||
==================
|
||||
|
||||
To specify options to be provided to the forked JVM, set
|
||||
`javaOptions`:
|
||||
:key:`javaOptions`:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ tasks:
|
|||
|
||||
javaOptions in (Test,run) += "-Xmx8G"
|
||||
|
||||
or only affect the `test` tasks:
|
||||
or only affect the :key:`test` tasks:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -99,7 +99,7 @@ or only affect the `test` tasks:
|
|||
Java Home
|
||||
=========
|
||||
|
||||
Select the Java installation to use by setting the `javaHome`
|
||||
Select the Java installation to use by setting the :key:`javaHome`
|
||||
directory:
|
||||
|
||||
::
|
||||
|
|
@ -108,21 +108,21 @@ directory:
|
|||
|
||||
Note that if this is set globally, it also sets the Java installation
|
||||
used to compile Java sources. You can restrict it to running only by
|
||||
setting it in the `run` scope:
|
||||
setting it in the :key:`run` scope:
|
||||
|
||||
::
|
||||
|
||||
javaHome in run := file("/path/to/jre/")
|
||||
|
||||
As with the other settings, you can specify the configuration to affect
|
||||
only the main or test `run` tasks or just the `test` tasks.
|
||||
only the main or test :key:`run` tasks or just the :key:`test` tasks.
|
||||
|
||||
Configuring output
|
||||
==================
|
||||
|
||||
By default, forked output is sent to the Logger, with standard output
|
||||
logged at the `Info` level and standard error at the `Error` level.
|
||||
This can be configured with the `outputStrategy` setting, which is of
|
||||
This can be configured with the :key:`outputStrategy` setting, which is of
|
||||
type
|
||||
`OutputStrategy <../../api/sbt/OutputStrategy.html>`_.
|
||||
|
||||
|
|
@ -141,13 +141,13 @@ type
|
|||
outputStrategy := Some(BufferedOutput(log: Logger))
|
||||
|
||||
As with other settings, this can be configured individually for main or
|
||||
test `run` tasks or for `test` tasks.
|
||||
test :key:`run` tasks or for :key:`test` tasks.
|
||||
|
||||
Configuring Input
|
||||
=================
|
||||
|
||||
By default, the standard input of the sbt process is not forwarded to
|
||||
the forked process. To enable this, configure the `connectInput`
|
||||
the forked process. To enable this, configure the :key:`connectInput`
|
||||
setting:
|
||||
|
||||
::
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Settings that should be applied to all projects can go in :sublit:`|globalSbtFil
|
|||
(or any file in :sublit:`|globalBase|` with a `.sbt` extension).
|
||||
Plugins that are defined globally in :sublit:`|globalPluginsBase|` are
|
||||
available to these settings. For example, to change the default
|
||||
`shellPrompt` for your projects:
|
||||
:key:`shellPrompt` for your projects:
|
||||
|
||||
:sublit:`|globalSbtFile|`
|
||||
|
||||
|
|
@ -32,7 +32,7 @@ the dependency definitions. For example:
|
|||
|
||||
addSbtPlugin("org.example" % "plugin" % "1.0")
|
||||
|
||||
To change the default `shellPrompt` for every project using this
|
||||
To change the default :key:`shellPrompt` for every project using this
|
||||
approach, create a local plugin :sublit:`|globalShellPromptScala|`:
|
||||
|
||||
::
|
||||
|
|
@ -51,7 +51,7 @@ The :sublit:`|globalPluginsBase|` directory is a full project that is included a
|
|||
an external dependency of every plugin project. In practice, settings
|
||||
and code defined here effectively work as if they were defined in a
|
||||
project's `project/` directory. This means that :sublit:`|globalPluginsBase|` can
|
||||
be used to try out ideas for plugins such as shown in the `shellPrompt`
|
||||
be used to try out ideas for plugins such as shown in the :key:`shellPrompt`
|
||||
example.
|
||||
|
||||
.. |globalBase| replace:: ~/.sbt/|version|/
|
||||
|
|
|
|||
|
|
@ -50,10 +50,10 @@ in the build in `/home/user/sample/`:
|
|||
> root/compile:compile
|
||||
> {file:/home/user/sample/}root/compile:compile
|
||||
|
||||
As another example, `run` by itself refers to `compile:run` because
|
||||
there is no global `run` task and the first configuration searched,
|
||||
`compile`, defines a `run`. Therefore, to reference the `run` task
|
||||
for the `test` configuration, the configuration axis must be specified
|
||||
As another example, :key:`run` by itself refers to `compile:run` because
|
||||
there is no global :key:`run` task and the first configuration searched,
|
||||
:key:`compile`, defines a :key:`run`. Therefore, to reference the :key:`run` task
|
||||
for the `Test` configuration, the configuration axis must be specified
|
||||
like `test:run`. Some other examples that require the explicit
|
||||
`test:` axis:
|
||||
|
||||
|
|
@ -68,9 +68,9 @@ Task-specific Settings
|
|||
----------------------
|
||||
|
||||
Some settings are defined per-task. This is used when there are several
|
||||
related tasks, such as `package`, `packageSrc`, and
|
||||
`packageDoc`, in the same configuration (such as `compile` or
|
||||
`test`). For package tasks, their settings are the files to package,
|
||||
related tasks, such as :key:`package`, :key:`packageSrc`, and
|
||||
:key:`packageDoc`, in the same configuration (such as :key:`compile` or
|
||||
:key:`test`). For package tasks, their settings are the files to package,
|
||||
the options to use, and the output file to produce. Each package task
|
||||
should be able to have different values for these settings.
|
||||
|
||||
|
|
@ -119,9 +119,9 @@ is defined. For example,
|
|||
[info] {file:/home/user/sample/}root/*:libraryDependencies
|
||||
...
|
||||
|
||||
This shows that `libraryDependencies` has been defined on the current
|
||||
This shows that :key:`libraryDependencies` has been defined on the current
|
||||
project (`{file:/home/user/sample/}root`) in the global configuration
|
||||
(`*:`). For a task like `update`, the output looks like:
|
||||
(`*:`). For a task like :key:`update`, the output looks like:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -161,7 +161,7 @@ distinction is explained in more detail in the following sections.
|
|||
Requested Dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
As an example, we'll look at `console`:
|
||||
As an example, we'll look at :key:`console`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -179,15 +179,15 @@ As an example, we'll look at `console`:
|
|||
|
||||
...
|
||||
|
||||
This shows the inputs to the `console` task. We can see that it gets
|
||||
its classpath and options from `fullClasspath` and
|
||||
This shows the inputs to the :key:`console` task. We can see that it gets
|
||||
its classpath and options from :key:`fullClasspath` and
|
||||
`scalacOptions(for console)`. The information provided by the
|
||||
`inspect` command can thus assist in finding the right setting to
|
||||
change. The convention for keys, like `console` and
|
||||
`fullClasspath`, is that the Scala identifier is camel case, while
|
||||
change. The convention for keys, like :key:`console` and
|
||||
:key:`fullClasspath`, is that the Scala identifier is camel case, while
|
||||
the String representation is lowercase and separated by dashes. The
|
||||
Scala identifier for a configuration is uppercase to distinguish it from
|
||||
tasks like `compile` and `test`. For example, we can infer from the
|
||||
tasks like :key:`compile` and :key:`test`. For example, we can infer from the
|
||||
previous example how to add code to be run when the Scala interpreter
|
||||
starts up:
|
||||
|
||||
|
|
@ -199,13 +199,13 @@ starts up:
|
|||
import mypackage._
|
||||
...
|
||||
|
||||
`inspect` showed that `console` used the setting
|
||||
`inspect` showed that :key:`console` used the setting
|
||||
`compile:console::initialCommands`. Translating the
|
||||
`initialCommands` string to the Scala identifier gives us
|
||||
`initialCommands`. `compile` indicates that this is for the main
|
||||
:key:`initialCommands` string to the Scala identifier gives us
|
||||
:key:`initialCommands`. :key:`compile` indicates that this is for the main
|
||||
sources. `console::` indicates that the setting is specific to
|
||||
`console`. Because of this, we can set the initial commands on the
|
||||
`console` task without affecting the `consoleQuick` task, for
|
||||
:key:`console`. Because of this, we can set the initial commands on the
|
||||
:key:`console` task without affecting the :key:`consoleQuick` task, for
|
||||
example.
|
||||
|
||||
Actual Dependencies
|
||||
|
|
@ -242,10 +242,10 @@ For `initialCommands`, we see that it comes from the global scope
|
|||
|
||||
compile:console::initialCommands
|
||||
|
||||
we know that we can set `initialCommands` as generally as the global
|
||||
scope, as specific as the current project's `console` task scope, or
|
||||
we know that we can set :key:`initialCommands` as generally as the global
|
||||
scope, as specific as the current project's :key:`console` task scope, or
|
||||
anything in between. This means that we can, for example, set
|
||||
`initialCommands` for the whole project and will affect `console`:
|
||||
:key:`initialCommands` for the whole project and will affect :key:`console`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -268,9 +268,9 @@ looking at the reverse dependencies output of `inspect actual`:
|
|||
[info] *:consoleProject
|
||||
...
|
||||
|
||||
We now know that by setting `initialCommands` on the whole project,
|
||||
We now know that by setting :key:`initialCommands` on the whole project,
|
||||
we affect all console tasks in all configurations in that project. If we
|
||||
didn't want the initial commands to apply for `consoleProject`, which
|
||||
didn't want the initial commands to apply for :key:`consoleProject`, which
|
||||
doesn't have our project's classpath available, we could use the more
|
||||
specific task axis:
|
||||
|
||||
|
|
@ -299,7 +299,7 @@ section of the `inspect` command. The Delegates section shows the
|
|||
order in which scopes are searched when a value is not defined for the
|
||||
requested key.
|
||||
|
||||
As an example, consider the initial commands for `console` again:
|
||||
As an example, consider the initial commands for :key:`console` again:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
|
|||
|
|
@ -9,12 +9,12 @@ class files.
|
|||
Usage
|
||||
=====
|
||||
|
||||
- `compile` will compile the sources under `src/main/java` by
|
||||
- :key:`compile` will compile the sources under `src/main/java` by
|
||||
default.
|
||||
- `testCompile` will compile the sources under `src/test/java` by
|
||||
- :key:`testCompile` will compile the sources under `src/test/java` by
|
||||
default.
|
||||
|
||||
Pass options to the Java compiler by setting `javacOptions`:
|
||||
Pass options to the Java compiler by setting :key:`javacOptions`:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -28,7 +28,7 @@ sbt. Multi-element options, such as `-source 1.5`, are specified like:
|
|||
javacOptions ++= Seq("-source", "1.5")
|
||||
|
||||
You can specify the order in which Scala and Java sources are built with
|
||||
the `compileOrder` setting. Possible values are from the
|
||||
the :key:`compileOrder` setting. Possible values are from the
|
||||
`CompileOrder` enumeration: `Mixed`, `JavaThenScala`, and
|
||||
`ScalaThenJava`. If you have circular dependencies between Scala and
|
||||
Java sources, you need the default, `Mixed`, which passes both Java
|
||||
|
|
@ -63,7 +63,7 @@ compile will always provide full checking, however.
|
|||
By default, sbt includes `src/main/scala` and `src/main/java` in its
|
||||
list of unmanaged source directories. For Java-only projects, the
|
||||
unnecessary Scala directories can be ignored by modifying
|
||||
`unmanagedSourceDirectories`:
|
||||
:key:`unmanagedSourceDirectories`:
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ project definition are required to use this method unless you would like
|
|||
to change the location of the directory you store the jars in.
|
||||
|
||||
To change the directory jars are stored in, change the
|
||||
`unmanagedBase` setting in your project definition. For example, to
|
||||
:key:`unmanagedBase` setting in your project definition. For example, to
|
||||
use `custom_lib/`:
|
||||
|
||||
::
|
||||
|
|
@ -38,7 +38,7 @@ use `custom_lib/`:
|
|||
unmanagedBase := baseDirectory.value / "custom_lib"
|
||||
|
||||
If you want more control and flexibility, override the
|
||||
`unmanagedJars` task, which ultimately provides the manual
|
||||
:key:`unmanagedJars` task, which ultimately provides the manual
|
||||
dependencies to sbt. The default implementation is roughly:
|
||||
|
||||
::
|
||||
|
|
@ -161,12 +161,12 @@ See :doc:`Resolvers` for details on defining other types of repositories.
|
|||
Override default resolvers
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`resolvers` configures additional, inline user resolvers. By default,
|
||||
:key:`resolvers` configures additional, inline user resolvers. By default,
|
||||
`sbt` combines these resolvers with default repositories (Maven
|
||||
Central and the local Ivy repository) to form `externalResolvers`. To
|
||||
have more control over repositories, set `externalResolvers`
|
||||
Central and the local Ivy repository) to form :key:`externalResolvers`. To
|
||||
have more control over repositories, set :key:`externalResolvers`
|
||||
directly. To only specify repositories in addition to the usual
|
||||
defaults, configure `resolvers`.
|
||||
defaults, configure :key:`resolvers`.
|
||||
|
||||
For example, to use the Sonatype OSS Snapshots repository in addition to
|
||||
the default repositories,
|
||||
|
|
@ -257,9 +257,9 @@ For multiple classifiers, use multiple `classifier` calls:
|
|||
"org.lwjgl.lwjgl" % "lwjgl-platform" % lwjglVersion classifier "natives-windows" classifier "natives-linux" classifier "natives-osx"
|
||||
|
||||
To obtain particular classifiers for all dependencies transitively, run
|
||||
the `updateClassifiers` task. By default, this resolves all artifacts
|
||||
the :key:`updateClassifiers` task. By default, this resolves all artifacts
|
||||
with the `sources` or `javadoc` classifier. Select the classifiers
|
||||
to obtain by configuring the `transitiveClassifiers` setting. For
|
||||
to obtain by configuring the :key:`transitiveClassifiers` setting. For
|
||||
example, to only retrieve sources:
|
||||
|
||||
::
|
||||
|
|
@ -300,8 +300,8 @@ Download Sources
|
|||
~~~~~~~~~~~~~~~~
|
||||
|
||||
Downloading source and API documentation jars is usually handled by an
|
||||
IDE plugin. These plugins use the `updateClassifiers` and
|
||||
`updateSbtClassifiers` tasks, which produce an :doc:`Update-Report`
|
||||
IDE plugin. These plugins use the :key:`updateClassifiers` and
|
||||
:key:`updateSbtClassifiers` tasks, which produce an :doc:`Update-Report`
|
||||
referencing these jars.
|
||||
|
||||
To have sbt download the dependency's sources without using an IDE
|
||||
|
|
@ -407,7 +407,7 @@ Conflict Management
|
|||
|
||||
The conflict manager decides what to do when dependency resolution brings in different versions of the same library.
|
||||
By default, the latest revision is selected.
|
||||
This can be changed by setting `conflictManager`, which has type `ConflictManager <../../api/sbt/ConflictManager.html>`_.
|
||||
This can be changed by setting :key:`conflictManager`, which has type `ConflictManager <../../api/sbt/ConflictManager.html>`_.
|
||||
See the `Ivy documentation <http://ant.apache.org/ivy/history/latest-milestone/settings/conflict-managers.html>`_ for details on the different conflict managers.
|
||||
For example, to specify that no conflicts are allowed,
|
||||
|
||||
|
|
@ -547,16 +547,16 @@ your dependency definition:
|
|||
|
||||
libraryDependencies += "org.scalatest" % "scalatest" % "1.2" % "test->compile"
|
||||
|
||||
This says that your project's `test` configuration uses
|
||||
`ScalaTest`'s `compile` configuration. See the `Ivy
|
||||
This says that your project's `"test"` configuration uses
|
||||
`ScalaTest`'s `"compile"` configuration. See the `Ivy
|
||||
documentation <http://ant.apache.org/ivy/history/2.3.0-rc1/tutorial/conf.html>`_
|
||||
for more advanced mappings. Most projects published to Maven
|
||||
repositories will use the `compile` configuration.
|
||||
repositories will use the `"compile"` configuration.
|
||||
|
||||
A useful application of configurations is to group dependencies that are
|
||||
not used on normal classpaths. For example, your project might use a
|
||||
`"js"` configuration to automatically download jQuery and then include
|
||||
it in your jar by modifying `resources`. For example:
|
||||
it in your jar by modifying :key:`resources`. For example:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -571,8 +571,8 @@ makes it private to the project so that it is not used for publishing.
|
|||
See :doc:`/Detailed-Topics/Update-Report` for more information on selecting managed
|
||||
artifacts.
|
||||
|
||||
A configuration without a mapping (no `"->"`) is mapped to `default`
|
||||
or `compile`. The `->` is only needed when mapping to a different
|
||||
A configuration without a mapping (no `"->"`) is mapped to `"default"`
|
||||
or `"compile"`. The `->` is only needed when mapping to a different
|
||||
configuration than those. The ScalaTest dependency above can then be
|
||||
shortened to:
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
Local Scala
|
||||
===========
|
||||
|
||||
To use a locally built Scala version, define the `scalaHome` setting,
|
||||
To use a locally built Scala version, define the :key:`scalaHome` setting,
|
||||
which is of type `Option[File]`. This Scala version will only be used
|
||||
for the build and not for sbt, which will still use the version it was
|
||||
compiled against.
|
||||
|
|
@ -13,7 +13,7 @@ Example:
|
|||
|
||||
scalaHome := Some(file("/path/to/scala"))
|
||||
|
||||
Using a local Scala version will override the `scalaVersion` setting
|
||||
Using a local Scala version will override the :key:`scalaVersion` setting
|
||||
and will not work with :doc:`cross building <Cross-Build>`.
|
||||
|
||||
sbt reuses the class loader for the local Scala version. If you
|
||||
|
|
|
|||
|
|
@ -142,7 +142,7 @@ For example, the `main` Project definition above would now look like:
|
|||
|
||||
|
||||
You may wish to disable publishing the macro implementation.
|
||||
This is done by overriding `publish` and `publishLocal` to do nothing:
|
||||
This is done by overriding :key:`publish` and :key:`publishLocal` to do nothing:
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
Mapping Files
|
||||
=============
|
||||
|
||||
Tasks like `package`, `packageSrc`, and `packageDoc` accept
|
||||
Tasks like :key:`package`, :key:`packageSrc`, and :key:`packageDoc` accept
|
||||
mappings of type `Seq[(File, String)]` from an input file to the path
|
||||
to use in the resulting artifact (jar). Similarly, tasks that copy files
|
||||
accept mappings of type `Seq[(File, File)]` from an input file to the
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ Why move to |version|?
|
|||
`project/build/MyProject.scala` was.
|
||||
3. No more `lib_managed` directory, reducing disk usage and avoiding
|
||||
backup and version control hassles.
|
||||
4. `update` is now much faster and it's invoked automatically by sbt.
|
||||
4. :key:`update` is now much faster and it's invoked automatically by sbt.
|
||||
5. Terser output. (Yet you can ask for more details if something goes
|
||||
wrong.)
|
||||
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ concurrency beyond the usual ordering declarations. There are two parts
|
|||
to these restrictions.
|
||||
|
||||
1. A task is tagged in order to classify its purpose and resource
|
||||
utilization. For example, the `compile` task may be tagged as
|
||||
utilization. For example, the :key:`compile` task may be tagged as
|
||||
`Tags.Compile` and `Tags.CPU`.
|
||||
2. A list of rules restrict the tasks that may execute concurrently. For
|
||||
example, `Tags.limit(Tags.CPU, 4)` would allow up to four
|
||||
|
|
@ -95,7 +95,7 @@ this weight is an integer, but it may be a floating point in the future.
|
|||
Task: `tag` and `tagw`. The first method, `tag`, fixes the weight
|
||||
to be 1 for the tags provided to it as arguments. The second method,
|
||||
`tagw`, accepts pairs of tags and weights. For example, the following
|
||||
associates the `CPU` and `Compile` tags with the `compile` task
|
||||
associates the `CPU` and `Compile` tags with the :key:`compile` task
|
||||
(with a weight of 1).
|
||||
|
||||
::
|
||||
|
|
@ -116,7 +116,7 @@ Different weights may be specified by passing tag/weight pairs to
|
|||
Defining Restrictions
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Once tasks are tagged, the `concurrentRestrictions` setting sets
|
||||
Once tasks are tagged, the :key:`concurrentRestrictions` setting sets
|
||||
restrictions on the tasks that may be concurrently executed based on the
|
||||
weighted tags of those tasks. This is necessarily a global set of rules,
|
||||
so it must be scoped `in Global`. For example,
|
||||
|
|
@ -223,12 +223,12 @@ The built-in resource tags are:
|
|||
|
||||
The tasks that are currently tagged by default are:
|
||||
|
||||
- `compile`: `Compile`, `CPU`
|
||||
- `test`: `Test`
|
||||
- `update`: `Update`, `Network`
|
||||
- `publish`, `publishLocal`: `Publish`, `Network`
|
||||
- :key:`compile` : `Compile`, `CPU`
|
||||
- :key:`test` : `Test`
|
||||
- :key:`update` : `Update`, `Network`
|
||||
- :key:`publish`, :key:`publishLocal` : `Publish`, `Network`
|
||||
|
||||
Of additional note is that the default `test` task will propagate its
|
||||
Of additional note is that the default :key:`test` task will propagate its
|
||||
tags to each child task created for each test class.
|
||||
|
||||
The default rules provide the same behavior as previous versions of sbt:
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ Relative files should only be used when defining the base directory of a
|
|||
val root = Project("root", file("."))
|
||||
|
||||
Elsewhere, files should be absolute or be built up from an absolute base
|
||||
`File`. The `baseDirectory` setting defines the base directory of
|
||||
`File`. The :key:`baseDirectory` setting defines the base directory of
|
||||
the build or project depending on the scope.
|
||||
|
||||
For example, the following setting sets the unmanaged library directory
|
||||
|
|
|
|||
|
|
@ -7,19 +7,19 @@ uploading a descriptor, such as an Ivy file or Maven POM, and artifacts,
|
|||
such as a jar or war, to a repository so that other projects can specify
|
||||
your project as a dependency.
|
||||
|
||||
The `publish` action is used to publish your project to a remote
|
||||
The :key:`publish` action is used to publish your project to a remote
|
||||
repository. To use publishing, you need to specify the repository to
|
||||
publish to and the credentials to use. Once these are set up, you can
|
||||
run `publish`.
|
||||
run :key:`publish`.
|
||||
|
||||
The `publishLocal` action is used to publish your project to a local
|
||||
The :key:`publishLocal` action is used to publish your project to a local
|
||||
Ivy repository. You can then use this project from other projects on the
|
||||
same machine.
|
||||
|
||||
Define the repository
|
||||
---------------------
|
||||
|
||||
To specify the repository, assign a repository to `publishTo` and
|
||||
To specify the repository, assign a repository to :key:`publishTo` and
|
||||
optionally set the publishing style. For example, to upload to Nexus:
|
||||
|
||||
::
|
||||
|
|
@ -44,7 +44,7 @@ If you're using Maven repositories you will also have to select the
|
|||
right repository depending on your artifacts: SNAPSHOT versions go to
|
||||
the /snapshot repository while other versions go to the /releases
|
||||
repository. Doing this selection can be done by using the value of the
|
||||
`version` SettingKey:
|
||||
:key:`version` SettingKey:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -100,10 +100,10 @@ for details.
|
|||
Modifying the generated POM
|
||||
---------------------------
|
||||
|
||||
When `publishMavenStyle` is `true`, a POM is generated by the
|
||||
`makePom` action and published to the repository instead of an Ivy
|
||||
When :key:`publishMavenStyle` is `true`, a POM is generated by the
|
||||
:key:`makePom` action and published to the repository instead of an Ivy
|
||||
file. This POM file may be altered by changing a few settings. Set
|
||||
`pomExtra` to provide XML (`scala.xml.NodeSeq`) to insert directly
|
||||
:key:`pomExtra` to provide XML (`scala.xml.NodeSeq`) to insert directly
|
||||
into the generated pom. For example:
|
||||
|
||||
::
|
||||
|
|
@ -117,8 +117,8 @@ into the generated pom. For example:
|
|||
</license>
|
||||
</licenses>
|
||||
|
||||
`makePom` adds to the POM any Maven-style repositories you have
|
||||
declared. You can filter these by modifying `pomRepositoryFilter`,
|
||||
:key:`makePom` adds to the POM any Maven-style repositories you have
|
||||
declared. You can filter these by modifying :key:`pomRepositoryFilter`,
|
||||
which by default excludes local repositories. To instead only include
|
||||
local repositories:
|
||||
|
||||
|
|
@ -128,7 +128,7 @@ local repositories:
|
|||
repo.root.startsWith("file:")
|
||||
}
|
||||
|
||||
There is also a `pomPostProcess` setting that can be used to
|
||||
There is also a :key:`pomPostProcess` setting that can be used to
|
||||
manipulate the final XML before it is written. It's type is
|
||||
`Node => Node`.
|
||||
|
||||
|
|
@ -141,7 +141,7 @@ manipulate the final XML before it is written. It's type is
|
|||
Publishing Locally
|
||||
------------------
|
||||
|
||||
The `publishLocal` command will publish to the local Ivy repository.
|
||||
The :key:`publishLocal` command will publish to the local Ivy repository.
|
||||
By default, this is in `${user.home}/.ivy2/local`. Other projects on
|
||||
the same machine can then list the project as a dependency. For example,
|
||||
if the SBT project you are publishing has configuration parameters like:
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
Running Project Code
|
||||
====================
|
||||
|
||||
The `run` and `console` actions provide a means for running user
|
||||
The :key:`run` and :key:`console` actions provide a means for running user
|
||||
code in the same virtual machine as sbt. This page describes the
|
||||
problems with doing so, how sbt handles these problems, what types of
|
||||
code can use this feature, and what types of code must use a :doc:`forked jvm <Forking>`.
|
||||
|
|
@ -15,7 +15,7 @@ System.exit
|
|||
-----------
|
||||
|
||||
User code can call `System.exit`, which normally shuts down the JVM.
|
||||
Because the `run` and `console` actions run inside the same JVM as
|
||||
Because the :key:`run` and :key:`console` actions run inside the same JVM as
|
||||
sbt, this also ends the build and requires restarting sbt.
|
||||
|
||||
Threads
|
||||
|
|
@ -47,7 +47,7 @@ User code is run with a custom `SecurityManager` that throws a custom
|
|||
`SecurityException` when `System.exit` is called. This exception is
|
||||
caught by sbt. sbt then disposes of all top-level windows, interrupts
|
||||
(not stops) all user-created threads, and handles the exit code. If the
|
||||
exit code is nonzero, `run` and `console` complete unsuccessfully.
|
||||
exit code is nonzero, :key:`run` and :key:`console` complete unsuccessfully.
|
||||
If the exit code is zero, they complete normally.
|
||||
|
||||
Threads
|
||||
|
|
@ -70,8 +70,8 @@ thread(s).
|
|||
User Code
|
||||
=========
|
||||
|
||||
Given the above, when can user code be run with the `run` and
|
||||
`console` actions?
|
||||
Given the above, when can user code be run with the :key:`run` and
|
||||
:key:`console` actions?
|
||||
|
||||
The user code cannot rely on shutdown hooks and at least one of the
|
||||
following situations must apply for user code to run in the same JVM:
|
||||
|
|
|
|||
|
|
@ -96,7 +96,7 @@ Application
|
|||
As an example, consider generating a zip file containing the binary jar,
|
||||
source jar, and documentation jar for your project. First, determine
|
||||
what tasks produce the jars. In this case, the input tasks are
|
||||
`packageBin`, `packageSrc`, and `packageDoc` in the main
|
||||
:key:`packageBin`, :key:`packageSrc`, and :key:`packageDoc` in the main
|
||||
`Compile` scope. The result of each of these tasks is the File for the
|
||||
jar that they generated. Our zip file task is defined by mapping these
|
||||
package tasks and including their outputs in a zip file. As good
|
||||
|
|
|
|||
|
|
@ -136,7 +136,7 @@ Task Scope
|
|||
~~~~~~~~~~
|
||||
|
||||
As with settings, tasks can be defined in a specific scope. For example,
|
||||
there are separate `compile` tasks for the `compile` and `test`
|
||||
there are separate :key:`compile` tasks for the `compile` and `test`
|
||||
scopes. The scope of a task is defined the same as for a setting. In the
|
||||
following example, `test:sampleTask` uses the result of
|
||||
`compile:intTask`.
|
||||
|
|
@ -252,7 +252,7 @@ Example
|
|||
-------
|
||||
|
||||
A common scenario is getting the sources for all subprojects for processing all at once, such as passing them to scaladoc.
|
||||
The task that we want to obtain values for is `sources` and we want to get the values in all non-root projects and in the `Compile` configuration.
|
||||
The task that we want to obtain values for is :key:`sources` and we want to get the values in all non-root projects and in the `Compile` configuration.
|
||||
This looks like:
|
||||
|
||||
::
|
||||
|
|
@ -384,13 +384,13 @@ The target of `all` is any task or setting, including anonymous ones.
|
|||
This means it is possible to get multiple values at once without defining a new task or setting in each scope.
|
||||
A common use case is to pair each value obtained with the project, configuration, or full scope it came from.
|
||||
|
||||
`resolvedScoped`
|
||||
:key:`resolvedScoped`
|
||||
Provides the full enclosing `ScopedKey` (which is a `Scope` + `AttributeKey[_]`)
|
||||
`thisProject`
|
||||
:key:`thisProject`
|
||||
Provides the `Project` associated with this scope (undefined at the global and build levels)
|
||||
`thisProjectRef`
|
||||
:key:`thisProjectRef`
|
||||
Provides the `ProjectRef` for the context (undefined at the global and build levels)
|
||||
`configuration`
|
||||
:key:`configuration`
|
||||
Provides the `Configuration` for the context (undefined for the global configuration)
|
||||
|
||||
For example, the following defines a task that prints non-Compile configurations that define
|
||||
|
|
@ -403,7 +403,7 @@ a fairly contrived example):
|
|||
lazy val filter: ScopeFilter = ScopeFilter(
|
||||
inProjects(ThisProject),
|
||||
inAnyConfiguration -- inConfigurations(Compile)
|
||||
)
|
||||
)
|
||||
|
||||
// Define a task that provides the name of the current configuration
|
||||
// and the set of sbt plugins defined in the configuration
|
||||
|
|
@ -434,7 +434,7 @@ This allows controlling the verbosity of stack traces and logging individually f
|
|||
as recalling the last logging for a task.
|
||||
Tasks also have access to their own persisted binary or text data.
|
||||
|
||||
To use Streams, get the value of the `streams` task. This is a
|
||||
To use Streams, get the value of the :key:`streams` task. This is a
|
||||
special task that provides an instance of
|
||||
`TaskStreams <../../api/sbt/std/TaskStreams.html>`_
|
||||
for the defining task. This type provides access to named binary and
|
||||
|
|
@ -468,7 +468,7 @@ To obtain the last logging output from a task, use the `last` command:
|
|||
[info] Hello!
|
||||
|
||||
The verbosity with which logging is persisted is controlled using the
|
||||
`persistLogLevel` and `persistTraceLevel` settings. The `last`
|
||||
:key:`persistLogLevel` and :key:`persistTraceLevel` settings. The `last`
|
||||
command displays what was logged according to these levels. The levels
|
||||
do not affect already logged information.
|
||||
|
||||
|
|
|
|||
|
|
@ -34,8 +34,8 @@ to use your library.
|
|||
|
||||
With the library dependency defined, you can then add test sources in
|
||||
the locations listed above and compile and run tests. The tasks for
|
||||
running tests are `test` and `testOnly`. The `test` task accepts
|
||||
no command line arguments and runs all tests:
|
||||
running tests are :key:`test` and :key:`testOnly`. The :key:`test` task
|
||||
accepts no command line arguments and runs all tests:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -44,7 +44,7 @@ no command line arguments and runs all tests:
|
|||
testOnly
|
||||
---------
|
||||
|
||||
The `testOnly` task accepts a whitespace separated list of test names
|
||||
The :key:`testOnly` task accepts a whitespace separated list of test names
|
||||
to run. For example:
|
||||
|
||||
.. code-block:: console
|
||||
|
|
@ -60,7 +60,7 @@ It supports wildcards as well:
|
|||
testQuick
|
||||
----------
|
||||
|
||||
The `testQuick` task, like `testOnly`, allows to filter the tests
|
||||
The :key:`testQuick` task, like :key:`testOnly`, allows to filter the tests
|
||||
to run to specific tests or wildcards using the same syntax to indicate
|
||||
the filters. In addition to the explicit filter, only the tests that
|
||||
satisfy one of the following conditions are run:
|
||||
|
|
@ -77,7 +77,7 @@ Tab completion is provided for test names based on the results of the
|
|||
last `test:compile`. This means that a new sources aren't available
|
||||
for tab completion until they are compiled and deleted sources won't be
|
||||
removed from tab completion until a recompile. A new test source can
|
||||
still be manually written out and run using `testOnly`.
|
||||
still be manually written out and run using :key:`testOnly`.
|
||||
|
||||
Other tasks
|
||||
-----------
|
||||
|
|
@ -98,7 +98,7 @@ Output
|
|||
======
|
||||
|
||||
By default, logging is buffered for each test source file until all
|
||||
tests for that file complete. This can be disabled with:
|
||||
tests for that file complete. This can be disabled by setting :key:`logBuffered`:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -111,7 +111,7 @@ Test Framework Arguments
|
|||
------------------------
|
||||
|
||||
Arguments to the test framework may be provided on the command line to
|
||||
the `testOnly` tasks following a `--` separator. For example:
|
||||
the :key:`testOnly` tasks following a `--` separator. For example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -162,10 +162,11 @@ Disable Parallel Execution of Tests
|
|||
|
||||
By default, sbt runs all tasks in parallel. Because each test is mapped
|
||||
to a task, tests are also run in parallel by default. To make tests
|
||||
within a given project execute serially:
|
||||
within a given project execute serially: ::
|
||||
|
||||
`scala parallelExecution in Test := false` `Test` can be replaced
|
||||
with `IntegrationTest` to only execute integration tests serially.
|
||||
parallelExecution in Test := false
|
||||
|
||||
`Test` can be replaced with `IntegrationTest` to only execute integration tests serially.
|
||||
Note that tests from different projects may still execute concurrently.
|
||||
|
||||
Filter classes
|
||||
|
|
@ -190,7 +191,7 @@ The setting:
|
|||
specifies that all tests will be executed in a single external JVM. See
|
||||
:doc:`Forking` for configuring standard options for forking. More control
|
||||
over how tests are assigned to JVMs and what options to pass to those is
|
||||
available with `testGrouping` key. For example:
|
||||
available with :key:`testGrouping` key. For example:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -426,7 +427,7 @@ using:
|
|||
|
||||
parallelExecution in Serial := false
|
||||
|
||||
The tests to run in parallel would be run with `test` and the ones to
|
||||
The tests to run in parallel would be run with :key:`test` and the ones to
|
||||
run in serial would be run with `serial:test`.
|
||||
|
||||
JUnit
|
||||
|
|
@ -473,14 +474,14 @@ Using Extensions
|
|||
|
||||
To use your extensions in a project definition:
|
||||
|
||||
Modify the `testFrameworks` setting to reference your test framework:
|
||||
Modify the :key:`testFrameworks` setting to reference your test framework:
|
||||
|
||||
::
|
||||
|
||||
testFrameworks += new TestFramework("custom.framework.ClassName")
|
||||
|
||||
Specify the test reporters you want to use by overriding the
|
||||
`testListeners` method in your project definition.
|
||||
:key:`testListeners` setting in your project definition.
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
|
|
@ -4,17 +4,17 @@ Triggered Execution
|
|||
|
||||
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 `watchSources` and `pollInterval` are
|
||||
This triggered execution is configured by the :key:`watch` setting, but
|
||||
typically the basic settings :key:`watchSources` and :key:`pollInterval` are
|
||||
modified.
|
||||
|
||||
- `watchSources` defines the files for a single project that are
|
||||
- :key:`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
|
||||
- :key:`watchTransitiveSources` then combines the :key:`watchSources` for
|
||||
the current project and all execution and classpath dependencies (see
|
||||
:doc:`Full Configuration </Getting-Started/Full-Def>` for details on interProject dependencies).
|
||||
- `pollInterval` selects the interval between polling for changes in
|
||||
- :key:`pollInterval` selects the interval between polling for changes in
|
||||
milliseconds. The default value is `500 ms`.
|
||||
|
||||
Some example usages are described below.
|
||||
|
|
@ -38,7 +38,7 @@ One use is for test driven development, as suggested by Erick on the
|
|||
mailing list.
|
||||
|
||||
The following will poll for changes to your source code (main or test)
|
||||
and run `testOnly` for the specified test.
|
||||
and run :key:`testOnly` for the specified test.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -51,8 +51,8 @@ Occasionally, you may need to trigger the execution of multiple
|
|||
commands. You can use semicolons to separate the commands to be
|
||||
triggered.
|
||||
|
||||
The following will poll for source changes and run `clean` and
|
||||
`test`.
|
||||
The following will poll for source changes and run :key:`clean` and
|
||||
:key:`test`.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
|
|||
|
|
@ -211,7 +211,7 @@ compile it and then change the `Test.scala` file so it looks like::
|
|||
def b: String = "abc"
|
||||
}
|
||||
|
||||
and run `compile` task again. Now if you run `last compile` you should see
|
||||
and run :key:`compile` task again. Now if you run `last compile` you should see
|
||||
the following lines in the debugging log
|
||||
|
||||
.. code-block:: none
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
Update Report
|
||||
=============
|
||||
|
||||
`update` and related tasks produce a value of type
|
||||
:key:`update` and related tasks produce a value of type
|
||||
`sbt.UpdateReport <../../api/sbt/UpdateReport.html>`_
|
||||
This data structure provides information about the resolved
|
||||
configurations, modules, and artifacts. At the top level,
|
||||
|
|
@ -12,9 +12,9 @@ each resolved configuration. A `ConfigurationReport` supplies reports
|
|||
configuration. Finally, a `ModuleReport` lists each successfully
|
||||
retrieved `Artifact` and the `File` it was retrieved to as well as
|
||||
the `Artifact`\ s that couldn't be downloaded. This missing
|
||||
`Arifact` list is always empty for `update`, which will fail if it is
|
||||
non-empty. However, it may be non-empty for `updateClassifiers` and
|
||||
`updateSbtClassifers`.
|
||||
`Arifact` list is always empty for :key:`update`, which will fail if it is
|
||||
non-empty. However, it may be non-empty for :key:`updateClassifiers` and
|
||||
:key:`updateSbtClassifers`.
|
||||
|
||||
Filtering a Report and Getting Artifacts
|
||||
========================================
|
||||
|
|
|
|||
|
|
@ -228,11 +228,11 @@ Relevant API documentation for custom transformers:
|
|||
Manipulating Project Dependencies in Settings
|
||||
=============================================
|
||||
|
||||
The `buildDependencies` setting, in the Global scope, defines the
|
||||
The :key:`buildDependencies` setting, in the Global scope, defines the
|
||||
aggregation and classpath dependencies between projects. By default,
|
||||
this information comes from the dependencies defined by `Project`
|
||||
instances by the `aggregate` and `dependsOn` methods. Because
|
||||
`buildDependencies` is a setting and is used everywhere dependencies
|
||||
:key:`buildDependencies` is a setting and is used everywhere dependencies
|
||||
need to be known (once all projects are loaded), plugins and build
|
||||
definitions can transform it to manipulate inter-project dependencies at
|
||||
setting evaluation time. The only requirement is that no new projects
|
||||
|
|
@ -244,7 +244,7 @@ Build or referenced as the argument to `Project.aggregate` or
|
|||
The BuildDependencies type
|
||||
--------------------------
|
||||
|
||||
The type of the `buildDependencies` setting is
|
||||
The type of the :key:`buildDependencies` setting is
|
||||
`BuildDependencies </api/sbt/BuildDependencies.html>`_.
|
||||
`BuildDependencies` provides mappings from a project to its aggregate
|
||||
or classpath dependencies. For classpath dependencies, a dependency has
|
||||
|
|
@ -286,6 +286,6 @@ like a local directory.
|
|||
|
||||
It is not limited to such basic translations, however. The configuration
|
||||
a dependency is defined in may be modified and dependencies may be added
|
||||
or removed. Modifying `buildDependencies` can be combined with
|
||||
modifying `libraryDependencies` to convert binary dependencies to and
|
||||
or removed. Modifying :key:`buildDependencies` can be combined with
|
||||
modifying :key:`libraryDependencies` to convert binary dependencies to and
|
||||
from source dependencies, for example.
|
||||
|
|
|
|||
|
|
@ -219,7 +219,7 @@ For getting the test classpath of a specific project, use this key:
|
|||
Using State in a task
|
||||
---------------------
|
||||
|
||||
To access the current State from a task, use `state` task as an input.
|
||||
To access the current State from a task, use the :key:`state` task as an input.
|
||||
For example,
|
||||
|
||||
::
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ Where possible, reuse them in your plugin. For instance, don't define:
|
|||
|
||||
val sourceFiles = settingKey[Seq[File]]("Some source files")
|
||||
|
||||
Instead, simply reuse sbt's existing `sources` key.
|
||||
Instead, simply reuse sbt's existing :key:`sources` key.
|
||||
|
||||
Avoid namespace clashes
|
||||
-----------------------
|
||||
|
|
@ -259,7 +259,7 @@ Global settings should *not* be placed into a `build.sbt` file.
|
|||
|
||||
When overriding global settings, care should be taken to ensure previous
|
||||
settings from other plugins are not ignored. e.g. when creating a new
|
||||
`onLoad` handler, ensure that the previous `onLoad` handler is not
|
||||
:key:`onLoad` handler, ensure that the previous :key:`onLoad` handler is not
|
||||
removed.
|
||||
|
||||
::
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ markdown processing task. A plugin can define a sequence of sbt Settings
|
|||
that are automatically added to all projects or that are explicitly
|
||||
declared for selected projects. For example, a plugin might add a
|
||||
`proguard` task and associated (overridable) settings.
|
||||
Also, :doc:`Commands` can be added with the `commands` setting
|
||||
Also, :doc:`Commands` can be added with the :key:`commands` setting
|
||||
|
||||
The :doc:`Plugins-Best-Practices` page describes the
|
||||
currently evolving guidelines to writing sbt plugins. See also the
|
||||
|
|
@ -132,7 +132,7 @@ We can change to the plugins project in `project/` using
|
|||
|
||||
Then, we can add dependencies like usual and save them to
|
||||
`project/plugins.sbt`. It is useful, but not required, to run
|
||||
`update` to verify that the dependencies are correct.
|
||||
:key:`update` to verify that the dependencies are correct.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -167,7 +167,7 @@ If sbt is running, run `reload`.
|
|||
|
||||
Note that this approach can be useful used when developing a plugin.
|
||||
A project that uses the plugin will rebuild the plugin on `reload`.
|
||||
This saves the intermediate steps of `publishLocal` and `update`.
|
||||
This saves the intermediate steps of :key:`publishLocal` and :key:`update`.
|
||||
It can also be used to work with the development version of a plugin from its repository.
|
||||
|
||||
It is recommended to explicitly specify the commit or tag by appending it to the repository as a fragment:
|
||||
|
|
@ -358,7 +358,7 @@ In addition:
|
|||
3. sbt will rebuild the plugin and use it for the project.
|
||||
Additionally, the plugin will be available in other projects on
|
||||
the machine without recompiling again. This approach skips the
|
||||
overhead of `publishLocal` and cleaning the plugins directory
|
||||
overhead of :key:`publishLocal` and cleaning the plugins directory
|
||||
of the project using the plugin.
|
||||
|
||||
These are all consequences of :sublit:`|globalPluginsBase|` being a standard
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ build.sbt file:
|
|||
|
||||
Then, put the following examples in source files
|
||||
`SettingsExample.scala` and `SettingsUsage.scala`. Finally, run sbt
|
||||
and enter the REPL using `console`. To see the output described below,
|
||||
and enter the REPL using :key:`console`. To see the output described below,
|
||||
enter `SettingsUsage`.
|
||||
|
||||
Example Settings System
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ After examining a project and processing any build definition files, sbt
|
|||
will end up with an immutable map (set of key-value pairs) describing
|
||||
the build.
|
||||
|
||||
For example, one key is `name` and it maps to a string value, the name
|
||||
For example, one key is :key:`name` and it maps to a string value, the name
|
||||
of your project.
|
||||
|
||||
*Build definition files do not affect sbt's map directly.*
|
||||
|
|
@ -86,7 +86,7 @@ expressions may be interspersed with `val`s, `lazy val`s, and `def`s,
|
|||
but top-level `object`s and classes are not allowed in `build.sbt`.
|
||||
Those should go in the `project/` directory as full Scala source files.
|
||||
|
||||
On the left, `name`, `version`, and `scalaVersion` are *keys*. A
|
||||
On the left, :key:`name`, :key:`version`, and :key:`scalaVersion` are *keys*. A
|
||||
key is an instance of `SettingKey[T]`, `TaskKey[T]`, or
|
||||
`InputKey[T]` where `T` is the expected value type. The kinds of key
|
||||
are explained more below.
|
||||
|
|
@ -101,10 +101,10 @@ could use a Java-like syntax to call the method:
|
|||
But Scala allows `name := "hello"` instead (in Scala, any method can
|
||||
use either syntax).
|
||||
|
||||
The `:=` method on key `name` returns a `Setting`, specifically a
|
||||
`Setting[String]`. `String` also appears in the type of `name`
|
||||
The `:=` method on key :key:`name` returns a `Setting`, specifically a
|
||||
`Setting[String]`. `String` also appears in the type of :key:`name`
|
||||
itself, which is `SettingKey[String]`. In this case, the returned
|
||||
`Setting[String]` is a transformation to add or replace the `name`
|
||||
`Setting[String]` is a transformation to add or replace the :key:`name`
|
||||
key in sbt's map, giving it the value `"hello"`.
|
||||
|
||||
If you use the wrong value type, the build definition will not compile:
|
||||
|
|
@ -155,7 +155,7 @@ Built-in Keys
|
|||
The built-in keys are just fields in an object called
|
||||
`Keys <../../sxr/sbt/Keys.scala.html>`_. A
|
||||
`build.sbt` implicitly has an `import sbt.Keys._`, so
|
||||
`sbt.Keys.name` can be referred to as `name`.
|
||||
`sbt.Keys.name` can be referred to as :key:`name`.
|
||||
|
||||
Custom Keys
|
||||
~~~~~~~~~~~
|
||||
|
|
@ -180,18 +180,18 @@ Task v. Setting keys
|
|||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A `TaskKey[T]` is said to define a *task*. Tasks are operations such
|
||||
as `compile` or `package`. They may return `Unit` (`Unit` is
|
||||
as :key:`compile` or :key:`package`. They may return `Unit` (`Unit` is
|
||||
Scala for `void`), or they may return a value related to the task, for
|
||||
example `package` is a `TaskKey[File]` and its value is the jar file
|
||||
example :key:`package` is a `TaskKey[File]` and its value is the jar file
|
||||
it creates.
|
||||
|
||||
Each time you start a task execution, for example by typing `compile`
|
||||
Each time you start a task execution, for example by typing :key:`compile`
|
||||
at the interactive sbt prompt, sbt will re-run any tasks involved
|
||||
exactly once.
|
||||
|
||||
sbt's map describing the project can keep around a fixed string value
|
||||
for a setting such as `name`, but it has to keep around some
|
||||
executable code for a task such as `compile` -- even if that
|
||||
for a setting such as :key:`name`, but it has to keep around some
|
||||
executable code for a task such as :key:`compile` -- even if that
|
||||
executable code eventually returns a string, it has to be re-run every
|
||||
time.
|
||||
|
||||
|
|
@ -235,8 +235,8 @@ Keys in sbt interactive mode
|
|||
----------------------------
|
||||
|
||||
In sbt's interactive mode, you can type the name of any task to execute
|
||||
that task. This is why typing `compile` runs the compile task.
|
||||
`compile` is a task key.
|
||||
that task. This is why typing :key:`compile` runs the compile task.
|
||||
:key:`compile` is a task key.
|
||||
|
||||
If you type the name of a setting key rather than a task key, the value
|
||||
of the setting key will be displayed. Typing a task key name executes
|
||||
|
|
@ -283,7 +283,7 @@ add managed dependencies, which will look like this in `build.sbt`:
|
|||
This is how you add a managed dependency on the Apache Derby library,
|
||||
version 10.4.1.3.
|
||||
|
||||
The `libraryDependencies` key involves two complexities: `+=` rather
|
||||
The :key:`libraryDependencies` key involves two complexities: `+=` rather
|
||||
than `:=`, and the `%` method. `+=` appends to the key's old value
|
||||
rather than replacing it, this is explained in
|
||||
:doc:`more about settings </Getting-Started/More-About-Settings>`.
|
||||
|
|
|
|||
|
|
@ -26,14 +26,14 @@ You can place test jars such as
|
|||
`specs <http://code.google.com/p/specs/>`_, and
|
||||
`ScalaTest <http://www.scalatest.org/>`_ in `lib` as well.
|
||||
|
||||
Dependencies in `lib` go on all the classpaths (for `compile`,
|
||||
`test`, `run`, and `console`). If you wanted to change the
|
||||
Dependencies in `lib` go on all the classpaths (for :key:`compile`,
|
||||
:key:`test`, :key:`run`, and :key:`console`). If you wanted to change the
|
||||
classpath for just one of those, you would adjust
|
||||
`dependencyClasspath in Compile` or `dependencyClasspath in Runtime`
|
||||
for example.
|
||||
|
||||
There's nothing to add to `build.sbt` to use unmanaged dependencies,
|
||||
though you could change the `unmanagedBase` key if you'd like to use
|
||||
though you could change the :key:`unmanagedBase` key if you'd like to use
|
||||
a different directory rather than `lib`.
|
||||
|
||||
To use `custom_lib` instead of `lib`:
|
||||
|
|
@ -42,14 +42,14 @@ To use `custom_lib` instead of `lib`:
|
|||
|
||||
unmanagedBase := baseDirectory.value / "custom_lib"
|
||||
|
||||
`baseDirectory` is the project's root directory, so here you're
|
||||
changing `unmanagedBase` depending on `baseDirectory` using the
|
||||
:key:`baseDirectory` is the project's root directory, so here you're
|
||||
changing :key:`unmanagedBase` depending on :key:`baseDirectory` using the
|
||||
special `value` method as explained in :doc:`more about settings <More-About-Settings>`.
|
||||
|
||||
There's also an `unmanagedJars` task which lists the jars from the
|
||||
`unmanagedBase` directory. If you wanted to use multiple directories
|
||||
There's also an :key:`unmanagedJars` task which lists the jars from the
|
||||
:key:`unmanagedBase` directory. If you wanted to use multiple directories
|
||||
or do something else complex, you might need to replace the whole
|
||||
`unmanagedJars` task with one that does something else.
|
||||
:key:`unmanagedJars` task with one that does something else.
|
||||
|
||||
Managed Dependencies
|
||||
--------------------
|
||||
|
|
@ -62,7 +62,7 @@ The `libraryDependencies` key
|
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Most of the time, you can simply list your dependencies in the setting
|
||||
`libraryDependencies`. It's also possible to write a Maven POM file or
|
||||
:key:`libraryDependencies`. It's also possible to write a Maven POM file or
|
||||
Ivy configuration file to externally configure your dependencies, and
|
||||
have sbt use those external configuration files. You can learn more
|
||||
about that :ref:`here <external-maven-ivy>`.
|
||||
|
|
@ -80,14 +80,14 @@ or like this, where `configuration` is also a string:
|
|||
|
||||
libraryDependencies += groupID % artifactID % revision % configuration
|
||||
|
||||
`libraryDependencies` is declared in `Keys <../../sxr/sbt/Keys.scala.html#sbt.Keys.libraryDependencies>`_ like this:
|
||||
:key:`libraryDependencies` is declared in `Keys <../../sxr/sbt/Keys.scala.html#sbt.Keys.libraryDependencies>`_ like this:
|
||||
|
||||
::
|
||||
|
||||
val libraryDependencies = settingKey[Seq[ModuleID]]("Declares managed dependencies.")
|
||||
|
||||
The `%` methods create `ModuleID` objects from strings, then you add
|
||||
those `ModuleID` to `libraryDependencies`.
|
||||
those `ModuleID` to :key:`libraryDependencies`.
|
||||
|
||||
Of course, sbt (via Ivy) has to know where to download the module. If
|
||||
your module is in one of the default repositories sbt comes with, this
|
||||
|
|
@ -97,10 +97,10 @@ will just work. For example, Apache Derby is in a default repository:
|
|||
|
||||
libraryDependencies += "org.apache.derby" % "derby" % "10.4.1.3"
|
||||
|
||||
If you type that in `build.sbt` and then `update`, sbt should
|
||||
If you type that in `build.sbt` and then :key:`update`, sbt should
|
||||
download Derby to `~/.ivy2/cache/org.apache.derby/`. (By the way,
|
||||
`update` is a dependency of `compile` so there's no need to manually
|
||||
type `update` most of the time.)
|
||||
:key:`update` is a dependency of :key:`compile` so there's no need to manually
|
||||
type :key:`update` most of the time.)
|
||||
|
||||
Of course, you can also use `++=` to add a list of dependencies all at
|
||||
once:
|
||||
|
|
@ -112,7 +112,7 @@ once:
|
|||
groupID % otherID % otherRevision
|
||||
)
|
||||
|
||||
In rare cases you might find reasons to use `:=` with `libraryDependencies` as well.
|
||||
In rare cases you might find reasons to use `:=` with :key:`libraryDependencies` as well.
|
||||
|
||||
Getting the right Scala version with `%%`
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
|
@ -127,7 +127,7 @@ artifact name. This is just a shortcut. You could write this without the
|
|||
|
||||
libraryDependencies += "org.scala-tools" % "scala-stm_2.9.1" % "0.3"
|
||||
|
||||
Assuming the `scalaVersion` for your build is `2.9.1`, the following
|
||||
Assuming the :key:`scalaVersion` for your build is `2.9.1`, the following
|
||||
is identical:
|
||||
|
||||
::
|
||||
|
|
@ -177,7 +177,7 @@ For example:
|
|||
|
||||
resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
|
||||
|
||||
The `resolvers` key is defined in
|
||||
The :key:`resolvers` key is defined in
|
||||
`Keys <../../sxr/sbt/Keys.scala.html#sbt.Keys.resolvers>`_ like
|
||||
this:
|
||||
|
||||
|
|
@ -199,14 +199,14 @@ See :doc:`/Detailed-Topics/Resolvers` for details on defining other types of rep
|
|||
Overriding default resolvers
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`resolvers` does not contain the default resolvers; only additional
|
||||
:key:`resolvers` does not contain the default resolvers; only additional
|
||||
ones added by your build definition.
|
||||
|
||||
`sbt` combines `resolvers` with some default repositories to form
|
||||
`externalResolvers`.
|
||||
`sbt` combines :key:`resolvers` with some default repositories to form
|
||||
:key:`externalResolvers`.
|
||||
|
||||
Therefore, to change or remove the default resolvers, you would need to
|
||||
override `externalResolvers` instead of `resolvers`.
|
||||
override :key:`externalResolvers` instead of :key:`resolvers`.
|
||||
|
||||
.. _gsg-ivy-configurations:
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ Different settings transform the map in different ways.
|
|||
The `Setting` which `:=` creates puts a fixed, constant value in the
|
||||
new, transformed map. For example, if you transform a map with the
|
||||
setting `name := "hello"` the new map has the string `"hello"`
|
||||
stored under the key `name`.
|
||||
stored under the key :key:`name`.
|
||||
|
||||
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
|
||||
|
|
@ -94,7 +94,7 @@ Or, set the name to the name of the project's directory:
|
|||
// name the project after the directory it's inside
|
||||
name := baseDirectory.value.getName
|
||||
|
||||
This transforms the value of `baseDirectory` using the standard `getName` method of `java.io.File`.
|
||||
This transforms the value of :key:`baseDirectory` using the standard `getName` method of `java.io.File`.
|
||||
|
||||
Using multiple inputs is similar. For example,
|
||||
|
||||
|
|
@ -107,8 +107,8 @@ This sets the name in terms of its previous value as well as the organization an
|
|||
Settings with dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In the setting `name := baseDirectory.value.getName`, `name` will have
|
||||
a *dependency* on `baseDirectory`. If you place the above in
|
||||
In the setting `name := baseDirectory.value.getName`, :key:`name` will have
|
||||
a *dependency* on :key:`baseDirectory`. If you place the above in
|
||||
`build.sbt` and run the sbt interactive console, then type
|
||||
`inspect name`, you should see (in part):
|
||||
|
||||
|
|
@ -122,11 +122,11 @@ Remember that some settings describe tasks, so this approach also
|
|||
creates dependencies between tasks.
|
||||
|
||||
For example, if you `inspect compile` you'll see it depends on another
|
||||
key `compileInputs`, and if you inspect `compileInputs` it in turn
|
||||
key :key:`compileInputs`, and if you inspect :key:`compileInputs` it in turn
|
||||
depends on other keys. Keep following the dependency chains and magic
|
||||
happens. When you type `compile` sbt automatically performs an
|
||||
`update`, for example. It Just Works because the values required as
|
||||
inputs to the `compile` computation require sbt to do the `update`
|
||||
happens. When you type :key:`compile` sbt automatically performs an
|
||||
:key:`update`, for example. It Just Works because the values required as
|
||||
inputs to the :key:`compile` computation require sbt to do the :key:`update`
|
||||
computation first.
|
||||
|
||||
In this way, all build dependencies in sbt are *automatic* rather than
|
||||
|
|
@ -161,10 +161,10 @@ Take these two keys (from `Keys <../../sxr/sbt/Keys.scala.html>`_):
|
|||
val scalacOptions = taskKey[Seq[String]]("Options for the Scala compiler.")
|
||||
val checksums = settingKey[Seq[String]]("The list of checksums to generate and to verify for dependencies.")
|
||||
|
||||
(`scalacOptions` and `checksums` have nothing to do with each other,
|
||||
(:key:`scalacOptions` and :key:`checksums` have nothing to do with each other,
|
||||
they are just two keys with the same value type, where one is a task.)
|
||||
|
||||
It is possible to compile a `build.sbt` that aliases `scalacOptions` to `checksums`, but not the other way.
|
||||
It is possible to compile a `build.sbt` that aliases :key:`scalacOptions` to :key:`checksums`, but not the other way.
|
||||
For example, this is allowed:
|
||||
|
||||
::
|
||||
|
|
@ -189,7 +189,7 @@ Appending with dependencies: `+=` and `++=`
|
|||
Other keys can be used when appending to an existing setting or task, just like they can for assigning with `:=`.
|
||||
|
||||
For example, say you have a coverage report named after the project, and
|
||||
you want to add it to the files removed by `clean`:
|
||||
you want to add it to the files removed by :key:`clean`:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -199,5 +199,5 @@ Next
|
|||
----
|
||||
|
||||
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`.
|
||||
move on to a specific key that comes up often: :key:`libraryDependencies`.
|
||||
:doc:`Learn about library dependencies <Library-Dependencies>`.
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ especially if they depend on one another and you tend to modify them
|
|||
together.
|
||||
|
||||
Each sub-project in a build has its own source directories, generates
|
||||
its own jar file when you run `package`, and in general works like any
|
||||
its own jar file when you run :key:`package`, and in general works like any
|
||||
other project.
|
||||
|
||||
A project is defined by declaring a `lazy val` of type `Project <../../api/sbt/Project.html>`_.
|
||||
|
|
@ -59,12 +59,12 @@ run it on the aggregated projects. For example, ::
|
|||
|
||||
|
||||
In the above example, the root project aggregates `util` and `core`.
|
||||
Start up sbt with two subprojects as in the example, and try `compile`.
|
||||
Start up sbt with two subprojects as in the example, and try :key:`compile`.
|
||||
You should see that all three projects are compiled.
|
||||
|
||||
*In the project doing the aggregating*, the `root` project in
|
||||
this case, you can control aggregation per-task.
|
||||
For example, to avoid aggregating the `update` task:
|
||||
For example, to avoid aggregating the :key:`update` task:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -77,7 +77,7 @@ For example, to avoid aggregating the `update` task:
|
|||
|
||||
[...]
|
||||
|
||||
`aggregate in update` is the `aggregate` key scoped to the `update` task.
|
||||
`aggregate in update` is the :key:`aggregate` key scoped to the :key:`update` task.
|
||||
(See :doc:`scopes <Scopes>`.)
|
||||
|
||||
Note: aggregation will run the aggregated tasks in parallel and with no
|
||||
|
|
@ -182,7 +182,7 @@ Navigating projects interactively
|
|||
|
||||
At the sbt interactive prompt, type `projects` to list your projects
|
||||
and `project <projectname>` to select a current project. When you run
|
||||
a task like `compile`, it runs on the current project. So you don't
|
||||
a task like :key:`compile`, it runs on the current project. So you don't
|
||||
necessarily have to compile the root project, you could compile only a
|
||||
subproject.
|
||||
|
||||
|
|
|
|||
|
|
@ -20,15 +20,15 @@ Running sbt with no command line arguments starts it in interactive
|
|||
mode. Interactive mode has a command prompt (with tab completion and
|
||||
history!).
|
||||
|
||||
For example, you could type `compile` at the sbt prompt:
|
||||
For example, you could type :key:`compile` at the sbt prompt:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
> compile
|
||||
|
||||
To `compile` again, press up arrow and then enter.
|
||||
To :key:`compile` again, press up arrow and then enter.
|
||||
|
||||
To run your program, type `run`.
|
||||
To run your program, type :key:`run`.
|
||||
|
||||
To leave interactive mode, type `exit` or use Ctrl+D (Unix) or Ctrl+Z
|
||||
(Windows).
|
||||
|
|
@ -45,9 +45,9 @@ in quotes. For example,
|
|||
|
||||
$ sbt clean compile "testOnly TestA TestB"
|
||||
|
||||
In this example, `testOnly` has arguments, `TestA` and `TestB`.
|
||||
The commands will be run in sequence (`clean`, `compile`, then
|
||||
`testOnly`).
|
||||
In this example, :key:`testOnly` has arguments, `TestA` and `TestB`.
|
||||
The commands will be run in sequence (:key:`clean`, :key:`compile`, then
|
||||
:key:`testOnly`).
|
||||
|
||||
Continuous build and test
|
||||
-------------------------
|
||||
|
|
@ -74,16 +74,16 @@ Common commands
|
|||
Here are some of the most common sbt commands. For a more complete list,
|
||||
see :doc:`/Detailed-Topics/Command-Line-Reference`.
|
||||
|
||||
- `clean` Deletes all generated files (in the `target` directory).
|
||||
- `compile` Compiles the main sources (in `src/main/scala` and
|
||||
- :key:`clean` Deletes all generated files (in the :key:`target` directory).
|
||||
- :key:`compile` Compiles the main sources (in `src/main/scala` and
|
||||
`src/main/java` directories).
|
||||
- `test` Compiles and runs all tests.
|
||||
- `console` Starts the Scala interpreter with a classpath including
|
||||
- :key:`test` Compiles and runs all tests.
|
||||
- :key:`console` Starts the Scala interpreter with a classpath including
|
||||
the compiled sources and all dependencies. To return to sbt, type
|
||||
`:quit`, Ctrl+D (Unix), or Ctrl+Z (Windows).
|
||||
- `run <argument>*` Runs the main class for the project in the same
|
||||
virtual machine as `sbt`.
|
||||
- `package` Creates a jar file containing the files in
|
||||
- :key:`package` Creates a jar file containing the files in
|
||||
`src/main/resources` and the classes compiled from
|
||||
`src/main/scala` and `src/main/java`.
|
||||
- `help <command>` Displays detailed help for the specified command.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ The whole story about keys
|
|||
--------------------------
|
||||
|
||||
:doc:`Previously <Basic-Def>` we pretended that a key like
|
||||
`name` corresponded to one entry in sbt's map of key-value pairs. This
|
||||
:key:`name` corresponded to one entry in sbt's map of key-value pairs. This
|
||||
was a simplification.
|
||||
|
||||
In truth, each key can have an associated value in more than one
|
||||
|
|
@ -19,11 +19,11 @@ Some concrete examples:
|
|||
|
||||
- if you have multiple projects in your build definition, a key can
|
||||
have a different value in each project.
|
||||
- the `compile` key may have a different value for your main sources
|
||||
- the :key:`compile` key may have a different value for your main sources
|
||||
and your test sources, if you want to compile them differently.
|
||||
- the `packageOptions` key (which contains options for creating jar
|
||||
- the :key:`packageOptions` key (which contains options for creating jar
|
||||
packages) may have different values when packaging class files
|
||||
(`packageBin`) or packaging source code (`packageSrc`).
|
||||
(:key:`packageBin`) or packaging source code (:key:`packageSrc`).
|
||||
|
||||
*There is no single value for a given key name*, because the value may
|
||||
differ according to scope.
|
||||
|
|
@ -80,22 +80,22 @@ Some configurations you'll see in sbt:
|
|||
By default, all the keys associated with compiling, packaging, and
|
||||
running are scoped to a configuration and therefore may work differently
|
||||
in each configuration. The most obvious examples are the task keys
|
||||
`compile`, `package`, and `run`; but all the keys which *affect*
|
||||
those keys (such as `sourceDirectories` or `scalacOptions` or
|
||||
`fullClasspath`) are also scoped to the configuration.
|
||||
:key:`compile`, :key:`package`, and :key:`run`; but all the keys which *affect*
|
||||
those keys (such as :key:`sourceDirectories` or :key:`scalacOptions` or
|
||||
:key:`fullClasspath`) are also scoped to the configuration.
|
||||
|
||||
Scoping by task axis
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Settings can affect how a task works. For example, the `packageSrc`
|
||||
task is affected by the `packageOptions` setting.
|
||||
Settings can affect how a task works. For example, the :key:`packageSrc`
|
||||
task is affected by the :key:`packageOptions` setting.
|
||||
|
||||
To support this, a task key (such as `packageSrc`) can be a scope for
|
||||
another key (such as `packageOptions`).
|
||||
To support this, a task key (such as :key:`packageSrc`) can be a scope for
|
||||
another key (such as :key:`packageOptions`).
|
||||
|
||||
The various tasks that build a package (`packageSrc`,
|
||||
`packageBin`, `packageDoc`) can share keys related to packaging,
|
||||
such as `artifactName` and `packageOptions`. Those keys can have
|
||||
The various tasks that build a package (:key:`packageSrc`,
|
||||
:key:`packageBin`, :key:`packageDoc`) can share keys related to packaging,
|
||||
such as :key:`artifactName` and :key:`packageOptions`. Those keys can have
|
||||
distinct values for each packaging task.
|
||||
|
||||
Global scope
|
||||
|
|
@ -156,15 +156,15 @@ For more details, see :doc:`/Detailed-Topics/Inspecting-Settings`.
|
|||
Examples of scoped key notation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- `fullClasspath`: just a key, so the default scopes are used:
|
||||
- :key:`fullClasspath`: just a key, so the default scopes are used:
|
||||
current project, a key-dependent configuration, and global task
|
||||
scope.
|
||||
- `test:fullClasspath`: specifies the configuration, so this is
|
||||
`fullClasspath` in the `test` configuration, with defaults for
|
||||
:key:`fullClasspath` in the `test` configuration, with defaults for
|
||||
the other two scope axes.
|
||||
- `*:fullClasspath`: specifies `Global` for the configuration,
|
||||
rather than the default configuration.
|
||||
- `doc::fullClasspath`: specifies the `fullClasspath` key scoped
|
||||
- `doc::fullClasspath`: specifies the :key:`fullClasspath` key scoped
|
||||
to the `doc` task, with the defaults for the project and
|
||||
configuration axes.
|
||||
- `{file:/home/hp/checkout/hello/}default-aea33a/test:fullClasspath`
|
||||
|
|
@ -232,7 +232,7 @@ The value resulting from the task will have type
|
|||
"Provided by" points you to the scoped key that defines the value, in
|
||||
this case
|
||||
`{file:/home/hp/checkout/hello/}default-aea33a/test:fullClasspath`
|
||||
(which is the `fullClasspath` key scoped to the `test`
|
||||
(which is the :key:`fullClasspath` key scoped to the `test`
|
||||
configuration and the `{file:/home/hp/checkout/hello/}default-aea33a`
|
||||
project).
|
||||
|
||||
|
|
@ -267,7 +267,7 @@ Because the configuration is omitted, it is autodetected as `compile`.
|
|||
`inspect fullClasspath`.
|
||||
|
||||
Try `inspect *:fullClasspath` for another contrast.
|
||||
`fullClasspath` is not defined in the `Global` configuration by
|
||||
:key:`fullClasspath` is not defined in the `Global` configuration by
|
||||
default.
|
||||
|
||||
Again, for more details, see :doc:`/Detailed-Topics/Inspecting-Settings`.
|
||||
|
|
@ -302,7 +302,7 @@ name scoped to the `Compile` configuration:
|
|||
|
||||
name in Compile := "hello"
|
||||
|
||||
or you could set the name scoped to the `packageBin` task (pointless!
|
||||
or you could set the name scoped to the :key:`packageBin` task (pointless!
|
||||
just an example):
|
||||
|
||||
::
|
||||
|
|
@ -310,7 +310,7 @@ just an example):
|
|||
name in packageBin := "hello"
|
||||
|
||||
or you could set the name with multiple scope axes, for example in the
|
||||
`packageBin` task in the `Compile` configuration:
|
||||
:key:`packageBin` task in the `Compile` configuration:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -343,12 +343,12 @@ When to specify a scope
|
|||
-----------------------
|
||||
|
||||
You need to specify the scope if the key in question is normally scoped.
|
||||
For example, the `compile` task, by default, is scoped to `Compile`
|
||||
For example, the :key:`compile` task, by default, is scoped to `Compile`
|
||||
and `Test` configurations, and does not exist outside of those scopes.
|
||||
|
||||
To change the value associated with the `compile` key, you need to
|
||||
To change the value associated with the :key:`compile` key, you need to
|
||||
write `compile in Compile` or `compile in Test`. Using plain
|
||||
`compile` would define a new compile task scoped to the current
|
||||
:key:`compile` would define a new compile task scoped to the current
|
||||
project, rather than overriding the standard compile tasks which are
|
||||
scoped to a configuration.
|
||||
|
||||
|
|
@ -362,7 +362,7 @@ One way to think of it is that a name is only *part* of a key. In
|
|||
reality, all keys consist of both a name, and a scope (where the scope
|
||||
has three axes). The entire expression
|
||||
`packageOptions in (Compile, packageBin)` is a key name, in other
|
||||
words. Simply `packageOptions` is also a key name, but a different one
|
||||
words. Simply :key:`packageOptions` is also a key name, but a different one
|
||||
(for keys with no `in`, a scope is implicitly assumed: current
|
||||
project, global config, global task).
|
||||
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ sbt provides standard hooks for adding source or resource generation tasks.
|
|||
|
||||
sourceGenerators in Compile += <your Task[Seq[File]] here>
|
||||
|
||||
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:
|
||||
A source generation task should generate sources in a subdirectory of :key:`sourceManaged` and return a sequence of files generated. The key to add the task to is called :key:`sourceGenerators`. It should be scoped according to whether the generated files are main (`Compile`) or test (`Test`) sources. This basic structure looks like:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -46,7 +46,7 @@ By default, generated sources are not included in the packaged source artifact.
|
|||
|
||||
resourceGenerators in Compile += <your Task[Seq[File]] here>
|
||||
|
||||
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:
|
||||
A resource generation task should generate resources in a subdirectory of :key:`resourceManaged` and return a sequence of files generated. The key to add the task to is called :key:`resourceGenerators`. It should be scoped according to whether the generated files are main (`Compile`) or test (`Test`) resources. This basic structure looks like:
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
|
|
@ -300,8 +300,8 @@ For the test classpath,
|
|||
|
||||
show compile:discoveredMainClasses
|
||||
|
||||
sbt detects the classes with public, static main methods for use by the `run` method and to tab-complete the `runMain` method.
|
||||
The `discoveredMainClasses` task does this discovery and provides as its result the list of class names.
|
||||
sbt detects the classes with public, static main methods for use by the :key:`run` method and to tab-complete the :key:`runMain` method.
|
||||
The :key:`discoveredMainClasses` task does this discovery and provides as its result the list of class names.
|
||||
For example, the following shows the main classes discovered in the main sources:
|
||||
|
||||
.. code-block:: console
|
||||
|
|
@ -318,7 +318,7 @@ For example, the following shows the main classes discovered in the main sources
|
|||
show definedTestNames
|
||||
|
||||
sbt detects tests according to fingerprints provided by test frameworks.
|
||||
The `definedTestNames` task provides as its result the list of test names detected in this way.
|
||||
The :key:`definedTestNames` task provides as its result the list of test names detected in this way.
|
||||
For example,
|
||||
|
||||
.. code-block:: console
|
||||
|
|
|
|||
|
|
@ -67,7 +67,7 @@ Some commands have different levels of completion. Hitting tab multiple times i
|
|||
> consoleQuick
|
||||
scala> :keybindings
|
||||
|
||||
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`, `consoleQuick`, or `consoleProject`) and then running `:keybindings`. For example:
|
||||
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 :key:`console` commands (:key:`console`, :key:`consoleQuick`, or :key:`consoleProject`) and then running `:keybindings`. For example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -100,7 +100,7 @@ The default keybindings file is included in the sbt launcher and may be used as
|
|||
shellPrompt := { (s: State) => System.getProperty("user.name") + "> " }
|
||||
|
||||
By default, sbt only displays `>` to prompt for a command.
|
||||
This can be changed through the `shellPrompt` setting, which has type `State => String`.
|
||||
This can be changed through the :key:`shellPrompt` setting, which has type `State => String`.
|
||||
:doc:`State </Extending/Build-State>` contains all state for sbt and thus provides access to all build information for use in the prompt string.
|
||||
|
||||
Examples:
|
||||
|
|
@ -144,14 +144,14 @@ search history backwards. The following commands are supported:
|
|||
|
||||
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]`.
|
||||
The location can be changed with the :key:`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:
|
||||
|
||||
::
|
||||
|
||||
historyPath := Some(baseDirectory.value / ".history")
|
||||
|
||||
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).
|
||||
The history path needs to be set for each project, since sbt will use the value of :key:`historyPath` for the current project (as selected by the `project` command).
|
||||
|
||||
|
||||
.. howto::
|
||||
|
|
@ -163,7 +163,7 @@ The history path needs to be set for each project, since sbt will use the value
|
|||
|
||||
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:
|
||||
The way this is done is to set :key:`historyPath` to be the same file, such as a file in the root project's `target/` directory:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -179,7 +179,7 @@ The `in LocalRootProject` part means to get the output directory for the root pr
|
|||
|
||||
historyPath := None
|
||||
|
||||
If, for whatever reason, you want to disable history, set `historyPath` to `None` in each project it should be disabled in:
|
||||
If, for whatever reason, you want to disable history, set :key:`historyPath` to `None` in each project it should be disabled in:
|
||||
|
||||
historyPath := None
|
||||
|
||||
|
|
@ -199,8 +199,8 @@ 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.
|
||||
This runs :key:`clean` and then :key:`compile` before entering the interactive prompt.
|
||||
If either :key:`clean` or :key:`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,
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ Configure and use logging
|
|||
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:
|
||||
For example, the output of :key:`run` when the sources are uptodate is:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -69,7 +69,7 @@ Configuration of the logging level for the console and for the backing file are
|
|||
|
||||
When a task is run, more detailed logging output is sent to a file than to the screen (by default).
|
||||
This output can be recalled for a specific task by running `last <task>`.
|
||||
For example, the first time `compile` is run, output might look like:
|
||||
For example, the first time :key:`compile` is run, output might look like:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -125,8 +125,8 @@ Compiling code that uses the deprecated `error` method from Predef might generat
|
|||
[warn] there were 1 deprecation warnings; re-run with -deprecation for details
|
||||
[warn] one warning found
|
||||
|
||||
The details aren't provided, so it is necessary to add `-deprecation` to the options passed to the compiler (`scalacOptions`) and recompile.
|
||||
An alternative when using Scala 2.10 and later is to run `printWarnings`.
|
||||
The details aren't provided, so it is necessary to add `-deprecation` to the options passed to the compiler (:key:`scalacOptions`) and recompile.
|
||||
An alternative when using Scala 2.10 and later is to run :key:`printWarnings`.
|
||||
This task will display all warnings from the previous compilation.
|
||||
For example,
|
||||
|
||||
|
|
@ -144,7 +144,7 @@ For example,
|
|||
|
||||
set every logLevel := Level.Debug
|
||||
|
||||
The amount of logging is controlled by the `logLevel` setting, which takes values from the `Level` enumeration.
|
||||
The amount of logging is controlled by the :key:`logLevel` setting, which takes values from the `Level` enumeration.
|
||||
Valid values are `Error`, `Warn`, `Info`, and `Debug` in order of increasing verbosity.
|
||||
To change the global logging level, set `logLevel in Global`.
|
||||
For example, to set it temporarily from the sbt prompt,
|
||||
|
|
@ -161,7 +161,7 @@ For example, to set it temporarily from the sbt prompt,
|
|||
|
||||
logLevel in compile := Level.Debug
|
||||
|
||||
The amount of logging is controlled by the `logLevel` setting, which takes values from the `Level` enumeration.
|
||||
The amount of logging is controlled by the :key:`logLevel` setting, which takes values from the `Level` enumeration.
|
||||
Valid values are `Error`, `Warn`, `Info`, and `Debug` in order of increasing verbosity.
|
||||
The logging level may be configured globally, as described in the previous section, or it may be applied to a specific project, configuration, or task.
|
||||
For example, to change the logging level for compilation to only show warnings and errors:
|
||||
|
|
@ -177,9 +177,9 @@ To enable debug logging for all tasks in the current project,
|
|||
> set logLevel := Level.Warn
|
||||
|
||||
A common scenario is that after running a task, you notice that you need more information than was shown by default.
|
||||
A `logLevel` based solution typically requires changing the logging level and running a task again.
|
||||
A :key:`logLevel` based solution typically requires changing the logging level and running a task again.
|
||||
However, there are two cases where this is unnecessary.
|
||||
First, warnings from a previous compilation may be displayed using `printWarnings` for the main sources or `test:printWarnings` for test sources.
|
||||
First, warnings from a previous compilation may be displayed using :key:`printWarnings` for the main sources or `test:printWarnings` for test sources.
|
||||
Second, output from the previous execution is available either for a single task or for in its entirety.
|
||||
See the section on `printWarnings <#printwarnings>`_ and the sections on `previous output <#last>`_.
|
||||
|
||||
|
|
@ -195,8 +195,8 @@ By default, sbt hides the stack trace of most exceptions thrown during execution
|
|||
It prints a message that indicates how to display the exception.
|
||||
However, you may want to show more of stack traces by default.
|
||||
|
||||
The setting to configure is `traceLevel`, which is a setting with an Int value.
|
||||
When `traceLevel` is set to a negative value, no stack traces are shown.
|
||||
The setting to configure is :key:`traceLevel`, which is a setting with an Int value.
|
||||
When :key:`traceLevel` is set to a negative value, no stack traces are shown.
|
||||
When it is zero, the stack trace is displayed up to the first sbt stack frame.
|
||||
When positive, the stack trace is shown up to that many stack frames.
|
||||
|
||||
|
|
@ -207,7 +207,7 @@ For example, the following configures sbt to show stack traces up to the first s
|
|||
> set every traceLevel := 0
|
||||
|
||||
The `every` part means to override the setting in all scopes.
|
||||
To change the trace printing behavior for a single project, configuration, or task, scope `traceLevel` appropriately:
|
||||
To change the trace printing behavior for a single project, configuration, or task, scope :key:`traceLevel` appropriately:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -224,7 +224,7 @@ To change the trace printing behavior for a single project, configuration, or ta
|
|||
|
||||
By default, sbt buffers the logging output of a test until the whole class finishes.
|
||||
This is so that output does not get mixed up when executing in parallel.
|
||||
To disable buffering, set the `logBuffered` setting to false:
|
||||
To disable buffering, set the :key:`logBuffered` setting to false:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -234,9 +234,9 @@ To disable buffering, set the `logBuffered` setting to false:
|
|||
:id: custom
|
||||
:title: Add a custom logger
|
||||
|
||||
The setting `extraLoggers` can be used to add custom loggers.
|
||||
The setting :key:`extraLoggers` can be used to add custom loggers.
|
||||
A custom logger should implement [AbstractLogger].
|
||||
`extraLoggers` is a function `ScopedKey[_] => Seq[AbstractLogger]`.
|
||||
:key:`extraLoggers` is a function `ScopedKey[_] => Seq[AbstractLogger]`.
|
||||
This means that it can provide different logging based on the task that requests the logger.
|
||||
|
||||
::
|
||||
|
|
@ -255,8 +255,8 @@ The new function prepends our custom logger to the ones provided by the old func
|
|||
:id: log
|
||||
:title: Log messages in a task
|
||||
|
||||
The special task `streams` provides per-task logging and I/O via a `Streams <../../api/#sbt.std.Streams>`_ instance.
|
||||
To log, a task uses the `log` member from the `streams` task:
|
||||
The special task :key:`streams` provides per-task logging and I/O via a `Streams <../../api/#sbt.std.Streams>`_ instance.
|
||||
To log, a task uses the `log` member from the :key:`streams` task:
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
Project metadata
|
||||
================
|
||||
|
||||
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`.
|
||||
A project should define :key:`name` and :key:`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 :key:`organization`.
|
||||
|
||||
.. howto::
|
||||
:id: name
|
||||
|
|
@ -15,7 +15,7 @@ A project should define `name` and `version`. These will be used in various par
|
|||
|
||||
name := "Your project name"
|
||||
|
||||
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`.
|
||||
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 :key:`normalizedName`.
|
||||
|
||||
.. howto::
|
||||
:id: version
|
||||
|
|
@ -37,7 +37,7 @@ For published projects, this name is normalized to be suitable for use as an art
|
|||
|
||||
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:
|
||||
A full/formal name can be defined in the :key:`organizationName` setting. This is used in the generated pom.xml. If the organization has a web site, it may be set in the :key:`organizationHomepage` setting. For example:
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
|
|
@ -9,13 +9,13 @@
|
|||
|
||||
exportJars := true
|
||||
|
||||
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,
|
||||
By default, a project exports a directory containing its resources and compiled class files. Set :key:`exportJars` to true to export the packaged jar instead. For example,
|
||||
|
||||
::
|
||||
|
||||
exportJars := true
|
||||
|
||||
The jar will be used by `run`, `test`, `console`, and other tasks that use the full classpath.
|
||||
The jar will be used by :key:`run`, :key:`test`, :key:`console`, and other tasks that use the full classpath.
|
||||
|
||||
|
||||
.. howto::
|
||||
|
|
@ -26,7 +26,7 @@ The jar will be used by `run`, `test`, `console`, and other tasks that use the f
|
|||
packageOptions in (Compile, packageBin) +=
|
||||
Package.ManifestAttributes( Attributes.Name.SEALED -> "true" )
|
||||
|
||||
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.
|
||||
By default, sbt constructs a manifest for the binary package from settings such as :key:`organization` and :key:`mainClass`. Additional attributes may be added to the :key:`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.
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ Or, to read the manifest from a file:
|
|||
:id: name
|
||||
:title: Change the file name of a package
|
||||
|
||||
The `artifactName` setting controls the name of generated packages. See the :doc:`/Detailed-Topics/Artifacts` page for details.
|
||||
The :key:`artifactName` setting controls the name of generated packages. See the :doc:`/Detailed-Topics/Artifacts` page for details.
|
||||
|
||||
.. howto::
|
||||
:id: contents
|
||||
|
|
@ -73,7 +73,7 @@ The `artifactName` setting controls the name of generated packages. See the :do
|
|||
|
||||
.. _modify-package-contents:
|
||||
|
||||
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 :doc:`/Detailed-Topics/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",
|
||||
The contents of a package are defined by the :key:`mappings` task, of type `Seq[(File,String)]`. The :key:`mappings` task is a sequence of mappings from a file to include in the package to the path in the package. See :doc:`/Detailed-Topics/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",
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -81,4 +81,4 @@ The contents of a package are defined by the `mappings` task, of type `Seq[(File
|
|||
(baseDirectory.value / "in" / "example.txt") -> "out/example.txt"
|
||||
}
|
||||
|
||||
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.
|
||||
Note that :key:`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.
|
||||
|
|
|
|||
|
|
@ -28,7 +28,7 @@ Multiple commands can be scheduled at once by prefixing each command with a semi
|
|||
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:
|
||||
For example, the following runs :key:`clean` and then :key:`compile` each time a source file changes:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -85,4 +85,4 @@ For example,
|
|||
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.
|
||||
Use the Scala REPL (:key:`console` and related commands) for full support for evaluating Scala code interactively.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@
|
|||
|
||||
version := "1.0"
|
||||
|
||||
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.
|
||||
The :key:`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.2",
|
||||
|
||||
|
|
@ -24,7 +24,7 @@ For example, to set the Scala version to "2.9.2",
|
|||
|
||||
autoScalaLibrary := false
|
||||
|
||||
sbt adds a dependency on the Scala standard library by default. To disable this behavior, set the `autoScalaLibrary` setting to false.
|
||||
sbt adds a dependency on the Scala standard library by default. To disable this behavior, set the :key:`autoScalaLibrary` setting to false.
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -50,7 +50,7 @@ To set the Scala version in all scopes to a specific value, use the `++` command
|
|||
|
||||
scalaHome := Some(file("/path/to/scala/home/"))
|
||||
|
||||
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,
|
||||
Defining the :key:`scalaHome` setting with the path to the Scala home directory will use that Scala installation. sbt still requires :key:`scalaVersion` to be set when a local Scala version is used. For example,
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -71,7 +71,7 @@ See :doc:`cross building </Detailed-Topics/Cross-Build>`.
|
|||
|
||||
consoleQuick
|
||||
|
||||
The `consoleQuick` 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:consoleQuick`. This will force compilation of main sources.
|
||||
The :key:`consoleQuick` 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:consoleQuick`. This will force compilation of main sources.
|
||||
|
||||
.. howto::
|
||||
:id: console
|
||||
|
|
@ -80,7 +80,7 @@ The `consoleQuick` action retrieves dependencies and puts them on the classpath
|
|||
|
||||
console
|
||||
|
||||
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`.
|
||||
The :key:`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`.
|
||||
|
||||
.. howto::
|
||||
:id: consoleProject
|
||||
|
|
@ -102,7 +102,7 @@ For details, see the :doc:`consoleProject </Detailed-Topics/Console-Project>` pa
|
|||
|
||||
initialCommands in console := """println("Hi!")"""
|
||||
|
||||
Set `initialCommands in console` to set the initial statements to evaluate when `console` and `consoleQuick` are run. To configure `consoleQuick` separately, use `initialCommands in consoleQuick`.
|
||||
Set `initialCommands in console` to set the initial statements to evaluate when :key:`console` and :key:`consoleQuick` are run. To configure :key:`consoleQuick` separately, use `initialCommands in consoleQuick`.
|
||||
For example,
|
||||
|
||||
::
|
||||
|
|
@ -111,7 +111,7 @@ For example,
|
|||
|
||||
initialCommands in consoleQuick := """println("Hello from consoleQuick")"""
|
||||
|
||||
The `consoleProject` command is configured separately by `initialCommands in consoleProject`. It does not use the value from `initialCommands in console` by default. For example,
|
||||
The :key:`consoleProject` command is configured separately by `initialCommands in consoleProject`. It does not use the value from `initialCommands in console` by default. For example,
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -125,7 +125,7 @@ The `consoleProject` command is configured separately by `initialCommands in con
|
|||
|
||||
cleanupCommands in console := """println("Bye!")"""
|
||||
|
||||
Set `cleanupCommands in console` to set the statements to evaluate after exiting the Scala REPL started by `console` and `consoleQuick`. To configure `consoleQuick` separately, use `cleanupCommands in consoleQuick`.
|
||||
Set `cleanupCommands in console` to set the statements to evaluate after exiting the Scala REPL started by :key:`console` and :key:`consoleQuick`. To configure :key:`consoleQuick` separately, use `cleanupCommands in consoleQuick`.
|
||||
For example,
|
||||
|
||||
::
|
||||
|
|
@ -134,7 +134,7 @@ For example,
|
|||
|
||||
cleanupCommands in consoleQuick := """println("Bye from consoleQuick")"""
|
||||
|
||||
The `consoleProject` command is configured separately by `cleanupCommands in consoleProject`. It does not use the value from `cleanupCommands in console` by default. For example,
|
||||
The :key:`consoleProject` command is configured separately by `cleanupCommands in consoleProject`. It does not use the value from `cleanupCommands in console` by default. For example,
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -145,7 +145,7 @@ The `consoleProject` command is configured separately by `cleanupCommands in con
|
|||
:id: embed
|
||||
:title: Use the Scala REPL from project code
|
||||
|
||||
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:
|
||||
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 :key:`console` and when :key:`run` is not forked. Therefore, when using the Scala interpreter, it is important to set it up properly to avoid an error message like:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ If there are any Scala sources, sbt will run `scaladoc`.
|
|||
|
||||
scalacOptions in (Compile,doc) := Seq("-groups", "-implicits")
|
||||
|
||||
Scope `scalacOptions` to the `doc` task to configure `scaladoc`.
|
||||
Scope :key:`scalacOptions` to the :key:`doc` task to configure `scaladoc`.
|
||||
Use `:=` to definitively set the options without appending to the options for `compile`.
|
||||
Scope to `Compile` for main sources or to `Test` for test sources.
|
||||
For example, ::
|
||||
|
|
@ -34,7 +34,7 @@ For example, ::
|
|||
|
||||
scalacOptions in (Compile,doc) ++= Seq("-groups", "-implicits")
|
||||
|
||||
Scope `scalacOptions` to the `doc` task to configure `scaladoc`.
|
||||
Scope :key:`scalacOptions` to the :key:`doc` task to configure `scaladoc`.
|
||||
Use `+=` or `++=` to append options to the base options.
|
||||
To append a single option, use `+=`.
|
||||
To append a `Seq[String]`, use `++=`.
|
||||
|
|
@ -50,7 +50,7 @@ For example, ::
|
|||
|
||||
javacOptions in (Compile,doc) := Seq("-notimestamp", "-linksource")
|
||||
|
||||
Scope `javacOptions` to the `doc` task to configure `javadoc`.
|
||||
Scope :key:`javacOptions` to the :key:`doc` task to configure `javadoc`.
|
||||
Use `:=` to definitively set the options without appending to the options for `compile`.
|
||||
Scope to `Compile` for main sources or to `Test` for test sources.
|
||||
|
||||
|
|
@ -61,7 +61,7 @@ Scope to `Compile` for main sources or to `Test` for test sources.
|
|||
|
||||
javacOptions in (Compile,doc) ++= Seq("-notimestamp", "-linksource")
|
||||
|
||||
Scope `javacOptions` to the `doc` task to configure `javadoc`.
|
||||
Scope :key:`javacOptions` to the :key:`doc` task to configure `javadoc`.
|
||||
Use `+=` or `++=` to append options to the base options.
|
||||
To append a single option, use `+=`.
|
||||
To append a `Seq[String]`, use `++=`.
|
||||
|
|
@ -87,9 +87,9 @@ This requires that dependencies have this information in its metadata and you ar
|
|||
|
||||
apiMappings += ( <File> -> <URL> )
|
||||
|
||||
Add mappings of type `(File, URL)` to `apiMappings` to manually tell `scaladoc` where it can find the API documentation for dependencies.
|
||||
Add mappings of type `(File, URL)` to :key:`apiMappings` to manually tell `scaladoc` where it can find the API documentation for dependencies.
|
||||
(This requires `scaladoc` for Scala 2.10.2 or later.)
|
||||
These mappings are used in addition to `autoAPIMappings`, so this manual configuration is typically done for unmanaged dependencies.
|
||||
These mappings are used in addition to :key:`autoAPIMappings`, so this manual configuration is typically done for unmanaged dependencies.
|
||||
The `File` key is the location of the dependency as passed to the classpath.
|
||||
The `URL` value is the base URL of the API documentation for the dependency.
|
||||
For example, ::
|
||||
|
|
@ -106,8 +106,8 @@ For example, ::
|
|||
|
||||
apiURL := Some(url("http://example.org/api/"))
|
||||
|
||||
Set `apiURL` to define the base `URL` for the Scaladocs for your library.
|
||||
This will enable clients of your library to automatically link against the API documentation using `autoAPIMappings`.
|
||||
Set :key:`apiURL` to define the base `URL` for the Scaladocs for your library.
|
||||
This will enable clients of your library to automatically link against the API documentation using :key:`autoAPIMappings`.
|
||||
(This only works for Scala 2.10.2 and later.)
|
||||
For example, ::
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@
|
|||
|
||||
~ test
|
||||
|
||||
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 `watchSources` and `pollInterval` are modified as described in later sections.
|
||||
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 :key:`watch` setting, but typically the basic settings :key:`watchSources` and :key:`pollInterval` are modified as described in later sections.
|
||||
|
||||
The original use-case for triggered execution was continuous compilation:
|
||||
|
||||
|
|
@ -19,7 +19,7 @@ The original use-case for triggered execution was continuous compilation:
|
|||
|
||||
> ~ compile
|
||||
|
||||
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 `testOnly` for the specified test.
|
||||
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 :key:`testOnly` for the specified test.
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -47,8 +47,8 @@ This runs `a` and then `b` when sources change.
|
|||
|
||||
watchSources += baseDirectory.value / "examples.txt"
|
||||
|
||||
* `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 :doc:`/Getting-Started/Full-Def` for details on inter-project dependencies).
|
||||
* :key:`watchSources` defines the files for a single project that are monitored for changes. By default, a project watches resources and Scala and Java sources.
|
||||
* :key:`watchTransitiveSources` then combines the :key:`watchSources` for the current project and all execution and classpath dependencies (see :doc:`/Getting-Started/Full-Def` for details on inter-project dependencies).
|
||||
|
||||
To add the file `demo/example.txt` to the files to watch,
|
||||
|
||||
|
|
@ -63,7 +63,7 @@ To add the file `demo/example.txt` to the files to watch,
|
|||
|
||||
pollInterval := 1000 // in ms
|
||||
|
||||
`pollInterval` selects the interval between polling for changes in milliseconds. The default value is `500 ms`. To change it to `1 s`,
|
||||
:key:`pollInterval` selects the interval between polling for changes in milliseconds. The default value is `500 ms`. To change it to `1 s`,
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
|
|
@ -3,9 +3,6 @@ from sphinx.util.nodes import set_source_info
|
|||
|
||||
|
||||
class Struct:
|
||||
|
||||
"""Stores data attributes for dotted-attribute access."""
|
||||
|
||||
def __init__(self, **keywordargs):
|
||||
self.__dict__.update(keywordargs)
|
||||
|
||||
|
|
@ -17,14 +14,14 @@ def process_node(node):
|
|||
node['classes'].append('pre')
|
||||
return node
|
||||
|
||||
# This directive formats a string to be in a fixed width font.
|
||||
# This role formats a string to be in a fixed width font.
|
||||
# The string is taken as a literal and is not processed for further inline formatting.
|
||||
def code_literal(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
||||
node = nodes.inline('', text)
|
||||
node['classes'].append('pre')
|
||||
return [node], []
|
||||
|
||||
# This directive formats a string to be in a fixed width font.
|
||||
# This role formats a string to be in a fixed width font.
|
||||
# It processes nested inline formatting, substitutions in particular.
|
||||
def sub_literal(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
||||
memo = Struct(document=inliner.document,
|
||||
|
|
|
|||
|
|
@ -0,0 +1,37 @@
|
|||
from docutils import nodes
|
||||
from sphinx.util.nodes import set_source_info
|
||||
from sphinx.util.osutil import relative_uri
|
||||
|
||||
# node that will have its link that is relative to root be made relative to
|
||||
# the referencing document
|
||||
class sibling_ref(nodes.General, nodes.Inline, nodes.TextElement): pass
|
||||
|
||||
# This role interprets its argument as the name of a `val` in `sbt.Keys`.
|
||||
# The description of the key is used as the title and the name is linked to
|
||||
# the sxr documentation for the key.
|
||||
def sbt_key(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
||||
refNode = sibling_ref('', '')
|
||||
refNode.keyName = text
|
||||
refNode.description = 'faked'
|
||||
return [refNode], []
|
||||
|
||||
# register the role
|
||||
# process_sibling_ref_nodes will replace sibling_ref nodes with proper links
|
||||
# purge_siblings drops data for changed documents
|
||||
def setup(app):
|
||||
app.add_role('key', sbt_key)
|
||||
app.add_node(sibling_ref)
|
||||
app.connect('doctree-resolved', process_sibling_ref_nodes)
|
||||
|
||||
|
||||
# Resolves sibling_ref links relative to the referencing document
|
||||
def process_sibling_ref_nodes(app, doctree, fromdocname):
|
||||
fromTargetURI = app.builder.get_target_uri(fromdocname)
|
||||
# resolves links for all sibling_ref nodes
|
||||
for node in doctree.traverse(sibling_ref):
|
||||
rellink = '../sxr/sbt/Keys.scala.html#sbt.Keys.%s' % node.keyName
|
||||
newuri = relative_uri(fromTargetURI, rellink)
|
||||
refNode = nodes.reference('', node.keyName, internal=False, refuri=newuri)
|
||||
refNode['classes'].append('pre')
|
||||
refNode['title'] = node.description
|
||||
node.replace_self(refNode)
|
||||
|
|
@ -3,7 +3,7 @@
|
|||
import sys, os
|
||||
|
||||
sys.path.append(os.path.abspath('_sphinx/exts'))
|
||||
extensions = ['sphinxcontrib.issuetracker', 'sphinx.ext.extlinks', 'howto', 'codeliteral']
|
||||
extensions = ['sphinxcontrib.issuetracker', 'sphinx.ext.extlinks', 'howto', 'codeliteral', 'key']
|
||||
|
||||
# Project variables
|
||||
|
||||
|
|
|
|||
|
|
@ -52,14 +52,14 @@ screen, but as a newcomer it can leave you lost for explanation. To see
|
|||
the previous output of a command at a higher verbosity, type
|
||||
`last <task>` where `<task>` is the task that failed or that you
|
||||
want to view detailed output for. For example, if you find that your
|
||||
`update` fails to load all the dependencies as you expect you can
|
||||
:key:`update` fails to load all the dependencies as you expect you can
|
||||
enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
> last update
|
||||
|
||||
and it will display the full output from the last run of the `update`
|
||||
and it will display the full output from the last run of the :key:`update`
|
||||
command.
|
||||
|
||||
How do I disable ansi codes in the output?
|
||||
|
|
@ -115,8 +115,8 @@ How do I add files to a jar package?
|
|||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The files included in an artifact are configured by default by a task
|
||||
`mappings` that is scoped by the relevant package task. The
|
||||
`mappings` task returns a sequence `Seq[(File,String)]` of mappings
|
||||
:key:`mappings` that is scoped by the relevant package task. The
|
||||
:key:`mappings` task returns a sequence `Seq[(File,String)]` of mappings
|
||||
from the file to include to the path within the jar. See
|
||||
:doc:`/Detailed-Topics/Mapping-Files` for details on creating these mappings.
|
||||
|
||||
|
|
@ -131,10 +131,10 @@ For example, to add generated sources to the packaged source artifact:
|
|||
srcs x (relativeTo(base) | flat)
|
||||
}
|
||||
|
||||
This takes sources from the `managedSources` task and relativizes them
|
||||
against the `managedSource` base directory, falling back to a
|
||||
This takes sources from the :key:`managedSources` task and relativizes them
|
||||
against the :key:`managedSource` base directory, falling back to a
|
||||
flattened mapping. If a source generation task doesn't write the sources
|
||||
to the `managedSource` directory, the mapping function would have to
|
||||
to the :key:`managedSource` directory, the mapping function would have to
|
||||
be adjusted to try relativizing against additional directories or
|
||||
something more appropriate for the generator.
|
||||
|
||||
|
|
@ -197,7 +197,7 @@ The following example demonstrates adding a new set of compilation
|
|||
settings and tasks to a new configuration called `samples`. The
|
||||
sources for this configuration go in `src/samples/scala/`. Unspecified
|
||||
settings delegate to those defined for the `compile` configuration.
|
||||
For example, if `scalacOptions` are not overridden for `samples`,
|
||||
For example, if :key:`scalacOptions` are not overridden for `samples`,
|
||||
the options for the main sources are used.
|
||||
|
||||
Options specific to `samples` may be declared like:
|
||||
|
|
@ -278,7 +278,7 @@ configuration and classpaths. These are the steps:
|
|||
1. Define a new :ref:`configuration <ivy-configurations>`.
|
||||
2. Declare the tool :doc:`dependencies </Detailed-Topics/Library-Management>` in that
|
||||
configuration.
|
||||
3. Define a classpath that pulls the dependencies from the :doc:`/Detailed-Topics/Update-Report` produced by `update`.
|
||||
3. Define a classpath that pulls the dependencies from the :doc:`/Detailed-Topics/Update-Report` produced by :key:`update`.
|
||||
4. Use the classpath to implement the task.
|
||||
|
||||
As an example, consider a `proguard` task. This task needs the
|
||||
|
|
@ -356,7 +356,7 @@ Example of dynamic classpath augmentation
|
|||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following code can be used where a `State => State` is required,
|
||||
such as in the `onLoad` setting (described below) or in a
|
||||
such as in the :key:`onLoad` setting (described below) or in a
|
||||
:doc:`command </Extending/Commands>`. It adds some files to the "extra" component and
|
||||
reloads sbt if they were not already added. Note that reloading will
|
||||
drop the user's session state.
|
||||
|
|
@ -381,14 +381,14 @@ drop the user's session state.
|
|||
How can I take action when the project is loaded or unloaded?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The single, global setting `onLoad` is of type `State => State` (see
|
||||
The single, global setting :key:`onLoad` is of type `State => State` (see
|
||||
:doc:`/Extending/Build-State`) and is executed once, after all projects are built and
|
||||
loaded. There is a similar hook `onUnload` for when a project is
|
||||
loaded. There is a similar hook :key:`onUnload` for when a project is
|
||||
unloaded. Project unloading typically occurs as a result of a `reload`
|
||||
command or a `set` command. Because the `onLoad` and `onUnload`
|
||||
command or a `set` command. Because the :key:`onLoad` and :key:`onUnload`
|
||||
hooks are global, modifying this setting typically involves composing a
|
||||
new function with the previous value. The following example shows the
|
||||
basic structure of defining `onLoad`:
|
||||
basic structure of defining :key:`onLoad`:
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -434,7 +434,7 @@ Setting initializers are executed in order. If the initialization of a
|
|||
setting depends on other settings that has not been initialized, sbt
|
||||
will stop loading.
|
||||
|
||||
In this example, we try to append a library to `libraryDependencies`
|
||||
In this example, we try to append a library to :key:`libraryDependencies`
|
||||
before it is initialized with an empty sequence.
|
||||
|
||||
::
|
||||
|
|
@ -630,7 +630,7 @@ sbt 0.10 fixes a flaw in how dependencies get resolved in multi-module
|
|||
projects. This change ensures that only one version of a library appears
|
||||
on a classpath.
|
||||
|
||||
Use `last update` to view the debugging output for the last `update`
|
||||
Use `last update` to view the debugging output for the last :key:`update`
|
||||
run. Use `show update` to view a summary of files comprising managed
|
||||
classpaths.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue