diff --git a/src/sphinx/Detailed-Topics/Paths.rst b/src/sphinx/Detailed-Topics/Paths.rst index b9b1fc862..9a74a6dce 100644 --- a/src/sphinx/Detailed-Topics/Paths.rst +++ b/src/sphinx/Detailed-Topics/Paths.rst @@ -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 ------------ diff --git a/src/sphinx/Howto/classpaths.rst b/src/sphinx/Howto/classpaths.rst new file mode 100644 index 000000000..b36f13bb4 --- /dev/null +++ b/src/sphinx/Howto/classpaths.rst @@ -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 `, 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>`_. diff --git a/src/sphinx/Howto/defaultpaths.rst b/src/sphinx/Howto/defaultpaths.rst new file mode 100644 index 000000000..6f645b4ed --- /dev/null +++ b/src/sphinx/Howto/defaultpaths.rst @@ -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 ` 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 ` 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 ` 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.