From d0a8f40b995c46cf4b5df8e5e7662a2165d8e49f Mon Sep 17 00:00:00 2001 From: Mark Harrah Date: Thu, 22 Aug 2013 09:35:28 -0400 Subject: [PATCH] Docs: last updates to getting started guide for 0.13.0 --- src/sphinx/Getting-Started/Basic-Def.rst | 11 ++++------ .../Getting-Started/Custom-Settings.rst | 9 +++----- src/sphinx/Getting-Started/Full-Def.rst | 21 ++++--------------- src/sphinx/Getting-Started/Running.rst | 4 ++-- src/sphinx/Getting-Started/Summary.rst | 7 +++---- src/sphinx/Getting-Started/Using-Plugins.rst | 2 +- 6 files changed, 17 insertions(+), 37 deletions(-) diff --git a/src/sphinx/Getting-Started/Basic-Def.rst b/src/sphinx/Getting-Started/Basic-Def.rst index c7e66064c..734bb6ae2 100644 --- a/src/sphinx/Getting-Started/Basic-Def.rst +++ b/src/sphinx/Getting-Started/Basic-Def.rst @@ -11,14 +11,11 @@ Getting Started Guide. An sbt build definition can contain files ending in `.sbt`, located in the base directory, and files ending in `.scala`, located in the -`project` subdirectory of the base directory. +`project/` subdirectory the base directory. -You can use either one exclusively, or use both. A good approach is to -use `.sbt` files for most purposes, and use `.scala` files only to -contain what can't be done in `.sbt`. - -This page discusses `.sbt` files. See :doc:`.scala build definition ` (later in Getting Started) for -more on `.scala` files and how they relate to `.sbt` files. +This page discusses `.sbt` files, which are suitable for most cases. +The `.scala` files are typically used for sharing code across `.sbt` files and for larger build definitions. +See :doc:`.scala build definition ` (later in Getting Started) for more on `.scala` files. What is a build definition? --------------------------- diff --git a/src/sphinx/Getting-Started/Custom-Settings.rst b/src/sphinx/Getting-Started/Custom-Settings.rst index 16715739d..e5a3e8329 100644 --- a/src/sphinx/Getting-Started/Custom-Settings.rst +++ b/src/sphinx/Getting-Started/Custom-Settings.rst @@ -40,12 +40,9 @@ reload, while a task is re-computed for every "task execution" (every time someone types a command at the sbt interactive prompt or in batch mode). -Keys may be defined in a `.scala` file (as described in :doc:`.scala build definition `), -or in a plugin (as described in -:doc:`using plugins `). Any `val` found in -a `Build` object in your `.scala` build definition files, or any -`val` found in a `Plugin` object from a plugin, will be imported -automatically into your `.sbt` files. +Keys may be defined in a `.sbt file ` file, :doc:`.scala file `, or in a :doc:`plugin `. +Any `val` found in a `Build` object in your `.scala` build definition files or any +`val` found in a `Plugin` object from a plugin will be imported automatically into your `.sbt` files. Implementing a task ------------------- diff --git a/src/sphinx/Getting-Started/Full-Def.rst b/src/sphinx/Getting-Started/Full-Def.rst index fb70b6be9..1c4a612a5 100644 --- a/src/sphinx/Getting-Started/Full-Def.rst +++ b/src/sphinx/Getting-Started/Full-Def.rst @@ -194,24 +194,11 @@ In summary: When to use `.scala` files ---------------------------- -In `.scala` files, you can write any Scala code including `val`, `object`, -and method definitions. +In `.scala` files, you can write any Scala code, including top-level classes and objects. +Also, there are no restrictions on blank lines, since they are standard `.scala` files. -*One recommended approach is to define settings in `.sbt` files, using -`.scala` files when you need to factor out a `val` or `object` or -method definition.* - -There's one build definition, which is a nested project inside your main -project. `.sbt` and `.scala` files are compiled together to create -that single definition. - -`.scala` files are also required to define multiple projects in a -single build. More on that is coming up in :doc:`Multi-Project Builds `. - -(A disadvantage of using `.sbt` files in a :doc:`multi-project build ` is that they'll be spread around -in different directories; for that reason, some people prefer to put -settings in their `.scala` files if they have sub-projects. This will -be clearer after you see how :doc:`multi-project builds ` work.) +The recommended approach is to define most configuration in `.sbt` files, using +`.scala` files for task implementations or to share values, such as keys, across `.sbt` files. The build definition project in interactive mode ------------------------------------------------ diff --git a/src/sphinx/Getting-Started/Running.rst b/src/sphinx/Getting-Started/Running.rst index 0659d0e21..56ff3f0ef 100644 --- a/src/sphinx/Getting-Started/Running.rst +++ b/src/sphinx/Getting-Started/Running.rst @@ -45,9 +45,9 @@ in quotes. For example, $ sbt clean compile "testOnly TestA TestB" -In this example, `test-only` has arguments, `TestA` and `TestB`. +In this example, `testOnly` has arguments, `TestA` and `TestB`. The commands will be run in sequence (`clean`, `compile`, then -`test-only`). +`testOnly`). Continuous build and test ------------------------- diff --git a/src/sphinx/Getting-Started/Summary.rst b/src/sphinx/Getting-Started/Summary.rst index 5d03b906c..c8f8ae0c9 100644 --- a/src/sphinx/Getting-Started/Summary.rst +++ b/src/sphinx/Getting-Started/Summary.rst @@ -41,14 +41,13 @@ sbt: The Core Concepts - the per-project axis also supports "entire build" scope. - scopes fall back to or *delegate* to more general scopes. - :doc:`.sbt ` vs. :doc:`.scala ` build definition -- put most of your settings in `build.sbt`, but use `.scala` build - definition files to :doc:`define multiple subprojects ` - , and to factor out common values, objects, and methods. +- put most of your configuration in `build.sbt`, but use `.scala` build + definition files for defining classes and larger task implementations. - the build definition is an sbt project in its own right, rooted in the `project` directory. - :doc:`Plugins ` are extensions to the build definition -- add plugins with the `addSbtPlugin` method in `project/build.sbt` +- add plugins with the `addSbtPlugin` method in `project/plugins.sbt` (NOT `build.sbt` in the project's base directory). If any of this leaves you wondering rather than nodding, please ask for diff --git a/src/sphinx/Getting-Started/Using-Plugins.rst b/src/sphinx/Getting-Started/Using-Plugins.rst index 7a950aaca..5dfc05db9 100644 --- a/src/sphinx/Getting-Started/Using-Plugins.rst +++ b/src/sphinx/Getting-Started/Using-Plugins.rst @@ -81,7 +81,7 @@ Some especially popular plugins are: Creating a Plugin ----------------- -A minimal plugin is a Scala library that is built against the version of Scala that sbt runs, which is currently |scalaVersion|. +A minimal plugin is a Scala library that is built against the version of Scala for sbt itself, which is currently |scalaVersion|. Nothing special needs to be done for this type of plugin. It can be published as a normal project and declared in `project/plugins.sbt` like a normal dependency (without `addSbtPlugin`).