From 8716a9af6698872548f55789b8cac557278cef7b Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Tue, 18 Oct 2011 13:09:21 -0400 Subject: [PATCH] Group "getting started" pages by prefix and directory The directory will allow a separate _Sidebar.md for the Getting Started. The redundant prefixes are required because gollum URLs don't have the directory. --- Cross-Build.md | 2 +- Full-Configuration.md | 2 +- .../Getting-Started-Basic-Def.md | 20 +++++++------- .../Getting-Started-Custom-Settings.md | 20 +++++++------- .../Getting-Started-Directories.md | 10 +++---- .../Getting-Started-Full-Def.md | 13 +++++----- .../Getting-Started-Hello.md | 6 ++--- .../Getting-Started-Library-Dependencies.md | 9 ++++--- .../Getting-Started-More-About-Settings.md | 14 +++++----- .../Getting-Started-Multi-Project.md | 10 +++---- .../Getting-Started-Running.md | 4 +-- .../Getting-Started-Scopes.md | 18 ++++++------- .../Getting-Started-Setup.md | 8 +++--- .../Getting-Started-Summary.md | 10 +++---- .../Getting-Started-Using-Plugins.md | 14 +++++----- Home.md | 10 +++---- Index.md | 4 +-- Library-Management.md | 4 +-- Migrating-from-SBT-0.7.x-to-0.10.x.md | 4 +-- Needs-New-Home.md | 2 +- Nightly-Builds.md | 4 +-- Recipe:-Install-SBT.md | 2 +- Scripts.md | 4 +-- Testing.md | 2 +- _Sidebar.md | 26 +++++++++---------- 25 files changed, 112 insertions(+), 110 deletions(-) rename Basic-Build-Definition.md => Getting-Started/Getting-Started-Basic-Def.md (89%) rename Custom-Settings-and-Tasks.md => Getting-Started/Getting-Started-Custom-Settings.md (77%) rename Directory-Structure.md => Getting-Started/Getting-Started-Directories.md (84%) rename Full-Build-Definition.md => Getting-Started/Getting-Started-Full-Def.md (94%) rename Hello-World.md => Getting-Started/Getting-Started-Hello.md (88%) rename Library-Dependencies.md => Getting-Started/Getting-Started-Library-Dependencies.md (95%) rename More-About-Settings.md => Getting-Started/Getting-Started-More-About-Settings.md (96%) rename Multi-Project-Builds.md => Getting-Started/Getting-Started-Multi-Project.md (93%) rename Running.md => Getting-Started/Getting-Started-Running.md (94%) rename Scopes.md => Getting-Started/Getting-Started-Scopes.md (94%) rename Setup.md => Getting-Started/Getting-Started-Setup.md (81%) rename Summary.md => Getting-Started/Getting-Started-Summary.md (89%) rename Using-Plugins.md => Getting-Started/Getting-Started-Using-Plugins.md (93%) diff --git a/Cross-Build.md b/Cross-Build.md index 95eb846..f74208e 100644 --- a/Cross-Build.md +++ b/Cross-Build.md @@ -67,4 +67,4 @@ libraryDependencies <<= (scalaVersion, libraryDependencies) { (sv, deps) => This works because your project definition is reloaded for each version of Scala you are building against. `scalaVersion` contains the current version of Scala being used to build the project. -As a final note, you can use `++ ` to temporarily switch the Scala version currently being used to build (see [[Running]] for details). +As a final note, you can use `++ ` to temporarily switch the Scala version currently being used to build (see [[Running|Getting Started Running]] for details). diff --git a/Full-Configuration.md b/Full-Configuration.md index 4a2ca2a..5b0fb04 100644 --- a/Full-Configuration.md +++ b/Full-Configuration.md @@ -159,7 +159,7 @@ Additionally, there are implicit conversions `URI => RootProject` and `File => R External, remote builds are retrieved or checked out to a staging directory in the user's `.sbt` directory so that they can be manipulated like local builds. Examples of using project references follow in the next sections. -When using external projects, the `sbt.boot.directory` should be set (see [[Setup]]) so that unnecessary recompilations do not occur (see [#35]). +When using external projects, the `sbt.boot.directory` should be set (see [[Setup|Getting Started Setup]]) so that unnecessary recompilations do not occur (see [#35]). ### Execution Dependency diff --git a/Basic-Build-Definition.md b/Getting-Started/Getting-Started-Basic-Def.md similarity index 89% rename from Basic-Build-Definition.md rename to Getting-Started/Getting-Started-Basic-Def.md index 326f6d2..e306c1d 100644 --- a/Basic-Build-Definition.md +++ b/Getting-Started/Getting-Started-Basic-Def.md @@ -3,7 +3,7 @@ # Basic Build Definition This page describes sbt build definitions, including some "theory" and the -syntax of `build.sbt`. It assumes you know how to [[use sbt|Running]] and +syntax of `build.sbt`. It assumes you know how to [[use sbt|Getting Started Running]] and have read the previous pages in the Getting Started category. ## Basic vs. Full Definition @@ -17,7 +17,7 @@ use `.scala` files only to contain what can't be done in `.sbt`: - to define nested sub-projects This page discusses "basic" build definition, that is, `.sbt` files. See -[[Full Build Definition]] (later in Getting Started) for more on full build +[[full build definition|Getting Started Full Def]] (later in Getting Started) for more on full build files and how they relate to basic build files. ## What is a build definition? @@ -109,16 +109,16 @@ Keys are just fields in an object called [Keys]. A `build.sbt` implicitly has an `import sbt.Keys._`, so `sbt.Keys.name` can be referred to as `name`. Custom keys could also be defined in a -[[full build definition|Full Build Definition]] or a [[plugin|Using Plugins]]. +[[full build definition|Getting Started Full Def]] or a [[plugin|Getting Started Using Plugins]]. ## Other ways to transform settings Replacement with `:=` is the simplest transformation, but there are several others. For example you can append to a list value with `+=`. -The other transformations require an understanding of [[scopes|Scopes]], so the -[[next section|Scopes]] is about scopes and the -[[section after that|More About Settings]] goes into more detail about settings. +The other transformations require an understanding of [[scopes|Getting Started Scopes]], so the +[[next section|Getting Started Scopes]] is about scopes and the +[[section after that|Getting Started More About Settings]] goes into more detail about settings. ## Task Keys @@ -164,7 +164,7 @@ creates a value of type `T` when the task executes. The `T` vs. `Task[T]` type difference has this implication: a setting key can't depend on a task key, because a setting key is cached, and not -re-run. More on this in [[More About Settings]], coming up soon. +re-run. More on this in [[more about settings|Getting Started More About Settings]], coming up soon. ## Keys in sbt interactive mode @@ -203,11 +203,11 @@ import Process._ import Keys._ ``` -(In addition, if you have a [[full build definition|Full Build Definition]], +(In addition, if you have a [[full build definition|Getting Started Full Def]], the contents of any `Build` or `Plugin` objects in that definition will be imported. More on that when we get to -[[full build definitions|Full Build Definition]].) +[[full build definitions|Getting Started Full Def]].) ## Next -Move on to [[learn about scopes|Scopes]]. +Move on to [[learn about scopes|Getting Started Scopes]]. diff --git a/Custom-Settings-and-Tasks.md b/Getting-Started/Getting-Started-Custom-Settings.md similarity index 77% rename from Custom-Settings-and-Tasks.md rename to Getting-Started/Getting-Started-Custom-Settings.md index 0a42e14..b67267c 100644 --- a/Custom-Settings-and-Tasks.md +++ b/Getting-Started/Getting-Started-Custom-Settings.md @@ -7,7 +7,7 @@ This page gets you started creating your own settings and tasks. Be sure you've read earlier pages in the Getting Started series, especially -[[build.sbt|Basic Build Definition]] and [[More About Settings]], before +[[build.sbt|Getting Started Basic Def]] and [[more about settings|Getting Started More About Settings]], before reading this page. ## Defining a key @@ -16,7 +16,7 @@ reading this page. keys. Most of the keys are implemented in [Defaults]. Keys have one of three types. `SettingKey` and `TaskKey` are described in -[[Basic Build Definition]]. Read about `InputKey` on the [[Input Tasks]] +[[basic build definition|Getting Started Basic Def]]. Read about `InputKey` on the [[Input Tasks]] page. Some examples from [Keys]: @@ -30,16 +30,16 @@ The `Key` constructors have two string parameters: the name of the key (`"scala-version"`) and a documentation string (`"The version of scala used for building."`). -Remember from [[Basic Build Definition]] that the type parameter `T` in `SettingKey[T]` +Remember from [[basic build definition|Getting Started Basic Def]] that the type parameter `T` in `SettingKey[T]` indicates the type of value a setting has. `T` in `TaskKey[T]` indicates the -type of the task's result. Also remember from [[Basic Build Definition]] +type of the task's result. Also remember from [[basic build definition|Getting Started Basic Def]] that a setting has a fixed value cached forever, 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 -[[Full Build Definition]]), or in a plugin (as described in -[[Using Plugins]]). +[[full build definition|Getting Started Full Def]]), or in a plugin (as described in +[[using plugins|Getting Started Using Plugins]]). ## Implementing a task @@ -59,13 +59,13 @@ sampleIntTask := { ``` If the task has dependencies, you'd use `<<=` instead of course, as -discussed in [[More About Settings]]. +discussed in [[more about settings|Getting Started More About Settings]]. The hardest part about implementing tasks is often not sbt-specific; tasks are just Scala code. The hard part could be writing the "meat" of your task that does whatever you're trying to do. For example, maybe you're trying to format HTML in which case you might want to use an HTML library (you would -[[add a library dependency to your build definition|Using Plugins]] and +[[add a library dependency to your build definition|Getting Started Using Plugins]] and write code based on the HTML library, perhaps). sbt has some utility libraries and convenience functions, in particular you @@ -89,7 +89,7 @@ intTask ~= { (value: Int) => value + 1 } If you find you have a lot of custom code in `.scala` files, consider moving it to a plugin for re-use across multiple projects. -It's very easy to create a plugin, as [[teased earlier|Using Plugins]] and +It's very easy to create a plugin, as [[teased earlier|Getting Started Using Plugins]] and [[discussed at more length here|Plugins]]. ## Next @@ -97,4 +97,4 @@ It's very easy to create a plugin, as [[teased earlier|Using Plugins]] and This page has been a quick taste; there's much much more about custom tasks on the [[Tasks]] page. -You're at the end of Getting Started! There's a [[brief recap|Summary]]. +You're at the end of Getting Started! There's a [[brief recap|Getting Started Summary]]. diff --git a/Directory-Structure.md b/Getting-Started/Getting-Started-Directories.md similarity index 84% rename from Directory-Structure.md rename to Getting-Started/Getting-Started-Directories.md index 6846b63..80684f6 100644 --- a/Directory-Structure.md +++ b/Getting-Started/Getting-Started-Directories.md @@ -2,13 +2,13 @@ # Directory structure -This page assumes you've [[installed sbt|Setup]] and seen the [[Hello, World|Hello World]]. +This page assumes you've [[installed sbt|Getting Started Setup]] and seen the [[Hello, World|Getting Started Hello]]. ## Base directory In sbt's terminology, the "base directory" is the directory containing the project. So if you created a project `hello` containing `hello/build.sbt` -and `hello/hw.scala` as in the [[Hello, World|Hello World]] example, `hello` +and `hello/hw.scala` as in the [[Hello, World|Getting Started Hello]] example, `hello` is your base directory. ## Source code @@ -46,7 +46,7 @@ You've already seen `build.sbt` in the project's base directory. Other sbt files appear in a `project` subdirectory. `project` can contain `.scala` files, also called -[[full build definitions|Full Build Definition]], when you're doing +[[full build definitions|Getting Started Full Def]], when you're doing something too complex for a `.sbt` file. sbt-launch.jar automatically downloads the Scala compiler, sbt itself, and @@ -64,7 +64,7 @@ have much in `project/boot`. You may see `.sbt` files inside `project/` but they are not equivalent to `.sbt` files in the project's base directory. Explaining this will -[[come later|Full Build Definition]], since you'll need some background +[[come later|Getting Started Full Def]], since you'll need some background information first. ## Build products @@ -84,4 +84,4 @@ These directories are automatically created and managed by sbt and need not be k # Next -Learn about [[running sbt|Running]]. +Learn about [[running sbt|Getting Started Running]]. diff --git a/Full-Build-Definition.md b/Getting-Started/Getting-Started-Full-Def.md similarity index 94% rename from Full-Build-Definition.md rename to Getting-Started/Getting-Started-Full-Def.md index 3c18218..208642c 100644 --- a/Full-Build-Definition.md +++ b/Getting-Started/Getting-Started-Full-Def.md @@ -1,8 +1,8 @@ # Full Build Definition This page is part of a Getting Started series, and it assumes you've read -previous pages in the series, _especially_ [[Basic Build Definition]] and -[[More About Settings]]. +previous pages in the series, _especially_ [[basic build definition|Getting Started Basic Def]] and +[[more about settings|Getting Started More About Settings]]. ## sbt is recursive @@ -79,7 +79,7 @@ _`.sbt` files in the base directory for a project become part of the `project` build definition project also located in that base directory._ `build.sbt`, also known as a -[[basic build definition|Basic Build Definition]], is a convenient shorthand +[[basic build definition|Getting Started Basic Def]], is a convenient shorthand for adding settings to the build definition project. A _full build definition_ is a build definition that includes `.scala` files @@ -207,7 +207,8 @@ nested project inside your main project. `.sbt` ("basic") and `.scala` ("full") 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 [[Multi-Project Builds]]. +build. More on that is coming up in +[[Multi-Project Builds|Getting Started Multi-Project]]. ## The build definition project in interactive mode @@ -246,7 +247,7 @@ this order: - Settings from `Build.settings` and `Project.settings` in your `.scala` files. - Your user-global settings; for example in `~/.sbt/build.sbt` you can define settings affecting _all_ your projects. - - Settings injected by plugins, see [[Using Plugins]] coming up next. + - Settings injected by plugins, see [[using plugins|Getting Started Using Plugins]] coming up next. - Settings from `.sbt` files in the project. - FIXME parse this: "settings that configure the global plugin definition for a project-level plugin definition as if it were declared locally" @@ -256,4 +257,4 @@ build definition. ## Next -Move on to [[Using Plugins]]. +Move on to [[using plugins|Getting Started Using Plugins]]. diff --git a/Hello-World.md b/Getting-Started/Getting-Started-Hello.md similarity index 88% rename from Hello-World.md rename to Getting-Started/Getting-Started-Hello.md index 9d3eb64..0f724e6 100644 --- a/Hello-World.md +++ b/Getting-Started/Getting-Started-Hello.md @@ -1,7 +1,7 @@ # Hello, World -This page assumes you've [[installed sbt|Setup]]. +This page assumes you've [[installed sbt|Getting Started Setup]]. ## Create a project directory with source code @@ -54,7 +54,7 @@ version := "1.0" scalaVersion := "2.9.1" ``` -In [[Basic Build Definition]] you'll learn more about how to write a `build.sbt` file. +In [[basic build definition|Getting Started Basic Def]] you'll learn more about how to write a `build.sbt` file. If you plan to package your project in a jar, you will want to set at least the name and version in a `build.sbt`. @@ -74,5 +74,5 @@ confusion. # Next -Learn about the [[file and directory layout|Directory Structure]] of an sbt project. +Learn about the [[file and directory layout|Getting Started Directories]] of an sbt project. diff --git a/Library-Dependencies.md b/Getting-Started/Getting-Started-Library-Dependencies.md similarity index 95% rename from Library-Dependencies.md rename to Getting-Started/Getting-Started-Library-Dependencies.md index bdc52e7..95505e1 100644 --- a/Library-Dependencies.md +++ b/Getting-Started/Getting-Started-Library-Dependencies.md @@ -10,7 +10,8 @@ # Library Dependencies This page assumes you've read the earlier Getting Started pages, in particular -[[Basic Build Definition]], [[Scopes]], and [[More About Settings]]. +[[basic build definition|Getting Started Basic Def]], +[[scopes|Getting Started Scopes]], and [[more about settings|Getting Started More About Settings]]. Library dependencies can be added in two ways: @@ -34,7 +35,7 @@ Dependencies in `lib` go on all the classpaths (for `compile`, `test`, those, you would adjust `dependencyClasspath in Compile` or `dependencyClasspath in Runtime` for example. You could use `~=` to get the previous classpath value, filter some entries out, and return a new -classpath value. See [[More About Settings]] for details of `~=`. +classpath value. See [[more about settings|Getting Started More About Settings]] for details of `~=`. There's nothing to add to `build.sbt` to use unmanaged dependencies, though you could change the `unmanaged-base` key if you'd like to use a different @@ -48,7 +49,7 @@ unmanagedBase <<= baseDirectory { base => base / "custom_lib" } `baseDirectory` is the project's root directory, so here you're changing `unmanagedBase` depending on `baseDirectory`, using `<<=` as explained in -[[More About Settings]]. +[[more about settings|Getting Started More About Settings]]. There's also an `unmanaged-jars` task which lists the jars from the `unmanaged-base` directory. If you wanted to use multiple directories or do @@ -226,4 +227,4 @@ dependencies [[on this page|Library-Management]], if you didn't find an answer on this introductory page. If you're reading Getting Started in order, for now, you might move on to -read [[Full Build Definition]]. +read [[full build definition|Getting Started Full Def]]. diff --git a/More-About-Settings.md b/Getting-Started/Getting-Started-More-About-Settings.md similarity index 96% rename from More-About-Settings.md rename to Getting-Started/Getting-Started-More-About-Settings.md index 103d7c4..7a2d170 100644 --- a/More-About-Settings.md +++ b/Getting-Started/Getting-Started-More-About-Settings.md @@ -4,18 +4,18 @@ # More Kinds of Setting This page explains other ways to create a `Setting`, beyond the basic `:=` -method. It assumes you've read [[Basic Build Definition]] and [[Scopes]]. +method. It assumes you've read [[basic build definition|Getting Started Basic Def]] and [[scopes|Getting Started Scopes]]. ## Refresher: Settings -[[Remember|Basic Build Definition]], a build definition creates a list of +[[Remember|Getting Started Basic Def]], a build definition creates a list of `Setting`, which is then used to transform sbt's description of the build (which is a map of key-value pairs). A `Setting` is a transformation with sbt's earlier map as input and a new map as output. The new map becomes sbt's new state. Different settings transform the map in different -ways. [[Earlier|Basic Build Definition]], you read about the `:=` method. +ways. [[Earlier|Getting Started Basic Def]], you read about the `:=` method. The `Setting` which `:=` creates puts a fixed, constant value in the new, transformed map. For example, if you transform a map with the setting @@ -24,7 +24,7 @@ transformed map. For example, if you transform a map with the setting Settings must end up in the master list of settings to do any good (all lines in a `build.sbt` automatically end up in the list, but in a -[[full build definition|Full Build Definition]] you can get it wrong). +[[full build definition|Getting Started Full Def]] you can get it wrong). ## Appending to previous values: `+=` and `++=` @@ -264,14 +264,14 @@ Whenever a setting uses `~=` or `<<=` to create a dependency on itself or another key's value, the value it depends on must exist. If it does not, sbt will complain. It might say _"Reference to undefined setting"_, for example. When this happens, be sure you're using the key in the -[[scope|Scopes]] that defines it. +[[scope|Getting Started Scopes]] that defines it. It's possible to create cycles, which is an error; sbt will tell you if you do this. ### Tasks with dependencies -As noted in [[Basic Build Definition]], task keys create a +As noted in [[more about settings|Getting Started Basic Def]], task keys create a `Setting[Task[T]]` rather than a `Setting[T]` when you build a setting with `:=`, `<<=`, etc. Similarly, task keys are instances of `Initialize[Task[T]]` rather than `Initialize[T]` and `<<=` on a task key @@ -404,4 +404,4 @@ cleanFiles <+= (name) { n => file("coverage-report-" + n + ".txt") } At this point you know how to get things done with settings, so we can move on to a specific key that comes up often: `libraryDependencies`. -[[Learn about library dependencies|Library Dependencies]]. +[[Learn about library dependencies|Getting Started Library Dependencies]]. diff --git a/Multi-Project-Builds.md b/Getting-Started/Getting-Started-Multi-Project.md similarity index 93% rename from Multi-Project-Builds.md rename to Getting-Started/Getting-Started-Multi-Project.md index 3d65109..48b74c1 100644 --- a/Multi-Project-Builds.md +++ b/Getting-Started/Getting-Started-Multi-Project.md @@ -4,7 +4,7 @@ This page introduces multiple projects in a single build. It's part of a Getting Started series. Please read the earlier pages in the series first, in particular you need to understand -[[build.sbt|Basic Build Definition]] and [[Full Build Definition]] before +[[build.sbt|Getting Started Basic Def]] and [[full build definition|Getting Started Full Def]] before reading this page. ## Multiple projects @@ -47,7 +47,7 @@ with type `Project` in the `Build` object. Because project `hello-foo` is defined with `base = file("foo")`, it will be contained in the subdirectory `foo`. Its sources could be directly under `foo`, like `foo/Foo.scala`, or in `foo/src/main/scala`. The usual sbt -[[directory structure|Directory Structure]] applies underneath `foo` with +[[directory structure|Getting Started Directories]] applies underneath `foo` with the exception of build definition files. Any `.sbt` files in `foo`, say `foo/build.sbt`, will be merged with the @@ -73,7 +73,7 @@ defined): `hello-foo/*:version` was defined in `hello/foo/build.sbt`, `hello-bar/*:version` was defined in `hello/bar/build.sbt`, and `hello/*:version` was defined in `hello/build.sbt`. Remember the -[[syntax for scoped keys|Scopes]]. Each `version` key is scoped to a +[[syntax for scoped keys|Getting Started Scopes]]. Each `version` key is scoped to a project, based on the location of the `build.sbt`. But all three `build.sbt` are part of the same build definition. @@ -107,7 +107,7 @@ aggregate in update := false ``` `aggregate in update` is the `aggregate` key scoped to the `update` task, -see [[Scopes]]. +see [[scopes|Getting Started Scopes]]. Note: aggregation will run the aggregated tasks in parallel and with no defined ordering. @@ -161,4 +161,4 @@ have to compile the root project, you could compile only a subproject. ## Next -Move on to create [[Custom Settings and Tasks]]. +Move on to create [[custom settings|Getting Started Custom Settings]]. diff --git a/Running.md b/Getting-Started/Getting-Started-Running.md similarity index 94% rename from Running.md rename to Getting-Started/Getting-Started-Running.md index 29fa671..7a57f1d 100644 --- a/Running.md +++ b/Getting-Started/Getting-Started-Running.md @@ -1,7 +1,7 @@ # Running This page describes how to use `sbt` once you have set up your project. It -assumes you've [[installed sbt|Setup]] and created a [[Hello, World|Hello World]] or other project. +assumes you've [[installed sbt|Getting Started Setup]] and created a [[Hello, World|Getting Started Hello]] or other project. ## Interactive mode @@ -107,4 +107,4 @@ commands are also supported: ## Next -Move on to [[understanding build.sbt|Basic Build Definition]]. +Move on to [[understanding build.sbt|Getting Started Basic Def]]. diff --git a/Scopes.md b/Getting-Started/Getting-Started-Scopes.md similarity index 94% rename from Scopes.md rename to Getting-Started/Getting-Started-Scopes.md index e8c14b7..d15dda6 100644 --- a/Scopes.md +++ b/Getting-Started/Getting-Started-Scopes.md @@ -5,11 +5,11 @@ http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism # Scopes This page describes scopes. It assumes you've read and understood the -previous page, [[Basic Build Definition]]. +previous page, [[basic build definition|Getting Started Basic Def]]. ## The whole story about keys -[[Previously|Basic Build Definition]] we pretended that a key like `name` +[[Previously|Getting Started Basic Def]] we pretended that a key like `name` corresponded to one entry in sbt's map of key-value pairs. This was a simplification. @@ -32,7 +32,7 @@ according to scope. However, there is a single value for a given _scoped_ key. If you think about sbt processing a list of settings to generate a key-value -map describing the project, as [[discussed earlier|Basic Build Definition]], +map describing the project, as [[discussed earlier|Getting Started Basic Def]], the keys in that key-value map are _scoped_ keys. Each setting defined in the build definition (for example in `build.sbt`) applies to a scoped key as well. @@ -53,7 +53,7 @@ There are three scope axes: ### Scoping by project axis -If you [[put multiple projects in a single build|Multi-Project Builds]], each +If you [[put multiple projects in a single build|Getting Started Multi-Project]], each project needs its own settings. That is, keys can be scoped according to the project. @@ -66,7 +66,7 @@ setting. A _configuration_ defines a flavor of build, potentially with its own classpath, sources, generated packages, etc. The configuration concept comes -from Ivy, which sbt uses for [[managed dependencies|Library Dependencies]], and +from Ivy, which sbt uses for [[managed dependencies|Getting Started Library Dependencies]], and from [MavenScopes]. Some configurations you'll see in sbt: @@ -188,7 +188,7 @@ $ sbt ``` On the first line, you can see this is a task (as opposed to a setting, as -explained in [[Basic Build Definition]]). The value resulting from the task +explained in [[basic build definition|Getting Started Basic Def]]). The value resulting from the task will have type `scala.collection.Seq[sbt.Attributed[java.io.File]]`. "Provided by" points you to the scoped key that defines the value, in this @@ -197,7 +197,7 @@ is the `full-classpath` key scoped to the `test` configuration and the `{file:/home/hp/checkout/hello/}default-aea33a` project). "Dependencies" may not make sense yet; stay tuned for the -[[next section|More About Settings]]. +[[next section|Getting Started More About Settings]]. You can also see the delegates; if the value were not defined, sbt would search through: @@ -245,7 +245,7 @@ Run sbt and `inspect name` to see that it's provided by `build.sbt` always defines settings for a single project, so the "current project" is the project you're defining in that particular `build.sbt`. -(For [[multi-project builds|Multi-Project Builds]], each project has its own +(For [[multi-project builds|Getting Started Multi-Project]], each project has its own `build.sbt`.) Keys have an overloaded method called `in` used to set the scope. The @@ -317,4 +317,4 @@ project, global config, global task). ## Next -Now that you understand scopes, you can [[learn more about settings|More About Settings]]. +Now that you understand scopes, you can [[learn more about settings|Getting Started More About Settings]]. diff --git a/Setup.md b/Getting-Started/Getting-Started-Setup.md similarity index 81% rename from Setup.md rename to Getting-Started/Getting-Started-Setup.md index a820f2f..f09314d 100644 --- a/Setup.md +++ b/Getting-Started/Getting-Started-Setup.md @@ -11,11 +11,11 @@ Please go in order! Later pages assume you're familiar with earlier concepts. To create an sbt project, you'll need to take these steps: - Install sbt and create a script to launch it. - - Setup a simple [[Hello World]] project + - Setup a simple [[hello world|Getting Started Hello]] project - Create a project directory with source files in it. - Create your build definition. - - Move on to [[Running]] to learn how to run sbt. - - Then move on to [[Basic Build Definition]] to learn more about build definitions. + - Move on to [[running|Getting Started Running]] to learn how to run sbt. + - Then move on to [[basic build definition|Getting Started Basic Def]] to learn more about build definitions. # Installing sbt @@ -54,4 +54,4 @@ If you have any trouble running `sbt`, see [[Setup Notes]] on terminal encodings ## Next -Move on to [[create a simple project|Hello World]]. +Move on to [[create a simple project|Getting Started Hello]]. diff --git a/Summary.md b/Getting-Started/Getting-Started-Summary.md similarity index 89% rename from Summary.md rename to Getting-Started/Getting-Started-Summary.md index b0e4c1f..6f34383 100644 --- a/Summary.md +++ b/Getting-Started/Getting-Started-Summary.md @@ -15,7 +15,7 @@ to know. - the basics of Scala. It's undeniably helpful to be familiar with Scala syntax. [Programming in Scala](http://www.artima.com/shop/programming_in_scala_2ed) written by the creator of Scala is a great introduction. - - [[Basic Build Definition]] + - [[Basic build definition|Getting Started Basic Def]] - your build definition is one big list of `Setting` objects, where a `Setting` transforms the set of key-value pairs sbt uses to perform tasks. - to create a `Setting`, call one of a few methods on a `Key` (the `:=` and @@ -27,7 +27,7 @@ to know. - _tasks_ are special settings where the computation to produce the key's value will be re-run each time you kick off a task. Non-tasks compute the value once and cache it. - - [[Scopes]] + - [[Scopes|Getting Started Scopes]] - each key may have multiple values, in distinct scopes. - scoping may use three axes: configuration, project, and task. - a configuration is a kind of build, such as the main one (`Compile`) or @@ -36,14 +36,14 @@ to know. per-task, or per-configuration. - the per-project axis also supports "entire build" scope. - scopes "fall back to" or delegate to more general scopes. - - Basic vs. [[Full Build Definition]] + - Basic vs. [[Full|Getting Started Full Def]] - put most of your settings in basic (`build.sbt`), but use the full build definition to - [[define multiple subprojects|Multi-Project Builds]], and to factor out + [[define multiple subprojects|Getting Started Multi-Project]], and to factor out common values, objects, and methods. - the build definition is an sbt project in its own right, rooted in the `project` directory. - - [[Plugins|Using Plugins]] are extensions to the build definition + - [[Plugins|Getting Started Using Plugins]] are extensions to the build definition - add plugins with the `addSbtPlugin` method in `project/build.sbt` (NOT `build.sbt` in the project's base directory). diff --git a/Using-Plugins.md b/Getting-Started/Getting-Started-Using-Plugins.md similarity index 93% rename from Using-Plugins.md rename to Getting-Started/Getting-Started-Using-Plugins.md index cd7f469..1e9b6df 100644 --- a/Using-Plugins.md +++ b/Getting-Started/Getting-Started-Using-Plugins.md @@ -2,8 +2,8 @@ This page is part of a Getting Started series. Please read the earlier pages in the series first, in particular you need to understand -[[build.sbt|Basic Build Definition]], [[Library Dependencies]], and -[[Full Build Definition]] before reading this page. +[[build.sbt|Getting Started Basic Def]], [[library dependencies|Getting Started Library Dependencies]], and +[[full build definition|Getting Started Full Def]] before reading this page. ## What is a plugin? @@ -33,8 +33,8 @@ So that's how you do it... read on to understand what's going on. ### How it works Be sure you understand the -[[recursive nature of sbt projects|Full Build Definition]] described -earlier and how to add a [[managed dependency|Library Dependencies]]. +[[recursive nature of sbt projects|Getting Started Full Def]] described +earlier and how to add a [[managed dependency|Getting Started Library Dependencies]]. #### Dependencies for the build definition @@ -110,7 +110,7 @@ def addSbtPlugin(dependency: ModuleID): Setting[Seq[ModuleID]] = libraryDependencies <+= (sbtVersion in update,scalaVersion) { (sbtV, scalaV) => sbtPluginExtra(dependency, sbtV, scalaV) } ``` -Remember from [[More About Settings]] that `<+=` combines `<<=` and `+=`, so +Remember from [[more about settings|Getting Started More About Settings]] that `<+=` combines `<<=` and `+=`, so this builds a value based on other settings, and then appends it to `libraryDependencies`. The value is based on `sbtVersion in update` (sbt's version scoped to the `update` task) and `scalaVersion` (the version of @@ -168,7 +168,7 @@ If a plugin defines settings in the `settings` field of a `Plugin` object, you don't have to do anything to add them. However, plugins often avoid this because you could not control which -projects in a [[multi-project build|Multi-Project Builds]] would use the plugin. +projects in a [[multi-project build|Getting Started Multi-Project]] would use the plugin. sbt provides a method called `seq` which adds a whole batch of settings at once. So if a plugin has something like this: @@ -229,4 +229,4 @@ Some especially popular plugins are: ## Next -Move on to [[multi-project builds|Multi-Project Builds]]. +Move on to [[multi-project builds|Getting Started Multi-Project]]. diff --git a/Home.md b/Home.md index f8fe0fc..1756ca9 100644 --- a/Home.md +++ b/Home.md @@ -2,8 +2,8 @@ sbt is a build tool for Scala and Java projects that aims to do the basics well. ## Features * Easy to set up for simple projects -* [[Basic build definition|Basic Build Definition]] uses a Scala-based "domain-specific language" (DSL) -* More advanced [[full build definitions|Full Build Definition]] and [[extensions|Custom Settings and Tasks]] use the full flexibility of unrestricted Scala code +* [[Basic build definition|Getting Started Basic Def]] uses a Scala-based "domain-specific language" (DSL) +* More advanced [[full build definitions|Getting Started Full Def]] and [[extensions|Getting Started Custom Settings]] use the full flexibility of unrestricted Scala code * Accurate incremental recompilation using information extracted from the compiler * Continuous compilation and testing with [[triggered execution|Triggered Execution]] * Packages and publishes jars @@ -11,21 +11,21 @@ sbt is a build tool for Scala and Java projects that aims to do the basics well. * Supports mixed Scala/[[Java|Java Sources]] projects * Supports [[Testing|testing]] with ScalaCheck, specs, and ScalaTest (JUnit is supported by a plugin) * Starts the Scala REPL with project classes and dependencies on the classpath -* [[Sub-project|Multi-Project Builds]] support (put multiple packages in one project) +* [[Sub-project|Getting Started Multi-Project]] support (put multiple packages in one project) * [[External project|External Projects]] support (list a git repository as a dependency!) * Parallel task execution, including parallel test execution * [[Library management support|Library Management]]: inline declarations, external Ivy or Maven configuration files, or manual management ## Getting Started -To get started, start with [[Setup]], and continue through the other Getting +To get started, start with [[Setup|Getting Started Setup]], and continue through the other Getting Started pages listed in the sidebar on the right. It's best to read in order, as later pages in the Getting Started series build on concepts introduced earlier. _Please read the Getting Started pages._ You will save yourself a _lot_ of time if you have the right understanding of the big picture -up-front. [[Start with setup|Setup]]. +up-front. [[Start with setup|Getting Started Setup]]. If you are familiar with 0.7.x, please see the [[migration page|Migrating from sbt 0.7.x to 0.10.x]]. Documentation for diff --git a/Index.md b/Index.md index 1888def..459df33 100644 --- a/Index.md +++ b/Index.md @@ -33,7 +33,7 @@ # Index This is an index of common methods, types, and values you might find in an sbt build definition. -For command names, see [[Running]]. +For command names, see [[Running|Getting Started Running]]. For available plugins, see [[sbt 0.10 plugins list]]. ## Values and Types @@ -128,4 +128,4 @@ The methods to combine processes start with `#` so that they share the same prec * `run`, `!`, `!!`, `!<`, `lines`, `lines_!` are different ways to start a process once it has been defined. The `lines` variants produce a `Stream[String]` to obtain the output lines. * `#<`, `#<<`, `#>` are used to get input for a process from a source or send the output of a process to a sink. * `#|` is used to pipe output from one process into the input of another. -* `#||`, `#&&`, `###` sequence processes in different ways. \ No newline at end of file +* `#||`, `#&&`, `###` sequence processes in different ways. diff --git a/Library-Management.md b/Library-Management.md index eb601a0..cbc4090 100644 --- a/Library-Management.md +++ b/Library-Management.md @@ -208,7 +208,7 @@ ivyXML := ### Ivy Home Directory By default, sbt uses the standard Ivy home directory location `${user.home}/.ivy2/`. -This can be configured machine-wide, for use by both the sbt launcher and by projects, by setting the system property `sbt.ivy.home` in the sbt startup script (described in [[Setup]]). +This can be configured machine-wide, for use by both the sbt launcher and by projects, by setting the system property `sbt.ivy.home` in the sbt startup script (described in [[Setup|Getting Started Setup]]). For example: @@ -313,4 +313,4 @@ Maven support is dependent on Ivy's support for Maven POMs. Known issues with this support: * Specifying `relativePath` in the `parent` section of a POM will produce an error. -* Ivy ignores repositories specified in the POM. A workaround is to specify repositories inline or in an Ivy `ivysettings.xml` file. \ No newline at end of file +* Ivy ignores repositories specified in the POM. A workaround is to specify repositories inline or in an Ivy `ivysettings.xml` file. diff --git a/Migrating-from-SBT-0.7.x-to-0.10.x.md b/Migrating-from-SBT-0.7.x-to-0.10.x.md index 686e328..2055b70 100644 --- a/Migrating-from-SBT-0.7.x-to-0.10.x.md +++ b/Migrating-from-SBT-0.7.x-to-0.10.x.md @@ -42,7 +42,7 @@ Or (as most users do) with a shell script like: Note, in this script that I have renamed the `sbt-launch.jar` file with the version so that I can continue to use my 0.7.x version for projects that haven't been migrated. I called this script `sbt9`. -For more details see: [[Setup]]. +For more details see: [[Setup|Getting Started Setup]]. # Step 2: A technique for switching an existing project @@ -110,7 +110,7 @@ This does mean that existing solutions for sharing libraries with your favoured ## What are the commands I can use? -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 [[Running]] page for descriptions of common commands and tasks. +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 [[Running|Getting Started Running]] page 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. diff --git a/Needs-New-Home.md b/Needs-New-Home.md index c251193..77d5f12 100644 --- a/Needs-New-Home.md +++ b/Needs-New-Home.md @@ -274,7 +274,7 @@ ivyXML := ### Ivy Home Directory By default, sbt uses the standard Ivy home directory location `${user.home}/.ivy2/`. -This can be configured machine-wide, for use by both the sbt launcher and by projects, by setting the system property `sbt.ivy.home` in the sbt startup script (described in [[Setup]]). +This can be configured machine-wide, for use by both the sbt launcher and by projects, by setting the system property `sbt.ivy.home` in the sbt startup script (described in [[Setup|Getting Started Setup]]). For example: diff --git a/Nightly-Builds.md b/Nightly-Builds.md index ef1ec87..34b848c 100644 --- a/Nightly-Builds.md +++ b/Nightly-Builds.md @@ -4,7 +4,7 @@ Nightly builds are currently being published to . -To use a nightly build, follow the instructions for normal [[Setup]], except: +To use a nightly build, follow the instructions for normal [[Setup|Getting Started Setup]], except: 1. Download the launcher jar from one of the subdirectories of [sbt-launch]. They should be listed in chronological order, so the most recent one will be last. 2. Call your script something like `sbt-nightly` to retain access to a stable `sbt` launcher. @@ -14,4 +14,4 @@ Related to the third point, remember that an `sbt.version` setting in `