sbt/website

The source for scala-sbt.org

sbt

sbt is a build tool for Scala, Java, and more.

For general documentation, see https://www.scala-sbt.org/.

sbt 1.x

This is the 1.x series of sbt. The source code of sbt is split across several GitHub repositories, including this one.

• sbt/io hosts sbt.io module.
• sbt/librarymanagement hosts sbt.librarymanagement module that wraps Ivy.
• sbt/zinc hosts Zinc, an incremental compiler for Scala.
• sbt/sbt, this repository hosts modules that implements the build tool.

Other links

• Setup: Describes getting started with the latest binary release.
• FAQ: Explains how to get help and more.
• sbt/sbt-zero-seven: hosts sbt 0.7.7 and earlier versions

Issues and Pull Requests

Please read CONTRIBUTING carefully before opening a GitHub Issue.

The short version: try searching or asking on StackOverflow.

license

See LICENSE.

website's Issues

incorporate documentation inside sbt shell

I am thinking something analogous to :help in vim.
We would need some way of navigating within and between the pages, and also some way of searching.

Broken link in Organizing Build page

If you go the the Organizing Build page, and ctrl+f for "ld is to define one-off auto plugins in" The link to auto plugins is broken. What is this supposed to point to? I can submit a pull request with it fixed if someone can tell me where it's supposed to go.

API Links refer to 0.13 URL instead of latest

E g the link to ModuleID on page
http://www.scala-sbt.org/0.13/docs/Library-Management.html
leads to
http://www.scala-sbt.org/0.13/api/index.html#sbt.ModuleID
but should refer to
http://www.scala-sbt.org/0.13.11/api/index.html#sbt.ModuleID

I tried to find SbeExclusionRule, which was new in 0.13.8.

Cheers.
Enno.

Have `previewSite` task not depend on PDF docs task.

Just a suggestion for a build system improvement to save time when developing/testing website docs. Right now when previewSite is run the PDF docs are created before the HTTP server is launched.

confusing documentation about sbt axises

here http://www.scala-sbt.org/0.13.5/docs/Getting-Started/Scopes.html some descriptions are very confusing.

In particular it took me long time to undestand that in

{<build-uri>}<project-id>/config:intask::key

I should choose between config or intask and then add ::key
I think one or two examples like:

fooproject/config::name
fooproject/intask::bartask

will resolve the problem.
In my case confusing parts appeared because I got used to the notion that I operate with sbt as if I operate with scala-code. But in case of project/axis::key notation I operate just with some sbt-specific command syntax that is not code. I think it should be highlighted in the beginning that we are dealing with some special notation and axises here do not mean some scala traits (like I thought in the beginning) but a part of sbt console commands.

Revamp how to section

Title of the download page is broken

Hello,

The title page of the current online download page is not displayed at all. This bug appears from this commit.

I looked at the default layout and at the download page content, but I was not able to find any problem.
I am not familiar with ruby and nanoc, so I was not able to create a PR to fix it directly, sorry.

version switch

Any improvement on this front would be great

problem 1

When you get to 0.13.5 from Google for example http://www.scala-sbt.org/0.13.5/docs/Getting-Started/Welcome.html, 0.13 isn't on the version switch menu.
0.13 should be at the top, and it should navigate to http://www.scala-sbt.org/0.13/tutorial/ if you're on Getting Started guide; http://www.scala-sbt.org/0.13/docs/ otherwise.

problem 2

If you can jump to the corresponding page on 0.13 that'll be cool. I think there are some redirects that I generated.

problem 3

When you are on 0.13 tutorial or reference, version switch control is not displayed.
Again, I think it's ok for the first round to jump to the index page.

notes

Here are the stuff to fix

• http://www.scala-sbt.org/versions.js
• http://www.scala-sbt.org/0.13.2/docs/_static/set-versions.js

segfault while installing sbt via apt-get

This issue was initially posted to sbt/sbt: sbt/sbt#1883

The documentation says to run the following commands to install on ubuntu

echo "deb https://dl.bintray.com/sbt/debian /" | sudo tee -a /etc/apt/sources.list.d/sbt.list
sudo apt-get update
sudo apt-get install sbt

If you do that, then you will get the following crash.

NV\sowen@kafka01:~$ echo "deb https://dl.bintray.com/sbt/debian /" | sudo tee -a /etc/apt/sources.list.d/sbt.list
...
...
NV\sowen@kafka01:~$ sudo apt-get update
NV\sowen@kafka01:~$ sudo apt-get install sbt
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following NEW packages will be installed:
  sbt
0 upgraded, 1 newly installed, 0 to remove and 24 not upgraded.
Need to get 1,041 kB of archives.
After this operation, 1,224 kB of additional disk space will be used.
WARNING: The following packages cannot be authenticated!
  sbt
Install these packages without verification? [y/N] y
E: Method https has died unexpectedly!
E: Sub-process https received a segmentation fault.

Downloading the deb-file manually and installing with dpkg works fine. See:
http://stackoverflow.com/questions/13711395/install-sbt-on-ubuntu/13718915#13718915
http://stackoverflow.com/questions/28543911/sbt-install-failure-with-aptitude-on-ubuntu-14-04

Either the documentation should be updated, or a key should be included with the package.

Answer to original bug from jsuereth:

It looks like bintray recently starting having issues with HTTPs. Suprised it's a segfault. In any case, please reopen this against sbt/website.

https (https://www.scala-sbt.org/ uses Github's cert)

isaacs/github#156

Credentials best practice

https://github.com/sbt/website/blame/master/src/reference/02-DetailTopics/03-Dependency-Management/05-Publishing.md#L72 states that ~/.ivy2/.credentials is the preferred way to specify credentials. I disagree, at least as long as it doesn't clarify how to specify different credentials for multiple hosts.

IMHO the recommendation should be to put credentials in ~/.sbt/0.13/per-user-per-organization-credentials.sbt files like so:

credentials += Credentials("My realm", "some.host", "user", "password")

The recommendation to put credential settings (e.g. credentials += Credentials(Path.userHome / ".ivy2" / ".credentials")) into projects should also be discouraged. The reason being different projects being published to different artifact repositories an the Ivy credentials file being not flexible enough.

Does it make sense or am I missing something?

Scaladoc API documentation is missing

The Documentation page links to http://www.scala-sbt.org/0.13.8/api/index.html for API docs, but there is nothing there.

Broken link

The last link (excluding contents) on this page is broken

http://www.scala-sbt.org/0.13/docs/Howto-Generating-Files.html

To be clear, I am referring to the "Adding files to a package" link.

Opinion: TOC on the side rather than bottom

I found having the TOC on the right side in the old docs format much easier to navigate than having to scroll to the bottom of each page. It was also easier to keep track of where one was when jumping between sections. Not sure if Pamflet supports it, but having a more "Sphinx-style" TOC would improve usability in my opinion.

Expand on how sbt shell parses input

After some trial and error I understood a part of how the sbt shell parses scoped keys, which I didn't understand from the docs and, therefore, I think should be expanded upon.

Given (this was using sbt 0.13.7)

lazy val root = project aggregate core
lazy val core = project

here I'm getting the wrong answer because I'm asking the question wrong:

> test::publishArtifact
[info] core/*:test::publishArtifact
[info]     true
[info] root/*:test::publishArtifact
[info]     true

when I should be asking

> test:publishArtifact
[info] core/test:publishArtifact
[info]     false
[info] root/test:publishArtifact
[info]     false

Note, I was only able to understand because I was using a multi-module setup, which showed core/*:test::publishArtifact, which isn't what I was after. In a single module setup this would have just shown true.

Document the relationship between ~, aggregate and currentProject

See the discussion in https://gitter.im/sbt/sbt/archives/2015/05/26.

Does SBT Chinese tutorials need some assistance, like translation?

I can do translation for Chinese SBT tutorials. Where could I get started?

Install via https

It would be nice to revert 801b238

We should investigate what the problem is and either fix the instructions or report the issue to bintray if that's where the problem is

Make SBT_OPS information page in Getting Started

We (cc @takezoux2 ) see common mistakes of sbt beginners who don't set SBT_OPS in our regular Scala meetups. Then, as you imagine, their sbt immediately run out of memory.

This is because recommended SBT_OPS setting was only written in Installing sbt manually page among Getting Started with sbt pages, while it should be relevant for all ways of installation (at least homebrew's). So people who have installed sbt in homebrew rarely see Installing sbt manually page and often misses SBT_OPS.

So we propose to make "recommended sbt options" page separate from Installing sbt manually, or put SBT_OPS information to all Installing sbt xxx pages.

If it's OK for you, we're happy to send pull requests as well.

StackOverflowException in MarkdownParser when running sbt under Java 8.

As of 7f98941, running makeSite causes a StackOverflowException in:

com.tristanhunt.knockoff.ChunkParser$$anon$1.findEnd(MarkdownParsing.scala:270)

Obviously not really a bug in the documentation, but logging since the docs can't be built until fixed.

Top of the stack trace:

java.lang.StackOverflowError
    at java.util.regex.Pattern.compile(Pattern.java:1683)
    at java.util.regex.Pattern.<init>(Pattern.java:1351)
    at java.util.regex.Pattern.compile(Pattern.java:1028)
    at scala.util.matching.Regex.<init>(Regex.scala:153)
    at scala.collection.immutable.StringLike$class.r(StringLike.scala:224)
    at scala.collection.immutable.StringOps.r(StringOps.scala:31)
    at scala.collection.immutable.StringLike$class.r(StringLike.scala:213)
    at scala.collection.immutable.StringOps.r(StringOps.scala:31)
    at com.tristanhunt.knockoff.ChunkParser$$anon$1.findEnd(MarkdownParsing.scala:261)
    at com.tristanhunt.knockoff.ChunkParser$$anon$1.findEnd(MarkdownParsing.scala:270)
    at com.tristanhunt.knockoff.ChunkParser$$anon$1.findEnd(MarkdownParsing.scala:270)
    at com.tristanhunt.knockoff.ChunkParser$$anon$1.findEnd(MarkdownParsing.scala:270)

Linux downloads not shown

I was just told that there exists an architecture switch on the download page. This doesn't seem to work on Linux (Debian 8, Iceweasel/Firefox 38). Inspecting the page, all platforms are greyed out instead of showing the Linux bit.

Info from http://mybrowserinfo.com:

Your Browser User Agent String is Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Firefox/38.0 Iceweasel/38.6.1
Operating System:
    Linux
Platform:
    UNIX
Internet Browser:
    Firefox 38.0

scala-tools.org in Publishing page

@milessabin reported on Gitter:

Why on earth is this still mentioning nexus.scala-tools.org in the example credentials file?!? http://www.scala-sbt.org/0.13/docs/Publishing.html
Surely oss.sonatype.org would be more appropriate?

Travis CI build fails

Travis CI build fails with The command "sudo apt-get install -qq ruby-dev pandoc latex-cjk-all texlive-full" failed and exited with 100 during .

https://travis-ci.org/sbt/website/builds/74030087

About the version `app_version=0.13.11`

Is current version app_version=0.13.11 still valid?

I followed this document: http://www.scala-sbt.org/0.13/docs/Scripts.html, there is a command:

cs sbt/sbt --branch 0.13.11

which reports there is no such repo. I have to change it to 0.13 or 1.0.x

Search Engine Optimization

Currently 0.12.4 documentation shows up frequently.

• https://support.google.com/webmasters

Maybe build sitemap.xml?

Put the recommended platform installers on the download page

I use Linux, so the current download instructions on http://www.scala-sbt.org/download.html are fine for me, but I think the other recommended platform installers should be front and center on this page as well. They should be above the fold when browsing the page on a common desktop resolution.

I realize the links are available as part of the docs (http://www.scala-sbt.org/0.13/docs/Setup.html), but linking directly to the Windows, OSX, and Linux install instructions would make for a better UX (a few less clicks and scrolling).

Search box

• Sitemap
• Search box UI that limits the search to /0.13/*/

Missing docs for ProjectRef & RootProject

I don't see ProjectRef or RootProject mentioned anywhere in the documentation. A good place to include these docs might be in the section for multi-project builds.

I have a lot of questions about how to setup multi-project builds as our codebase grows larger. Should we put our entire codebase in a single SBT build split amongst standard SBT sub-projects? Or should we make each library it's own SBT project and wire them all together with ProjectRef external references?

Dependency document should be enhanced

Dependency document should be enhanced.
What does it means (groupId, artifactId, and revision)

How's different between sbt dependency and the MVN repository.

ps .
I would like to add some more introduction to explain this.

Documentation links to unavailable version of the API

The current version of the documentation index page (http://www.scala-sbt.org/documentation.html) links to the 0.13.7 version of sbt API (http://www.scala-sbt.org/0.13.7/api/index.html) which is not available yet, so there's a 404 error (same applies for source link). I guess the link should rather lead to http://www.scala-sbt.org/0.13/api/index.html in order to always link to the newest version of the API.

Old documentations should link to the new one

People still frequently cites old doc. Maybe because the version lookup shows 0.13.5 as the latest.
Regardless, we should probably point at newer doc.

Update http://www.scala-sbt.org/0.13/docs/Changes.html

It's a bit out of date.

Example in reference manual does not compile

package sbthello

import sbt._
import Keys._

object HelloPlugin3 extends AutoPlugin {
  object autoImport {
    val greeting = settingKey[String]("greeting")
  }
  import autoImport._
  override def trigger = allRequirements
  override lazy val buildSettings = Seq(
    greeting := "Hi!",
    commands += helloCommand)
  lazy val helloCommand =
    Command.command("hello") { (state: State) =>
      println(greeting.value)
      state
    }
}

error:

/home/richard/workspace/sbt-issues/HelloPlugin3.scala:17: `value` can only be used within a task or setting macro, such as :=, +=, ++=, Def.task, or Def.setting.
[error]       println(greeting.value)

/home/richard/workspace/sbt-issues/project/build.properties:

sbt.version=0.13.8

http://paste.ubuntu.com/11803979/

The Nightly Builds page is out of date

http://www.scala-sbt.org/0.13/docs/Nightly-Builds.html

Def.sequential example doesn't compile

The docs for Def.sequential don't compile.

[error] /home/bmccann/src/play-multidomain-seed/project/Common.scala:23: not found: value sideEffect0
[error] sideEffect0 := {
[error] ^
[error] /home/bmccann/src/play-multidomain-seed/project/Common.scala:28: not found: value sideEffect1
[error] sideEffect1 := {
[error] ^
[error] /home/bmccann/src/play-multidomain-seed/project/Common.scala:33: not found: value foo
[error] foo := Def.sequential(compile in Compile, sideEffect0, sideEffect1, test in Test).value
[error] ^
[error] three errors found
error Compilation failed

HelloPlugin3 example does not compile

The HelloPlugin3 in 02-Plugins.md contains this code:

  lazy val helloCommand =
    Command.command("hello") { (state: State) =>
      println(greeting.value)
      state
    }

It calls .value on the SettingKey greeting outside of a task or setting macro. I've done something similar in my own plugin which gave me the following compile error:

`value` can only be used within a task or setting macro, such as :=, +=, ++=, Def.task, or Def.setting

So I guess this example also does not compile.

What would be an idiomatic way to implement helloCommand? Maybe like this:

  lazy val helloCommand =
    Command.command("hello") { (state: State) =>
      println(Project.extract(state).get(greeting))
      state
    }

?

Better mobile support

• https://twitter.com/yrrebjr/status/473939915521015808

Responsive design around menu and landing pages.

Anchors hide the top of the section below the floating header

Try and click http://www.scala-sbt.org/0.13/docs/Best-Practices.html#.sbtrc and the .sbtrc part won't be visible as it's below the floating header (Docs/Download/Get Involved).

Error in docs for "Running commands"

On this page, in section Pass arguments to a command or task in batch mode, the docs give the following example:

$ sbt 'project X' clean '~ compile'

But this is wrong. Instead, the example should read:

$ sbt "project X" clean "~ compile"

That is, the single quotes should be replaced with double quotes.

I've tested this on both Windows and Linux, and only double quotes work.

Expose sbt logo assets

We should maybe also add the typesafe legal terms of use for our logo: http://typesafe.com/legal/trademarks

PDF

Some people really really want PDF - https://twitter.com/bhaskar_vk/status/473117421067591681

This was one of the things I added to Pamflet, so I should be able to do it fairly quickly at least on my machine. Jenkins would require pandoc, but it would also require nanoc etc that I started using too.

Extend Tags docs to include the tags SettingsKey

In our project we have a bunch of tests that can run in parallel and a whole bunch that cannot. To split these out we've created a custom scope and ran them with parallelExecution := false.

This worked great as long as we had a simple project, but the moment we went to a multi-module troubles kicked in because we couldn't assure that test tasks from the different projects were not running in parallel.

After a lot of digging through the sbt source in combination with the ParallelExecution page I found out that I could create a custom tag and tie it to my custom scope with the tag SettingsKey.

Let's say it wasn't a pleasant experience and it would be very useful if this awesome feature could be documented on the website. I'm sure many ppl are running into this in large projects that contain integration tests.

Deprecated SettingKey `cacheDirectory` used in `FileFunction.cached` example

On scala-sbt.org the example makes use of cacheDirectory, which was deprecated in 0.13.0.

Consider migrating info from the wiki to the official documentation

Speaking with @eed3si9n a while ago about the wiki, he advised we should probably migrate everything but the use cases from the wiki to the documentation.

Asides from having it in the same location, it allows for that information to be pull-requested against.

Change COMMUNITY to "Get Involved"

Play has a nice Get Involved page. Let's be like Play. http://www.playframework.com/get-involved

Developers guide: A guided tour of sbt code base

Website has older version

It must be older than 853603b, since those changes are no longer present.

nav is slightly irritating

In a reasonably-sized browser window the "go left" and "go right" regions take up about 25% of the width of the window and it's really easy to click over to the next or previous page as you're mousing around. At least for me; I do it every single time I look at the doc. What would you think about maybe just making the buttons hot instead of the entire margin?

Jenkins, instead of Travis

we should automate pushing new websites.

local toc

There should be an ability to show toc for the current section.
This could bring in Getting Started Guide into the main doc.