mirror of https://github.com/sbt/sbt.git
Docs: howto pages on classpaths and default paths
This commit is contained in:
Mark Harrah
parent
136bb00698
commit
8bc0e5ab26
|
|
@ -222,6 +222,8 @@ mappings from the input file to its (String) path in the jar or its
|
|||
|
||||
Mappings are discussed in detail on the :doc:`Mapping-Files` page.
|
||||
|
||||
.. _file-filter:
|
||||
|
||||
File Filters
|
||||
------------
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,157 @@
|
|||
==========
|
||||
Classpaths
|
||||
==========
|
||||
|
||||
.. howto::
|
||||
:id: classpath-types
|
||||
:title: Include a new type of managed artifact on the classpath, such as `mar`
|
||||
:type: setting
|
||||
|
||||
classpathTypes += "mar"
|
||||
|
||||
The :key:`classpathTypes` setting controls the types of managed artifacts that are included on the classpath by default.
|
||||
To add a new type, such as `mar`, ::
|
||||
|
||||
classpathTypes += "mar"
|
||||
|
||||
See the default types included by running `show classpathTypes` at the sbt prompt.
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: get-compile-classpath
|
||||
:title: Get the classpath used for compilation
|
||||
:type: setting
|
||||
|
||||
... (dependencyClasspath in Compile).value.files ...
|
||||
|
||||
The :key:`dependencyClasspath` task scoped to `Compile` provides the classpath to use for compilation.
|
||||
Its type is `Seq[Attributed[File]]`, which means that each entry carries additional metadata.
|
||||
The `files` method provides just the raw `Seq[File]` for the classpath.
|
||||
For example, to use the files for the compilation classpath in another task, ::
|
||||
|
||||
example := {
|
||||
val cp: Seq[File] = (dependencyClasspath in Compile).value.files
|
||||
...
|
||||
}
|
||||
|
||||
.. note::
|
||||
|
||||
This classpath does not include the class directory, which may be necessary for compilation in some situations.
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: get-runtime-classpath
|
||||
:title: Get the runtime classpath, including the project's compiled classes
|
||||
:type: setting
|
||||
|
||||
... (fullClasspath in Runtime).value.files ...
|
||||
|
||||
The :key:`fullClasspath` task provides a classpath including both the dependencies and the products of project.
|
||||
For the runtime classpath, this means the main resources and compiled classes for the project as well as all runtime dependencies.
|
||||
|
||||
The type of a classpath is `Seq[Attributed[File]]`, which means that each entry carries additional metadata.
|
||||
The `files` method provides just the raw `Seq[File]` for the classpath.
|
||||
For example, to use the files for the runtime classpath in another task, ::
|
||||
|
||||
example := {
|
||||
val cp: Seq[File] = (fullClasspath in Runtime).value.files
|
||||
...
|
||||
}
|
||||
|
||||
.. howto::
|
||||
:id: get-test-classpath
|
||||
:title: Get the test classpath, including the project's compiled test classes
|
||||
:type: setting
|
||||
|
||||
... (fullClasspath in Test).value.files ...
|
||||
|
||||
The :key:`fullClasspath` task provides a classpath including both the dependencies and the products of a project.
|
||||
For the test classpath, this includes the main and test resources and compiled classes for the project as well as all dependencies for testing.
|
||||
|
||||
The type of a classpath is `Seq[Attributed[File]]`, which means that each entry carries additional metadata.
|
||||
The `files` method provides just the raw `Seq[File]` for the classpath.
|
||||
For example, to use the files for the test classpath in another task, ::
|
||||
|
||||
example := {
|
||||
val cp: Seq[File] = (fullClasspath in Test).value.files
|
||||
...
|
||||
}
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: export-jars
|
||||
:title: Use packaged jars on classpaths instead of class directories
|
||||
:type: setting
|
||||
|
||||
exportJars := true
|
||||
|
||||
By default, :key:`fullClasspath` includes a directory containing class files and resources for a project.
|
||||
This in turn means that tasks like :key:`compile`, :key:`test`, and :key:`run` have these class directories on their classpath.
|
||||
To use the packaged artifact (such as a jar) instead, configure :key:`exportJars` ::
|
||||
|
||||
exportJars := true
|
||||
|
||||
This will use the result of :key:`packageBin` on the classpath instead of the class directory.
|
||||
|
||||
.. note::
|
||||
|
||||
Specifically, :key:`fullClasspath` is the concatentation of :key:`dependencyClasspath` and :key:`exportedProducts`. When :key:`exportJars` is true, :key:`exportedProducts` is the output of `packageBin`. When :key:`exportJars` is false, :key:`exportedProducts` is just :key:`products`, which is by default the directory containing class files and resources.
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: managed-jars-in-config
|
||||
:title: Get all managed jars for a configuration
|
||||
:type: setting
|
||||
|
||||
... Classpaths.managedJars(config, artifactTypes, update.value) ...
|
||||
|
||||
The result of the :key:`update` task has type :doc:`UpdateReport </Detailed-Topics/Update-Report>`, which contains the results of dependency resolution.
|
||||
This can be used to extract the files for specific types of artifacts in a specific configuration.
|
||||
For example, to get the jars and zips of dependencies in the `Compile` configuration, ::
|
||||
|
||||
example := {
|
||||
val artifactTypes = Set("jar", "zip")
|
||||
val files: Seq[File] =
|
||||
Classpaths.managedJars(Compile, artifactTypes, update.value)
|
||||
...
|
||||
}
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: classpath-files
|
||||
:title: Get the files included in a classpath
|
||||
:type: setting
|
||||
|
||||
... someClasspath.files ...
|
||||
|
||||
A classpath has type `Seq[Attributed[File]]`, which means that each entry carries additional metadata.
|
||||
The `files` method provides just the raw `Seq[File]` for the classpath.
|
||||
For example, ::
|
||||
|
||||
val cp: Seq[Attributed[File]] = ...
|
||||
val files: Seq[File] = cp.files
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: classpath-entry-module
|
||||
:title: Get the module and artifact that produced a classpath entry
|
||||
:type: text
|
||||
|
||||
A classpath has type `Seq[Attributed[File]]`, which means that each entry carries additional metadata.
|
||||
This metadata is in the form of an `AttributeMap <../../api/sbt/AttributeMap.html>`_.
|
||||
Useful keys for entries in the map are `artifact.key`, `module.key`, and :key:`analysis`.
|
||||
For example, ::
|
||||
|
||||
val classpath: Seq[Attributed[File]] = ???
|
||||
for(entry <- classpath) yield {
|
||||
val art: Option[Artifact] = entry.get(artifact.key)
|
||||
val mod: Option[ModuleID] = entry.get(module.key)
|
||||
val an: Option[inc.Analysis] = entry.get(analysis)
|
||||
...
|
||||
}
|
||||
|
||||
.. note::
|
||||
|
||||
Entries may not have some or all metadata.
|
||||
Only entries from source dependencies, such as internal projects, have an incremental compilation `Analysis <../../api/sbt/inc/Analysis.html>`_.
|
||||
Only entries for managed dependencies have an `Artifact <../../api/sbt/Artifact.html>`_ and `ModuleID <../../api/sbt/ModuleID.html>`_.
|
||||
|
|
@ -0,0 +1,213 @@
|
|||
=================
|
||||
Customizing paths
|
||||
=================
|
||||
|
||||
This page describes how to modify the default source, resource, and library directories and what files get included from them.
|
||||
|
||||
.. howto::
|
||||
:id: scala-source-directory
|
||||
:title: Change the default Scala source directory
|
||||
:type: setting
|
||||
|
||||
scalaSource in Compile := baseDirectory.value / "src"
|
||||
|
||||
The directory that contains the main Scala sources is by default `src/main/scala`.
|
||||
For test Scala sources, it is `src/test/scala`.
|
||||
To change this, modify :key:`scalaSource` in the `Compile` (for main sources) or `Test` (for test sources).
|
||||
For example, ::
|
||||
|
||||
scalaSource in Compile := baseDirectory.value / "src"
|
||||
|
||||
scalaSource in Test := baseDirectory.value / "test-src"
|
||||
|
||||
.. note::
|
||||
|
||||
The Scala source directory can be the same as the Java source directory.
|
||||
|
||||
.. howto::
|
||||
:id: java-source-directory
|
||||
:title: Change the default Java source directory
|
||||
:type: setting
|
||||
|
||||
javaSource in Compile := baseDirectory.value / "src"
|
||||
|
||||
The directory that contains the main Java sources is by default `src/main/java`.
|
||||
For test Java sources, it is `src/test/java`.
|
||||
To change this, modify :key:`javaSource` in the `Compile` (for main sources) or `Test` (for test sources).
|
||||
|
||||
For example, ::
|
||||
|
||||
javaSource in Compile := baseDirectory.value / "src"
|
||||
|
||||
javaSource in Test := baseDirectory.value / "test-src"
|
||||
|
||||
.. note::
|
||||
|
||||
The Scala source directory can be the same as the Java source directory.
|
||||
|
||||
.. howto::
|
||||
:id: resource-directory
|
||||
:title: Change the default resource directory
|
||||
:type: setting
|
||||
|
||||
resourceDirectory in Compile := baseDirectory.value / "resources"
|
||||
|
||||
The directory that contains the main resources is by default `src/main/resources`.
|
||||
For test resources, it is `src/test/resources`.
|
||||
To change this, modify :key:`resourceDirectory` in either the `Compile` or `Test` configuration.
|
||||
|
||||
For example, ::
|
||||
|
||||
resourceDirectory in Compile := baseDirectory.value / "resources"
|
||||
|
||||
resourceDirectory in Test := baseDirectory.value / "test-resources"
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: unmanaged-base-directory
|
||||
:title: Change the default (unmanaged) library directory
|
||||
:type: setting
|
||||
|
||||
unmanagedBase := baseDirectory.value / "jars"
|
||||
|
||||
The directory that contains the unmanaged libraries is by default `lib/`.
|
||||
To change this, modify :key:`unmanagedBase`.
|
||||
This setting can be changed at the project level or in the `Compile`, `Runtime`, or `Test` configurations.
|
||||
|
||||
|
||||
When defined without a configuration, the directory is the default directory for all configurations.
|
||||
For example, the following declares `jars/` as containing libraries: ::
|
||||
|
||||
unmanagedBase := baseDirectory.value / "jars"
|
||||
|
||||
When set for `Compile`, `Runtime`, or `Test`, :key:`unmanagedBase` is the directory containing libraries for that configuration, overriding the default.
|
||||
For example, the following declares `lib/main/` to contain jars only for `Compile` and not for running or testing: ::
|
||||
|
||||
unmanagedBase in Compile := baseDirectory.value / "lib" / "main"
|
||||
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: disable-base-sources
|
||||
:title: Disable using the project's base directory as a source directory
|
||||
:type: setting
|
||||
|
||||
sourcesInBase := false
|
||||
|
||||
By default, sbt includes `.scala` files from the project's base directory as main source files.
|
||||
To disable this, configure :key:`sourcesInBase`: ::
|
||||
|
||||
sourcesInBase := false
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: add-source-directory
|
||||
:title: Add an additional source directory
|
||||
:type: setting
|
||||
|
||||
unmanagedSourceDirectories in Compile += baseDirectory.value / "extra-src"
|
||||
|
||||
sbt collects :key:`sources` from :key:`unmanagedSourceDirectories`, which by default consists of :key:`scalaSource` and :key:`javaSource`.
|
||||
Add a directory to :key:`unmanagedSourceDirectories` in the appropriate configuration to add a source directory.
|
||||
For example, to add `extra-src` to be an additional directory containing main sources, ::
|
||||
|
||||
unmanagedSourceDirectories in Compile += baseDirectory.value / "extra-src"
|
||||
|
||||
.. note::
|
||||
|
||||
This directory should only contain unmanaged sources, which are sources that are manually created and managed.
|
||||
See :doc:`/Howto/generatefiles` for working with automatically generated sources.
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: add-resource-directory
|
||||
:title: Add an additional resource directory
|
||||
:type: setting
|
||||
|
||||
unmanagedResourceDirectories in Compile += baseDirectory.value / "extra-resources"
|
||||
|
||||
sbt collects :key:`resources` from :key:`unmanagedResourceDirectories`, which by default consists of :key:`resourceDirectory`.
|
||||
Add a directory to :key:`unmanagedResourceDirectories` in the appropriate configuration to add another resource directory.
|
||||
For example, to add `extra-resources` to be an additional directory containing main resources, ::
|
||||
|
||||
unmanagedResourceDirectories in Compile += baseDirectory.value / "extra-resources"
|
||||
|
||||
.. note::
|
||||
|
||||
This directory should only contain unmanaged resources, which are resources that are manually created and managed.
|
||||
See :doc:`/Howto/generatefiles` for working with automatically generated resources.
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: source-include-filter
|
||||
:title: Include/exclude files in the source directory
|
||||
:type: setting
|
||||
|
||||
includeFilter in unmanagedSources := "*.scala" || "*.java"
|
||||
|
||||
When sbt traverses :key:`unmanagedSourceDirectories` for sources, it only includes directories and files that match :key:`includeFilter` and do not match :key:`excludeFilter`.
|
||||
:key:`includeFilter` and :key:`excludeFilter` have type `java.io.FileFilter` and sbt :ref:`provides some useful combinators <file-filter>` for constructing a `FileFilter`.
|
||||
For example, in addition to the default hidden files exclusion, the following also ignores files containing `impl` in their name, ::
|
||||
|
||||
excludeFilter in unmanagedSources := HiddenFileFilter || "*impl*"
|
||||
|
||||
To have different filters for main and test libraries, configure `Compile` and `Test` separately: ::
|
||||
|
||||
includeFilter in (Compile, unmanagedSources) := "*.scala" || "*.java"
|
||||
|
||||
includeFilter in (Test, unmanagedSources) := HiddenFileFilter || "*impl*"
|
||||
|
||||
.. note::
|
||||
|
||||
By default, sbt includes `.scala` and `.java` sources, excluding hidden files.
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: resource-include-filter
|
||||
:title: Include/exclude files in the resource directory
|
||||
:type: setting
|
||||
|
||||
includeFilter in unmanagedResources := "*.txt" || "*.html"
|
||||
|
||||
When sbt traverses :key:`unmanagedResourceDirectories` for resources, it only includes directories and files that match :key:`includeFilter` and do not match :key:`excludeFilter`.
|
||||
:key:`includeFilter` and :key:`excludeFilter` have type `java.io.FileFilter` and sbt :ref:`provides some useful combinators <file-filter>` for constructing a `FileFilter`.
|
||||
For example, in addition to the default hidden files exclusion, the following also ignores files containing `impl` in their name, ::
|
||||
|
||||
excludeFilter in unmanagedSources := HiddenFileFilter || "*impl*"
|
||||
|
||||
To have different filters for main and test libraries, configure `Compile` and `Test` separately: ::
|
||||
|
||||
includeFilter in (Compile, unmanagedSources) := "*.txt"
|
||||
|
||||
includeFilter in (Test, unmanagedSources) := "*.html"
|
||||
|
||||
.. note::
|
||||
|
||||
By default, sbt includes all files that are not hidden.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. howto::
|
||||
:id: lib-include-filter
|
||||
:title: Include only certain (unmanaged) libraries
|
||||
:type: setting
|
||||
|
||||
includeFilter in unmanagedJars := "*.jar" || "*.zip"
|
||||
|
||||
When sbt traverses :key:`unmanagedBase` for resources, it only includes directories and files that match :key:`includeFilter` and do not match :key:`excludeFilter`.
|
||||
:key:`includeFilter` and :key:`excludeFilter` have type `java.io.FileFilter` and sbt :ref:`provides some useful combinators <file-filter>` for constructing a `FileFilter`.
|
||||
For example, in addition to the default hidden files exclusion, the following also ignores zips, ::
|
||||
|
||||
excludeFilter in unmanagedJars := HiddenFileFilter || "*.zip"
|
||||
|
||||
To have different filters for main and test libraries, configure `Compile` and `Test` separately: ::
|
||||
|
||||
includeFilter in (Compile, unmanagedJars) := "*.jar"
|
||||
|
||||
includeFilter in (Test, unmanagedJars) := "*.jar" || "*.zip"
|
||||
|
||||
.. note::
|
||||
|
||||
By default, sbt includes jars, zips, and native dynamic libraries, excluding hidden files.
|
||||
Loading…
Reference in New Issue