From d3f8bdb8379f402489476c07dc90943bb868d752 Mon Sep 17 00:00:00 2001 From: Mark Harrah Date: Tue, 9 Apr 2013 13:54:45 -0400 Subject: [PATCH] Docs: move contents of dormant configurations page into Library-Management --- src/sphinx/Community/ChangeSummary_0.13.0.rst | 2 +- src/sphinx/Community/Opportunities.rst | 11 +-- .../Detailed-Topics/Library-Management.rst | 66 +++++++++++++++- src/sphinx/Detailed-Topics/Local-Scala.rst | 2 +- src/sphinx/Detailed-Topics/Testing.rst | 2 +- src/sphinx/Dormant/Configurations.rst | 79 ------------------- .../Getting-Started/Library-Dependencies.rst | 2 + src/sphinx/Name-Index.rst | 4 +- src/sphinx/faq.rst | 2 +- 9 files changed, 76 insertions(+), 94 deletions(-) delete mode 100644 src/sphinx/Dormant/Configurations.rst diff --git a/src/sphinx/Community/ChangeSummary_0.13.0.rst b/src/sphinx/Community/ChangeSummary_0.13.0.rst index 99ac70469..5a50e75e1 100644 --- a/src/sphinx/Community/ChangeSummary_0.13.0.rst +++ b/src/sphinx/Community/ChangeSummary_0.13.0.rst @@ -105,7 +105,7 @@ A similar method ``parsed`` is defined on ``Parser[T]``, ``Initialize[Parser[T]] for(arg <- args) println(" " + arg) } -For details, see :doc:`Extending/Input-Tasks`. +For details, see :doc:`/Extending/Input-Tasks`. To expect a task to fail and get the failing exception, use the ``failure`` method instead of ``value``. This provides an ``Incomplete`` value, which wraps the exception. To get the result of a task whether or not it succeeds, use ``result``, which provides a ``Result[T]``. diff --git a/src/sphinx/Community/Opportunities.rst b/src/sphinx/Community/Opportunities.rst index e683bfe17..634e040dd 100644 --- a/src/sphinx/Community/Opportunities.rst +++ b/src/sphinx/Community/Opportunities.rst @@ -81,21 +81,18 @@ Documentation repo) but doesn't have anything to link to that explains how to use those. -3. the :doc:`/Dormant/Configurations` page is missing a list of the built-in - configurations and the purpose of each. - -4. grep the documentation's git checkout for "Wiki Maintenance Note" and work on +3. grep the documentation's git checkout for "Wiki Maintenance Note" and work on some of those -5. API docs are much needed. +4. API docs are much needed. -6. Find useful answers or types/methods/values in the other docs, and +5. Find useful answers or types/methods/values in the other docs, and pull references to them up into :doc:`/faq` or :doc:`/Name-Index` so people can find the docs. In general the :doc:`/faq` should feel a bit more like a bunch of pointers into the regular docs, rather than an alternative to the docs. -7. A lot of the pages could probably have better names, and/or little +6. A lot of the pages could probably have better names, and/or little 2-4 word blurbs to the right of them in the sidebar. diff --git a/src/sphinx/Detailed-Topics/Library-Management.rst b/src/sphinx/Detailed-Topics/Library-Management.rst index f392e63cf..dfac311bc 100644 --- a/src/sphinx/Detailed-Topics/Library-Management.rst +++ b/src/sphinx/Detailed-Topics/Library-Management.rst @@ -99,7 +99,7 @@ or libraryDependencies += groupID % artifactID % revision % configuration -See :doc:`/Dormant/Configurations` for details on configuration mappings. Also, +See :ref:`configurations ` for details on configuration mappings. Also, several dependencies can be declared together: :: @@ -533,10 +533,72 @@ For example, Publishing ~~~~~~~~~~ -Finally, see :doc:`Publishing` for how to publish your project. +See :doc:`Publishing` for how to publish your project. + +.. _ivy-configurations: + +Configurations +~~~~~~~~~~~~~~ + +Ivy configurations are a useful feature for your build when you need +custom groups of dependencies, such as for a plugin. Ivy configurations +are essentially named sets of dependencies. You can read the +`Ivy documentation `_ +for details. + +The built-in use of configurations in sbt is similar to scopes in Maven. +sbt adds dependencies to different classpaths by the configuration that +they are defined in. See the description of `Maven +Scopes `_ +for details. + +You put a dependency in a configuration by selecting one or more of its +configurations to map to one or more of your project's configurations. +The most common case is to have one of your configurations ``A`` use a +dependency's configuration ``B``. The mapping for this looks like +``"A->B"``. To apply this mapping to a dependency, add it to the end of +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 +documentation `_ +for more advanced mappings. Most projects published to Maven +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: + +:: + + ivyConfigurations += config("js") hide + + libraryDependencies += "jquery" % "jquery" % "1.3.2" % "js->default" from "http://jqueryjs.googlecode.com/files/jquery-1.3.2.min.js" + + resources ++= update.value.select( configurationFilter("js") ) + +The ``config`` method defines a new configuration with name ``"js"`` and +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 +configuration than those. The ScalaTest dependency above can then be +shortened to: + +:: + + libraryDependencies += "org.scala-tools.testing" % "scalatest" % "1.0" % "test" .. _external-maven-ivy: + Maven/Ivy --------- diff --git a/src/sphinx/Detailed-Topics/Local-Scala.rst b/src/sphinx/Detailed-Topics/Local-Scala.rst index 0d90119bf..ef9980ee9 100644 --- a/src/sphinx/Detailed-Topics/Local-Scala.rst +++ b/src/sphinx/Detailed-Topics/Local-Scala.rst @@ -11,7 +11,7 @@ Example: :: - scalaHome := Some(file("/path/to/scala"))`` + scalaHome := Some(file("/path/to/scala")) Using a local Scala version will override the ``scalaVersion`` setting and will not work with :doc:`cross building `. diff --git a/src/sphinx/Detailed-Topics/Testing.rst b/src/sphinx/Detailed-Topics/Testing.rst index 75d910f73..bf3a2ac55 100644 --- a/src/sphinx/Detailed-Topics/Testing.rst +++ b/src/sphinx/Detailed-Topics/Testing.rst @@ -26,7 +26,7 @@ declaring it as a :doc:`managed dependency `: libraryDependencies += "org.scala-tools.testing" %% "scalacheck" % "1.9" % "test" -The fourth component ``"test"`` is the :doc:`configuration ` +The fourth component ``"test"`` is the :ref:`configuration ` and means that ScalaCheck will only be on the test classpath and it isn't needed by the main sources. This is generally good practice for libraries because your users don't typically need your test dependencies diff --git a/src/sphinx/Dormant/Configurations.rst b/src/sphinx/Dormant/Configurations.rst deleted file mode 100644 index 1f0e06ed9..000000000 --- a/src/sphinx/Dormant/Configurations.rst +++ /dev/null @@ -1,79 +0,0 @@ -============== -Configurations -============== - -*Wiki Maintenance Note:* Most of what's on this page is now covered in -:doc:`/Getting-Started/Library-Dependencies`. This page should be analyzed -for any points that aren't covered on the new page, and those points -moved somewhere (maybe the :doc:`/faq` or an "advanced library deps" page). -Then this page could become a redirect with no content except a link -pointing to the new page(s). - -*Wiki Maintenance Note 2:* There probably should be a page called -Configurations that's less about library dependency management and more -about listing all the configurations that exist and describing what they -are used for. This would complement the way this page is linked, for -example in :doc:`/Name-Index`. - -Configurations -============== - -Ivy configurations are a useful feature for your build when you use -managed dependencies. They are essentially named sets of dependencies. -You can read the `Ivy -documentation `_ -for details. Their use in sbt is described on this page. - -Usage -===== - -The built-in use of configurations in sbt is similar to scopes in Maven. -sbt adds dependencies to different classpaths by the configuration that -they are defined in. See the description of `Maven -Scopes `_ -for details. - -You put a dependency in a configuration by selecting one or more of its -configurations to map to one or more of your project's configurations. -The most common case is to have one of your configurations ``A`` use a -dependency's configuration ``B``. The mapping for this looks like -``"A->B"``. To apply this mapping to a dependency, add it to the end of -your dependency definition: - -:: - - libraryDependencies += "org.scalatest" % "scalatest" % "1.2" % "test->compile" - -This says that your project's ``test`` configuration uses -``ScalaTest``'s ``default`` configuration. Again, see the `Ivy -documentation `_ -for more advanced mappings. Most projects published to Maven -repositories will use the ``default`` or ``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: - -:: - - ivyConfigurations += config("js") hide - - libraryDependencies += "jquery" % "jquery" % "1.3.2" % "js->default" from "http://jqueryjs.googlecode.com/files/jquery-1.3.2.min.js" - - resources ++= update.value.select( configurationFilter("js") ) - -The ``config`` method defines a new configuration with name ``"js"`` and -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 -configuration than those. The ScalaTest dependency above can then be -shortened to: - -:: - - libraryDependencies += "org.scala-tools.testing" % "scalatest" % "1.0" % "test" - diff --git a/src/sphinx/Getting-Started/Library-Dependencies.rst b/src/sphinx/Getting-Started/Library-Dependencies.rst index 902e78ee8..3b9302054 100644 --- a/src/sphinx/Getting-Started/Library-Dependencies.rst +++ b/src/sphinx/Getting-Started/Library-Dependencies.rst @@ -210,6 +210,8 @@ ones added by your build definition. Therefore, to change or remove the default resolvers, you would need to override ``externalResolvers`` instead of ``resolvers``. +.. _gsg-ivy-configurations: + Per-configuration dependencies ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/src/sphinx/Name-Index.rst b/src/sphinx/Name-Index.rst index 84cd997f4..7c13829fd 100644 --- a/src/sphinx/Name-Index.rst +++ b/src/sphinx/Name-Index.rst @@ -28,8 +28,8 @@ Dependency Management - A `Configuration <../api/sbt/Configuration.html>`_ is a useful Ivy construct for grouping dependencies. See - :doc:`/Dormant/Configurations`. It is also used for :doc:`scoping settings `. -- ``Compile``, ``Test``, ``Runtime``, ``Provided``, and ``Optional`` are predefined :doc:`/Dormant/Configurations`. + :ref:`ivy-configurations`. It is also used for :doc:`scoping settings `. +- ``Compile``, ``Test``, ``Runtime``, ``Provided``, and ``Optional`` are predefined :ref:`configurations `. Settings and Tasks ~~~~~~~~~~~~~~~~~~ diff --git a/src/sphinx/faq.rst b/src/sphinx/faq.rst index 674207244..1a0101987 100644 --- a/src/sphinx/faq.rst +++ b/src/sphinx/faq.rst @@ -462,7 +462,7 @@ Tool dependencies are used to implement a task and are not needed by project source code. These dependencies can be declared in their own configuration and classpaths. These are the steps: -1. Define a new :doc:`configuration `. +1. Define a new :ref:`configuration `. 2. Declare the tool :doc:`dependencies ` in that configuration. 3. Define a classpath that pulls the dependencies from the :doc:`/Detailed-Topics/Update-Report` produced by ``update``.