From 2ebf9f1a4ae6f6cb7a0485eea2e63d9ce7d5d54a Mon Sep 17 00:00:00 2001 From: Mark Harrah Date: Sun, 16 Jun 2013 10:21:21 -0400 Subject: [PATCH] Docs: fixes, updates, reorganization --- src/sphinx/Community/Opportunities.rst | 27 +- src/sphinx/Detailed-Topics/Best-Practices.rst | 7 +- src/sphinx/Detailed-Topics/Macro-Projects.rst | 22 +- src/sphinx/conf.py | 2 + src/sphinx/faq.rst | 312 +++++++++--------- src/sphinx/home.rst | 24 +- 6 files changed, 190 insertions(+), 204 deletions(-) diff --git a/src/sphinx/Community/Opportunities.rst b/src/sphinx/Community/Opportunities.rst index 634e040dd..07450b07c 100644 --- a/src/sphinx/Community/Opportunities.rst +++ b/src/sphinx/Community/Opportunities.rst @@ -3,8 +3,8 @@ Opportunites ============ Below is a running list of potential areas of contribution. This list -may become out of date quickly, so you may want to check on the mailing -list if you are interested in a specific topic. +may become out of date quickly, so you may want to check on the `mailing list`_ +if you are interested in a specific topic. 1. There are plenty of possible visualization and analysis opportunities. @@ -39,11 +39,7 @@ list if you are interested in a specific topic. the dependencies. It is also easy to extend this to other ways of retrieving projects. Support for svn and hg was a recent contribution, for example. -3. Dependency management is a general area. Working on Apache Ivy itself - is another way to help. For example, I'm pretty sure Ivy is - fundamentally single threaded. Either a) it's not and you can fix sbt - to take advantage of this or b) make Ivy multi-threaded and faster at - resolving dependencies. +3. Dependency management: see `adept`_ 4. If you like parsers, sbt commands and input tasks are written using custom parser combinators that provide tab completion and error handling. Among other things, the efficiency could be improved. @@ -64,9 +60,11 @@ You could make commands that wrap this, like: warn test:run Also, trace is currently an integer, but should really be an abstract -data type. 7. There is more aggressive incremental compilation in sbt -0.12. I expect it to be more difficult to reproduce bugs. It would be -helpful to have a mode that generates a diff between successive +data type. + +7. Each sbt version has more aggressive incremental compilation and +reproducing bugs can be difficult. It would be helpful to +have a mode that generates a diff between successive compilations and records the options passed to scalac. This could be replayed or inspected to try to find the cause. @@ -81,18 +79,15 @@ Documentation repo) but doesn't have anything to link to that explains how to use those. -3. grep the documentation's git checkout for "Wiki Maintenance Note" and work on - some of those +3. API docs are much needed. -4. API docs are much needed. - -5. Find useful answers or types/methods/values in the other docs, and +4. 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. -6. A lot of the pages could probably have better names, and/or little +5. 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/Best-Practices.rst b/src/sphinx/Detailed-Topics/Best-Practices.rst index 24a30c7e0..72c0c3c1b 100644 --- a/src/sphinx/Detailed-Topics/Best-Practices.rst +++ b/src/sphinx/Detailed-Topics/Best-Practices.rst @@ -2,12 +2,7 @@ Best Practices ============== -This page describes best practices for working with sbt. Nontrivial -additions and changes should generally be discussed on the `mailing -list `_ first. -(Because there isn't built-in support for discussing GitHub wiki edits -like normal commits, a subpar suggestion can only be reverted in its -entirety without comment.) +This page describes best practices for working with sbt. ``project/`` vs. ``~/.sbt/`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/src/sphinx/Detailed-Topics/Macro-Projects.rst b/src/sphinx/Detailed-Topics/Macro-Projects.rst index 1446d1117..67fc1bfb1 100644 --- a/src/sphinx/Detailed-Topics/Macro-Projects.rst +++ b/src/sphinx/Detailed-Topics/Macro-Projects.rst @@ -15,11 +15,11 @@ The rest of the page shows example solutions to these problems. Defining the Project Relationships ================================== -The macro implementation will go in a subproject in the `macro/` directory. +The macro implementation will go in a subproject in the ``macro/`` directory. The main project in the project's base directory will depend on this subproject and use the macro. This configuration is shown in the following build definition: -`project/Build.scala` +``project/Build.scala`` :: @@ -34,11 +34,11 @@ This configuration is shown in the following build definition: } -This specifies that the macro implementation goes in `macro/src/main/scala/` and tests go in `macro/src/test/scala/`. +This specifies that the macro implementation goes in ``macro/src/main/scala/`` and tests go in ``macro/src/test/scala/``. It also shows that we need a dependency on the compiler for the macro implementation. -As an example macro, we'll use `desugar` from `macrocosm `_. +As an example macro, we'll use ``desugar`` from `macrocosm `_. -`macro/src/main/scala/demo/Demo.scala` +``macro/src/main/scala/demo/Demo.scala`` :: @@ -84,12 +84,12 @@ This can be then be run at the console: > macro/test:run immutable.this.List.apply[Int](1, 2, 3).reverse -Actual tests can be defined and run as usual with `macro/test`. +Actual tests can be defined and run as usual with ``macro/test``. The main project can use the macro in the same way that the tests do. For example, -`src/main/scala/MainUsage.scala` +``src/main/scala/MainUsage.scala`` :: @@ -123,7 +123,7 @@ For example, the project definitions from above would look like: ) lazy val commonSub = Project("common", file("common")) -Code in `common/src/main/scala/` is available for both the `macro` and `main` projects to use. +Code in ``common/src/main/scala/`` is available for both the ``macro`` and ``main`` projects to use. Distribution ============ @@ -135,14 +135,14 @@ For example, the `main` Project definition above would now look like: lazy val main = Project("main", file(".")) dependsOn(macroSub) settings( // include the macro classes and resources in the main jar - mappings in (Compile, packageBin) <++= mappings in (macroSub, Compile, packageBin), + mappings in (Compile, packageBin) ++= mappings.in(macroSub, Compile, packageBin).value, // include the macro sources in the main source jar - mappings in (Compile, packageSrc) <++= mappings in (macroSub, Compile, packageSrc) + mappings in (Compile, packageSrc) ++= mappings.in(macroSub, Compile, packageSrc).value ) 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 ``publish`` and ``publishLocal`` to do nothing: :: diff --git a/src/sphinx/conf.py b/src/sphinx/conf.py index ae8fee3ff..6e922bf94 100644 --- a/src/sphinx/conf.py +++ b/src/sphinx/conf.py @@ -92,6 +92,8 @@ rst_epilog = """ .. _RPM: %(sbt_native_package_base)s/%(version)s/sbt.rpm .. |nightly-launcher| replace:: <%(launcher_snapshots_base)s .. _mailing list: http://groups.google.com/group/simple-build-tool/topics +.. _adept: https://groups.google.com/group/adept-dev/topics +.. _Stack Overflow: http://stackoverflow.com/tags/sbt .. _source code: http://github.com/sbt/sbt """ % { 'launcher_release_base': launcher_release_base, diff --git a/src/sphinx/faq.rst b/src/sphinx/faq.rst index 8faefa713..fb995fdfa 100644 --- a/src/sphinx/faq.rst +++ b/src/sphinx/faq.rst @@ -7,7 +7,7 @@ Project Information How do I get help? ~~~~~~~~~~~~~~~~~~ -Please use the `mailing list`_ for questions, comments, and discussions. +Please use `Stack Overflow`_ for questions. Use the `mailing list`_ for comments and discussions. - Please state the problem or question clearly and provide enough context. Code examples and build transcripts are often useful when @@ -37,154 +37,6 @@ How can I help? :doc:`/Community/Opportunities` page for some ideas, but the most useful contributions are usually ones you want yourself. -For more details on developing sbt, see -`Developing.pdf `_ - -0.7 to 0.10+ Migration ----------------------- - -How do I migrate from 0.7 to 0.10+? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See the :doc:`migration page ` first and -then the following questions. - -Where has 0.7's ``lib_managed`` gone? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, sbt |version| loads managed libraries from your ivy cache without -copying them to a ``lib_managed`` directory. This fixes some bugs with -the previous solution and keeps your project directory small. If you -want to insulate your builds from the ivy cache being cleared, set -``retrieveManaged := true`` and the dependencies will be copied to -``lib_managed`` as a build-local cache (while avoiding the issues of -``lib_managed`` in 0.7.x). - -This does mean that existing solutions for sharing libraries with your -favoured IDE may not work. There are |version| plugins for IDEs being -developed: - -- IntelliJ IDEA: [[https://github.com/mpeltonen/sbt-idea]] -- Netbeans: [[https://github.com/remeniuk/sbt-netbeans-plugin]] -- Eclipse: [[https://github.com/typesafehub/sbteclipse]] - -What are the commands I can use in |version| vs. 0.7? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For a list of commands, run ``help``. For details on a specific command, -run ``help ``. To view a list of tasks defined on the current -project, run ``tasks``. Alternatively, see the :doc:`Running ` -page in the Getting Started Guide for descriptions of common commands and tasks. - -If in doubt start by just trying the old command as it may just work. -The built in TAB completion will also assist you, so you can just press -TAB at the beginning of a line and see what you get. - -The following commands work pretty much as in 0.7 out of the box: - -.. code-block:: text - - reload - update - compile - test - testOnly - publishLocal - exit - -Why have the resolved dependencies in a multi-module project changed since 0.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`` -run. Use ``show update`` to view a summary of files comprising managed -classpaths. - -My tests all run really fast but some are broken that weren't in 0.7! -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Be aware that compilation and tests run in parallel by default in sbt -|version|. If your test code isn't thread-safe then you may want to change -this behaviour by adding one of the following to your ``build.sbt``: - -:: - - // Execute tests in the current project serially. - // Tests from other projects may still run concurrently. - parallelExecution in Test := false - - // Execute everything serially (including compilation and tests) - parallelExecution := false - -How do I set log levels in |version| vs. 0.7? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``warn``, ``info``, ``debug`` and ``error`` don't work any more. - -The new syntax in the sbt |version| shell is: -``text > set logLevel := Level.Warn`` - -Or in your ``build.sbt`` file write: - -:: - - logLevel := Level.Warn - -What happened to the web development and Web Start support since 0.7? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Web application support was split out into a plugin. See the -`xsbt-web-plugin `_ project. - -For an early version of an xsbt Web Start plugin, visit the -`xsbt-webstart `_ project. - -How are inter-project dependencies different in |version| vs. 0.7? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In |version|, there are three types of project dependencies (classpath, -execution, and configuration) and they are independently defined. These -were combined in a single dependency type in 0.7.x. A declaration like: - -:: - - lazy val a = project("a", "A") - lazy val b = project("b", "B", a) - -meant that the ``B`` project had a classpath and execution dependency on -``A`` and ``A`` had a configuration dependency on ``B``. Specifically, -in 0.7.x: - -1. Classpath: Classpaths for ``A`` were available on the appropriate - classpath for ``B``. -2. Execution: A task executed on ``B`` would be executed on ``A`` first. -3. Configuration: For some settings, if they were not overridden in - ``A``, they would default to the value provided in ``B``. - -In |version|, declare the specific type of dependency you want. Read about -:doc:`multi-project builds ` in the Getting -Started Guide for details. - -Where did class/object X go since 0.7? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -================================================================================================================================================================================================ ===================================================================================================================================================================================== -0.7 |version| -================================================================================================================================================================================================ ===================================================================================================================================================================================== -| `FileUtilities `_ `IO <../api/sbt/IO$.html>`_ -`Path class `_ and `object `_ `Path object <../api/sbt/Path$.html>`_, ``File``, `RichFile <../api/sbt/RichFile.html>`_ -`PathFinder class `_ ``Seq[File]``, `PathFinder class <../api/sbt/PathFinder.html>`_, `PathFinder object <../api/sbt/PathFinder$.html>`_ -================================================================================================================================================================================================ ===================================================================================================================================================================================== - - -Where can I find plugins for |version|? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -See :doc:`/Community/Community-Plugins` for a list of currently available plugins. - Usage ----- @@ -233,10 +85,10 @@ You may run ``sbt console``. Build definitions ----------------- -What are the ``:=``, ``+=``, ``++=```, and ``~=`` methods? +What are the ``:=``, ``+=``, ``++=``, and ``~=`` methods? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -These are methods on keys used to construct a ``Setting``. The Getting +These are methods on keys used to construct a ``Setting`` or a ``Task``. The Getting Started Guide covers all these methods, see :doc:`.sbt build definition ` and :doc:`more about settings ` for example. @@ -269,11 +121,12 @@ For example, to add generated sources to the packaged source artifact: :: - mappings in (Compile, packageSrc) <++= - (sourceManaged in Compile, managedSources in Compile) map { (base, srcs) => + mappings in (Compile, packageSrc) ++= { import Path.{flat, relativeTo} - srcs x (relativeTo(base) | flat) - } + val base = (sourceManaged in Compile).value + val srcs = (managedSources in Compile).value + srcs x (relativeTo(base) | flat) + } This takes sources from the ``managedSources`` task and relativizes them against the ``managedSource`` base directory, falling back to a @@ -673,8 +526,10 @@ that files in ``~/.sbt/plugins`` are only to be used by sbt itself, not as part of the general build definition. If you define your plugins in a file under *that* directory, they won't foul up your cross-compilations. Any file name ending in ``.sbt`` will do, but most people use -``~/.sbt/plugins/build.sbt`` or ``~/.sbt/plugins/plugins.sbt``. ## +``~/.sbt/plugins/build.sbt`` or ``~/.sbt/plugins/plugins.sbt``. + Miscellaneous +------------- How do I use the Scala interpreter in my code? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -717,3 +572,148 @@ example: ILoop.breakIf[MyType](a != b, "a" -> a, "b" -> b ) } + +0.7 to 0.10+ Migration +---------------------- + +How do I migrate from 0.7 to 0.10+? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See the :doc:`migration page ` first and +then the following questions. + +Where has 0.7's ``lib_managed`` gone? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, sbt |version| loads managed libraries from your ivy cache without +copying them to a ``lib_managed`` directory. This fixes some bugs with +the previous solution and keeps your project directory small. If you +want to insulate your builds from the ivy cache being cleared, set +``retrieveManaged := true`` and the dependencies will be copied to +``lib_managed`` as a build-local cache (while avoiding the issues of +``lib_managed`` in 0.7.x). + +This does mean that existing solutions for sharing libraries with your +favoured IDE may not work. There are |version| plugins for IDEs being +developed: + +- IntelliJ IDEA: `https://github.com/mpeltonen/sbt-idea`_ +- Netbeans: `https://github.com/remeniuk/sbt-netbeans-plugin`_ +- Eclipse: `https://github.com/typesafehub/sbteclipse`_ + +What are the commands I can use in |version| vs. 0.7? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For a list of commands, run ``help``. For details on a specific command, +run ``help ``. To view a list of tasks defined on the current +project, run ``tasks``. Alternatively, see the :doc:`Running ` +page in the Getting Started Guide for descriptions of common commands and tasks. + +If in doubt start by just trying the old command as it may just work. +The built in TAB completion will also assist you, so you can just press +TAB at the beginning of a line and see what you get. + +The following commands work pretty much as in 0.7 out of the box: + +.. code-block:: text + + reload + update + compile + test + testOnly + publishLocal + exit + +Why have the resolved dependencies in a multi-module project changed since 0.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`` +run. Use ``show update`` to view a summary of files comprising managed +classpaths. + +My tests all run really fast but some are broken that weren't in 0.7! +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Be aware that compilation and tests run in parallel by default in sbt +|version|. If your test code isn't thread-safe then you may want to change +this behaviour by adding one of the following to your ``build.sbt``: + +:: + + // Execute tests in the current project serially. + // Tests from other projects may still run concurrently. + parallelExecution in Test := false + + // Execute everything serially (including compilation and tests) + parallelExecution := false + +How do I set log levels in |version| vs. 0.7? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``warn``, ``info``, ``debug`` and ``error`` don't work any more. + +The new syntax in the sbt |version| shell is: +``text > set logLevel := Level.Warn`` + +Or in your ``build.sbt`` file write: + +:: + + logLevel := Level.Warn + +What happened to the web development and Web Start support since 0.7? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Web application support was split out into a plugin. See the +`xsbt-web-plugin `_ project. + +For an early version of an xsbt Web Start plugin, visit the +`xsbt-webstart `_ project. + +How are inter-project dependencies different in |version| vs. 0.7? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In |version|, there are three types of project dependencies (classpath, +execution, and configuration) and they are independently defined. These +were combined in a single dependency type in 0.7.x. A declaration like: + +:: + + lazy val a = project("a", "A") + lazy val b = project("b", "B", a) + +meant that the ``B`` project had a classpath and execution dependency on +``A`` and ``A`` had a configuration dependency on ``B``. Specifically, +in 0.7.x: + +1. Classpath: Classpaths for ``A`` were available on the appropriate + classpath for ``B``. +2. Execution: A task executed on ``B`` would be executed on ``A`` first. +3. Configuration: For some settings, if they were not overridden in + ``A``, they would default to the value provided in ``B``. + +In |version|, declare the specific type of dependency you want. Read about +:doc:`multi-project builds ` in the Getting +Started Guide for details. + +Where did class/object X go since 0.7? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +================================================================================================================================================================================================ ===================================================================================================================================================================================== +0.7 |version| +================================================================================================================================================================================================ ===================================================================================================================================================================================== +| `FileUtilities `_ `IO <../api/sbt/IO$.html>`_ +`Path class `_ and `object `_ `Path object <../api/sbt/Path$.html>`_, ``File``, `RichFile <../api/sbt/RichFile.html>`_ +`PathFinder class `_ ``Seq[File]``, `PathFinder class <../api/sbt/PathFinder.html>`_, `PathFinder object <../api/sbt/PathFinder$.html>`_ +================================================================================================================================================================================================ ===================================================================================================================================================================================== + + +Where can I find plugins for |version|? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See :doc:`/Community/Community-Plugins` for a list of currently available plugins. diff --git a/src/sphinx/home.rst b/src/sphinx/home.rst index e7ccd3e57..be4e0787f 100644 --- a/src/sphinx/home.rst +++ b/src/sphinx/home.rst @@ -7,8 +7,8 @@ sbt index -sbt is a build tool for Scala and Java projects that aims to do the -basics well. It requires Java 1.6 or later. +sbt is a build tool for Scala, Java, and `more `_. +It requires Java 1.6 or later. Install ------- @@ -18,21 +18,17 @@ See the :doc:`setup instructions `. Features -------- -- Easy to set up for simple projects -- :doc:`.sbt build definition ` uses a - Scala-based "domain-specific language" (DSL) -- More advanced :doc:`.scala build definitions ` - and :doc:`extensions ` use the full - flexibility of unrestricted Scala code +- Little or no configuration required for simple projects +- Scala-based :doc:`build definition ` that can use the full flexibility of Scala code - Accurate incremental recompilation using information extracted from the compiler - Continuous compilation and testing with :doc:`triggered execution ` - Packages and publishes jars - Generates documentation with scaladoc - Supports mixed Scala/:doc:`Java ` projects -- Supports :doc:`testing ` with ScalaCheck, specs, and ScalaTest - (JUnit is supported by a plugin) +- Supports :doc:`testing ` with ScalaCheck, specs, and ScalaTest. + JUnit is supported by a plugin. - Starts the Scala REPL with project classes and dependencies on the classpath -- :doc:`Sub-project ` support (put multiple packages in one project) +- Modularization supported with :doc:`sub-projects ` - External project support (list a git repository as a dependency!) - :doc:`Parallel task execution `, including parallel test execution - :doc:`Library management support `: @@ -45,13 +41,11 @@ To get started, *please read* the :doc:`Getting Started Guide `. -The mailing list is at http://groups.google.com/group/simple-build-tool/topics and should be used for discussions and questions. -Questions may also be asked at `Stack Overflow `_. +`Stack Overflow `_ is preferred for questions. +The `mailing list`_ can be used for comments, discussions, and questions. This documentation can be forked `on GitHub `_. Feel free to make corrections and add documentation. -If you are familiar with 0.7.x, please see the :doc:`migration page `. Documentation for 0.7.x has been `archived here `_. This documentation applies to sbt |version|. -