mirror of https://github.com/sbt/sbt.git
Add new DEVELOPMENT.md file
Consisting mainly of a cookbook of sbt commands to be used during development.
This commit is contained in:
Alexandre Archambault
parent
3636c58d07
commit
3e270c9fb2
107
DEVELOP.md
107
DEVELOP.md
|
|
@ -1,107 +0,0 @@
|
|||
# Development guide
|
||||
|
||||
## Compiling / testing via the command-line tool
|
||||
|
||||
The [command-line tool](https://github.com/coursier/coursier#command-line-1) 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](https://github.com/xerial/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](http://www.scala-sbt.org/0.13/docs/Testing-sbt-plugins.html) 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](https://travis-ci.org/coursier/coursier/), Windows with [Appveyor](https://ci.appveyor.com/project/alexarchambault/coursier)) 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](https://github.com/typesafehub/migration-manager/wiki/Sbt-plugin),
|
||||
- launcher and sbt-coursier plugin tested against Java 6.
|
||||
|
|
@ -0,0 +1,100 @@
|
|||
# Cookbook of stuff done while developing coursier
|
||||
|
||||
General note: always explicitly set the scala version at the sbt prompt, like
|
||||
```
|
||||
> ++2.12.1
|
||||
> ++2.11.11
|
||||
> ++2.10.6
|
||||
```
|
||||
|
||||
Some modules of coursier are only built in specific scala versions (sbt plugins in 2.10 and 2.12, cli and web modules in 2.11, …). coursier doesn't use sbt-doge
|
||||
to handle that for now (but any help to make it work would be welcome).
|
||||
|
||||
## Compile and run the CLI
|
||||
|
||||
```
|
||||
$ sbt ++2.11.11 "project cli" pack
|
||||
…
|
||||
$ cli/target/pack/bin/coursier --help
|
||||
…
|
||||
```
|
||||
|
||||
Note: `sbt ++2.11.11 cli/pack` used to work fine, but doesn't anymore, see
|
||||
https://github.com/coursier/coursier/commit/3636c58d07532ab2dc176f2d2caa2b4d51050f12.
|
||||
|
||||
## Automatically re-compile the CLI
|
||||
|
||||
Doesn't work anymore :/ `sbt ++2.11.11 ~cli/pack` used to work, but doesn't
|
||||
anymore for now (see above). `sbt ++2.11.11 "project cli" ~pack` only watches
|
||||
the sources of the cli module, not those of the modules it depends on (core,
|
||||
cache, …).
|
||||
|
||||
## Run a scripted test of sbt-coursier or sbt-shading
|
||||
|
||||
```
|
||||
$ sbt
|
||||
> ++2.12.1
|
||||
> sbt-plugins/publishLocal
|
||||
> sbt-coursier/scripted sbt-coursier/simple
|
||||
> sbt-shading/scripted sbt-shading/shading
|
||||
```
|
||||
|
||||
`++2.12.1` sets the scala version, which automatically builds the plugins for sbt 1.0. For sbt 0.13, do `++2.10.6`.
|
||||
|
||||
`sbt-plugins/publishLocal` publishes locally the plugins *and their dependencies*, which scripted seems not to do automatically.
|
||||
|
||||
## Run all the scripted tests of sbt-coursier or sbt-shading
|
||||
|
||||
```
|
||||
$ sbt
|
||||
> ++2.12.1
|
||||
> sbt-plugins/publishLocal
|
||||
> sbt-coursier/scripted
|
||||
> sbt-shading/scripted
|
||||
```
|
||||
|
||||
Use `++2.10.6` for sbt 0.13. See discussion above too.
|
||||
|
||||
## Run unit tests (JVM)
|
||||
|
||||
```
|
||||
$ sbt
|
||||
> ++2.12.1
|
||||
> testsJVM/testOnly coursier.util.TreeTests
|
||||
> testsJVM/test
|
||||
```
|
||||
|
||||
`testOnly` runs the tests that match the expression it is passed.
|
||||
`test` runs all the tests.
|
||||
|
||||
To run the tests each time the sources change, prefix the test commands with
|
||||
`~`, like
|
||||
```
|
||||
$ sbt
|
||||
> ++2.12.1
|
||||
> ~testsJVM/testOnly coursier.util.TreeTests
|
||||
> ~testsJVM/test
|
||||
```
|
||||
|
||||
## Run unit tests (JS)
|
||||
|
||||
The JS tests require node to be installed, and a few dependencies to have been
|
||||
fetched with
|
||||
```
|
||||
$ npm install
|
||||
```
|
||||
(run from the root of the coursier sources).
|
||||
|
||||
JS tests can then be run like JVM tests, like
|
||||
```
|
||||
$ sbt
|
||||
> ++2.12.1
|
||||
> testsJS/testOnly coursier.util.TreeTests
|
||||
> testsJS/test
|
||||
```
|
||||
|
||||
Like for the JVM tests, prefix test commands with `~` to watch sources (see above).
|
||||
|
||||
## Run integration tests
|
||||
|
||||
…
|
||||
Loading…
Reference in New Issue