sbt/CONTRIBUTING.md

Development guide

Compiling / testing via the command-line tool

The command-line tool of coursier allows to quickly test changes in the core, cache, and cli modules. To get a freshly compiled launcher for it, type

$ sbt ++2.11.8 cli/pack

++2.11.8 sets the Scala version to 2.11.8. This is the latest 2.11 Scala version. The launcher is only compiled for Scala 2.11 for now.

cli/pack instructs sbt to create a "pack" directory, via the sbt-pack plugin. Its result can be found under cli/target/pack. It mainly contains a lib sub-directory, containing the full launcher classpath, along with a bin sub-directory, that contains shell scripts allowing to launch applications contained in lib.

As the launcher has only one main class, cli/target/pack/bin contains only one launcher, named coursier. It can be launched like

$ cli/target/pack/bin/coursier --help

During development, it can be helpful to have the "pack" directory mirror what's in the sources. This can be achieved with

$ sbt ++2.11.8 "~cli/pack"

which instructs sbt to watch the sources of coursier, and launch cli/pack whenever a change is detected.

Note that cli/pack triggers a compilation of the cli module, along with the modules it depends on (currently, coreJVM, the JVM counterpart of the cross-compiled core module, and cache). That allows to catch compilation errors along the way while generating the "pack" directory.

Compiling / testing the sbt plugin(s)

Via scripted

scripted is a test framework for sbt plugins. sbt-coursier and sbt-shading are tested via scripted.

Running sbt-coursier tests requires to have locally published the coreJVM and cache modules for Scala 2.10, that sbt-coursier depends on. That can be done via

$ sbt ++2.10.6 coreJVM/publishLocal cache/publishLocal

To run the scripted test suite for sbt-coursier, one can then type

$ sbt ++2.10.6 sbt-coursier/scripted

To run the test suite of sbt-shading, publish first the modules it depends on with

$ sbt ++2.10.6 coreJVM/publishLocal cache/publishLocal sbt-coursier/publishLocal

Then run the test suite per se with

$ sbt ++2.10.6 sbt-shading/scripted

Running the whole test suites can be cumbersome. scripted allows to run only particular tests, e.g.

$ sbt ++2.10.6 "sbt-coursier/scripted sbt-coursier/simple"

runs only the simple test. The full list of tests for sbt-coursier can be found under sbt-coursier/src/sbt-test/sbt-coursier, the ones of sbt-shading can be found under sbt-shading/src/sbt-test/sbt-shading.

Tests can be run continuously, with

$ sbt ++2.10.6 "~sbt-coursier/scripted sbt-coursier/simple"

which runs the simple test of sbt-coursier whenever the sources of sbt-coursier change. Note that changes in core and cache are not taken into account straightaway when running tests. These modules have to be published again if they changed (with sbt ++2.10.6 coreJVM/publishLocal, sbt ++2.10.6 cache/publishLocal, and / or sbt ++2.10.6 sbt-coursier/publishLocal, briefly discussed above, the latter only applying when running sbt-shading tests, which depends on sbt-coursier).

Via a test project

Alternatively, one can setup a small test project, and have it use a locally published plugin.

Set the coursier version to a test value in version.sbt, like

$ cat version.sbt
version in ThisBuild := "1.0.0-test-1"

Using a custom version, that can be changed if necessary, allows to circumvent possible stale sbt caches (these seem to keep track of the plugin dependencies, and make the plugin fail if these dependencies change) - if the plugin dependencies change, just bump the suffix of the custom version.

Then continuously publish the plugin and its dependencies, with

$ sbt ++2.10.6 "~publishLocal"

If the compilation went fine, this should print various messages related to the publishing of the modules of coursier under ~/.ivy2/local, with the custom version set above (here 1.0.0-test-1).

These published modules, that include the sbt plugins, can then be used straightaway in a test project. For example, one can be setup with

$ mkdir -p test-project/project
$ cd test-project
$ echo "sbt.version=0.13.13" > project/build.properties
$ echo 'addSbtPlugin("io.get-coursier" % "sbt-coursier" % "1.0.0-test-1")' > project/plugins.sbt
$ echo 'scalaVersion := "2.12.1"' > build.sbt
$ sbt

and tweaked a bit more depending on what should be tested.

coursier build matrix

The CI(s) of coursier (Linux and Mac with Travis, Windows with Appveyor) test a variety of things. Testing all of those locally can be quite cumbersome. Each of those is susceptible to make the CI fail - often for good reasons, sometimes for less good ones:

• 3 Scala versions (currently, 2.10.6, 2.11.8, and 2.12.1),
• 2 sbt plugins (sbt-coursier and sbt-shading), each with its own test suite,
• scala-js compilation and tests,
• Windows CI,
• integration tests with external components (currently, a web server and locally published artifacts),
• binary compatibility checks with MiMA,
• launcher and sbt-coursier plugin tested against Java 6.