Include a new section in `Understanding-incremental-compilation`
document which explains in detail how to turn on and use the
new api debugging feature.
Mention distinction between dependencies through inheritance and member
reference. Add an example which demonstrates the difference a little
bit more concretely by using some simple Scala source code.
The startup script should set sbt.cygwin=true if running from cygwin.
This will set the terminal type properly for JLine if not already set.
If sbt.cygwin=false or unset and os.name includes "windows", JAnsi is
downloaded by the launcher and installed on standard out/err.
The value for jline.terminal is transformed from explicit jline.X to
the basic types "windows", "unix", or "none". Now that sbt uses JLine
2.0, these types are understood by both sbt's JLine and Scala's.
Older Scala versions shaded the classes but not the terminal property
so both couldn't be configured with a class name at the same time.
Previous table was mix of reStructuredText and html produced by
automatic conversion tool. The result was rather unreadable and very
hard to edit.
I converted the table to native reStructuredText's table.
Add `apiDiffContextSize` option to `IncOptions` which allows one
to control the size (in lines) of a context used when printing
diffs for textual API representation.
The default value for `apiDiffContextSize` is 5 which seems to be
enough for most situations. This is verified by many debugging
sessions I performed when using api diffing functionality.
Implement displaying API changes by using textual representation
of an API (ShowAPI) and good, old textual diff algorithm. We are
using java-diff-utils library that is distributed under Apache 2.0
license.
Notice that we have only soft dependency on java-diff-utils. It means
that we'll try to lookup java-diff-utils class through reflection
and fail gracefully if none is found on the classpath. This way
sbt is not getting any new dependency. If user needs to debug
api diffs then it's matter of starting sbt with
`-Dsbt.extraClasspath=path/to/diffutils.jar` option passed
to sbt launcher.
Lanucher configuration parser would previously require a default
value in variable substitution pattern to be non-empty string.
This is an unnecessary restriction as empty value is sometimes
useful as in this example:
resources: ${sbt.extraClasspath-}
This commit lifts this restriction so empty default values are
allowed. The change has been discussed with @harrah.
Set sbt.task.timings=true to print timings for tasks.
This sample progress handler shows how to get names for tasks and
deal with flatMapped tasks. There are still some tasks that make
it through as anonymous, which needs to be investigated.
A setting to provide a custom handler should come in a subsequent commit.
* Consolidate project ID validation and normalization into Project methods
* Provide an earlier and more detailed error message when the directory
name can't be used for the project ID
Construction of Scala providers was already properly synchronized jvm and machine-wide.
The cache on top of construction was not and neither was the newer ClassLoaderCache.
This could cause the same Scala version to be loaded in multiple class loaders, taking
up more permgen space and possibly decreasing performance due to less effective jit.
The issue is very rare in practice for 0.13 because of the low probability of contention
on ClassLoaderCache. This is because the work for a cache miss is mainly the construction
of a URLClassLoader. In 0.12, however, the work potentially involved network access and
class loading (not just class loader construction), thus greatly increasing the probability
of contention and thus duplicate work (i.e. class loader construction).
When there is contention, multiple class loaders are constructed and then preserved by the
scalaInstance task in each project throughout the first task execution. Only when multiple
scalaInstance tasks execute simultaneously and only during the first execution does this occur.
(Technically, it could still happen later, but it doesn't in practice.)
This means that the number of duplicate class loaders should quickly saturate instead of growing
linearly with the number of projects. It also means that the impact depends on the exact
tree structure of projects. A linear chain of dependencies will be unaffected, but a build with
independent leaves may be limited by the number of cores. The number of cores affects
the number of threads typically used by the task engine, which limits the number of concurrently
executing scalaInstance tasks.
In summary, this might affect the first, cold compilation of a multi-module project with
independent leaves on a multi-core machine with Scala version different from the version used
for sbt. It might increase the maximum permgen requirements as well as slow the jit compilation
by up to one task execution. Subsequent compilations should be unaffected and the permgen
utilization return to be as expected.
The Help for these commands now needs to be cleaned up, since they were not written with
this feature in mind. In particular,
* consider adding syntax summaries in the short help strings
* alternatively, add the syntax summary data elsewhere for use specifically by this feature
* display a better message when there is no short help string, such as
"See 'help <command>' for usage." or just displaying the lower level error message, such as
"Expected whitespace"
Mark Harrah
Grzegorz Kossakowski
Eugene Yokota