From b3bf74d2722dc32628c42aa8ddf5146667c3c867 Mon Sep 17 00:00:00 2001 From: Mark Harrah Date: Fri, 10 May 2013 16:27:13 -0400 Subject: [PATCH] Docs: cleanup related to generating sources+resources --- src/sphinx/Detailed-Topics/Best-Practices.rst | 2 +- src/sphinx/Howto/generatefiles.rst | 4 +- src/sphinx/Howto/package.rst | 2 + src/sphinx/faq.rst | 45 +------------------ 4 files changed, 6 insertions(+), 47 deletions(-) diff --git a/src/sphinx/Detailed-Topics/Best-Practices.rst b/src/sphinx/Detailed-Topics/Best-Practices.rst index abd9a2269..24a30c7e0 100644 --- a/src/sphinx/Detailed-Topics/Best-Practices.rst +++ b/src/sphinx/Detailed-Topics/Best-Practices.rst @@ -56,7 +56,7 @@ 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. -For generating sources and resources, see :ref:`the faq entry `. +For generating sources and resources, see :doc:`/Howto/generatefiles`. Don't hard code ~~~~~~~~~~~~~~~ diff --git a/src/sphinx/Howto/generatefiles.rst b/src/sphinx/Howto/generatefiles.rst index 057e2c734..2cd4f8878 100644 --- a/src/sphinx/Howto/generatefiles.rst +++ b/src/sphinx/Howto/generatefiles.rst @@ -37,7 +37,7 @@ As a specific example, the following generates a hello world source file: Executing 'run' will print "Hi". Change ``Compile`` to ``Test`` to make it a test source. For efficiency, you would only want to generate sources when necessary and not every run. -By default, generated sources are not included in the packaged source artifact. To do so, add them as you would other mappings. See ``Adding files to a package``. +By default, generated sources are not included in the packaged source artifact. To do so, add them as you would other mappings. See :ref:`Adding files to a package `. .. howto:: :id: resources @@ -73,4 +73,4 @@ As a specific example, the following generates a properties file containing the Change ``Compile`` to ``Test`` to make it a test resource. Normally, you would only want to generate resources when necessary and not every run. -By default, generated resources are not included in the packaged source artifact. To do so, add them as you would other mappings. See the ``Adding files to a package`` section. +By default, generated resources are not included in the packaged source artifact. To do so, add them as you would other mappings. See :ref:`Adding files to a package `. diff --git a/src/sphinx/Howto/package.rst b/src/sphinx/Howto/package.rst index 9472d7db8..f5d3f67d0 100644 --- a/src/sphinx/Howto/package.rst +++ b/src/sphinx/Howto/package.rst @@ -71,6 +71,8 @@ The ``artifactName`` setting controls the name of generated packages. See the : mappings in (Compile, packageBin) += { ( baseDirectory.value / "example.txt") -> "out/example.txt" } +.. _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", :: diff --git a/src/sphinx/faq.rst b/src/sphinx/faq.rst index b293b2019..8c3489419 100644 --- a/src/sphinx/faq.rst +++ b/src/sphinx/faq.rst @@ -282,53 +282,10 @@ to the ``managedSource`` directory, the mapping function would have to be adjusted to try relativizing against additional directories or something more appropriate for the generator. -.. _generate-sources-resources: - How can I generate source code or resources? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -sbt provides standard hooks for adding source or resource generation -tasks. A generation task should generate sources in a subdirectory of -``sourceManaged`` for sources or ``resourceManaged`` for resources and -return a sequence of files generated. The key to add the task to is -called ``sourceGenerators`` for sources and ``resourceGenerators`` for -resources. It should be scoped according to whether the generated files -are main (``Compile``) or test (``Test``) sources or resources. This -basic structure looks like: - -:: - - sourceGenerators in Compile += - -For example, assuming a method -``def makeSomeSources(base: File): Seq[File]``, - -:: - - sourceGenerators in Compile += Def.task { - makeSomeSources( (sourceManaged in Compile).value / "demo") - } - -As a specific example, the following generates a hello world source -file: - -:: - - sourceGenerators in Compile += Def.task { - val file = (sourceManaged in Compile) / "demo" / "Test.scala" - IO.write(file, """object Test extends App { println("Hi") }""") - Seq(file) - } - -Executing 'run' will print "Hi". Change ``Compile`` to ``Test`` to make -it a test source. To generate resources, change ``sourceGenerators`` to -``resourceGenerators`` and ``sourceManaged`` to ``resourceManaged``. -Normally, you would only want to generate sources when necessary and not -every run. - -By default, generated sources and resources are not included in the -packaged source artifact. To do so, add them as you would other -mappings. See the ``Adding files to a package`` section. +See :doc:`/Howto/generatefiles`. How can a task avoid redoing work if the input files are unchanged? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~