From 55d1cbbfe2ec2dd697a6b1de0fb847fa4b09655e Mon Sep 17 00:00:00 2001 From: Eugene Yokota Date: Mon, 15 Jul 2019 12:39:41 -0400 Subject: [PATCH] Split some of the developing related docs to DEVELOPING.md --- CONTRIBUTING.md | 169 +------------------------------------------- DEVELOPING.md | 183 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 185 insertions(+), 167 deletions(-) create mode 100644 DEVELOPING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92abd3324..1f14b8aa6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -124,174 +124,9 @@ Make sure you document each commit and squash them appropriately. You can use th * Play's documentation on [Working with Git](https://www.playframework.com/documentation/2.4.4/WorkingWithGit#Squashing-commits) Build from source -================= +----------------- -### Branch to work against - -sbt uses two branches for development: - -- Development branch: `develop` (this is also called "master") -- Stable branch: `1.$MINOR.x`, where `$MINOR` is current minor version (e.g. `1.1.x` during 1.1.x series) - -### Instruction to build all modules from source - -1. Install the current stable binary release of sbt (see [Setup]), which will be used to build sbt from source. -2. Get the source code. - - ``` - $ mkdir sbt-modules - $ cd sbt-modules - $ for i in sbt io util librarymanagement zinc; do \ - git clone https://github.com/sbt/$i.git && (cd $i; git checkout -b develop origin/develop) - done - $ cd sbt - $ ./sbt-allsources.sh - ``` - -3. To build and publish all components locally, - - ``` - $ ./sbt-allsources.sh - sbt:sbtRoot> publishLocalAllModule - ``` - -### Instruction to build just sbt - -If the change you are making is contained in sbt/sbt, you could publishLocal on sbt/sbt: - -``` -$ sbt -sbt:sbtRoot> publishLocal -``` - -### Using the locally built sbt - -The `publishLocal` above will build and publish version `1.$MINOR.$PATCH-SNAPSHOT` (e.g. 1.1.2-SNAPSHOT) to your local ivy repository. - -To use the locally built sbt, set the version in `build.properties` file in your project to `1.$MINOR.$PATCH-SNAPSHOT` then launch `sbt` (this can be the `sbt` launcher installed in your machine). - -``` -$ cd $YOUR_OWN_PROJECT -$ sbt -> compile -``` - -### Using Jenkins sbt-snapshots nighties - -There is a Jenkins instance for sbt that every night builds and publishes (if successful) a timestamped version -of sbt to http://jenkins.scala-sbt.org/sbt-snapshots and is available for 4-5 weeks. To use it do the following: - -1. Set the `sbt.version` in `project/build.properties` - -```bash -echo "sbt.version=1.2.0-bin-20180423T192044" > project/build.properties -``` - -2. Create an sbt repositories file (`./repositories`) that includes that Maven repository: - -```properties -[repositories] - local - local-preloaded-ivy: file:///${sbt.preloaded-${sbt.global.base-${user.home}/.sbt}/preloaded/}, [organization]/[module]/[revision]/[type]s/[artifact](-[classifier]).[ext] - local-preloaded: file:///${sbt.preloaded-${sbt.global.base-${user.home}/.sbt}/preloaded/} - maven-central - sbt-maven-releases: https://repo.scala-sbt.org/scalasbt/maven-releases/, bootOnly - sbt-maven-snapshots: https://repo.scala-sbt.org/scalasbt/maven-snapshots/, bootOnly - typesafe-ivy-releases: https://repo.typesafe.com/typesafe/ivy-releases/, [organization]/[module]/[revision]/[type]s/[artifact](-[classifier]).[ext], bootOnly - sbt-ivy-snapshots: https://repo.scala-sbt.org/scalasbt/ivy-snapshots/, [organization]/[module]/[revision]/[type]s/[artifact](-[classifier]).[ext], bootOnly - sbt-snapshots: https://jenkins.scala-sbt.org/sbt-snapshots -``` - -3. Start sbt with a stable launcher and the custom repositories file: - -```bash -$ sbt -sbt-jar ~/.sbt/launchers/1.1.4/sbt-launch.jar -Dsbt.repository.config=repositories -Getting org.scala-sbt sbt 1.2.0-bin-20180423T192044 (this may take some time)... -downloading https://jenkins.scala-sbt.org/sbt-snapshots/org/scala-sbt/sbt/1.2.0-bin-20180423T192044/sbt-1.2.0-bin-20180423T192044.jar ... - [SUCCESSFUL ] org.scala-sbt#sbt;1.2.0-bin-20180423T192044!sbt.jar (139ms) -... -[info] sbt server started at local:///Users/dnw/.sbt/1.0/server/936e0f52ed9baf6b6d83/sock -> show sbtVersion -[info] 1.2.0-bin-20180423T192044 -``` - -### Using Jenkins maven-snapshots nightlies - -As an alternative you can request a build that publishes to https://repo.scala-sbt.org/scalasbt/maven-snapshots -and stays there forever by: - -1. Logging into https://jenkins.scala-sbt.org/job/sbt-validator/ -2. Clicking "Build with Parameters" -3. Making sure `deploy_to_bintray` is enabled -4. Hitting "Build" - -Afterwhich start sbt with a stable launcher: `sbt -sbt-jar ~/.sbt/launchers/1.1.4/sbt-launch.jar` - -### Clearing out boot and local cache - -When you run a locally built sbt, the JAR artifacts will be now cached under `$HOME/.sbt/boot/scala-2.12.6/org.scala-sbt/sbt/1.$MINOR.$PATCH-SNAPSHOT` directory. To clear this out run: `reboot dev` command from sbt's session of your test application. - -One drawback of `-SNAPSHOT` version is that it's slow to resolve as it tries to hit all the resolvers. You can workaround that by using a version name like `1.$MINOR.$PATCH-LOCAL1`. A non-SNAPSHOT artifacts will now be cached under `$HOME/.ivy/cache/` directory, so you need to clear that out using [sbt-dirty-money](https://github.com/sbt/sbt-dirty-money)'s `cleanCache` task. - -### Running sbt "from source" - `sbtOn` - -In addition to locally publishing a build of sbt, there is an alternative, experimental launcher within sbt/sbt -to be able to run sbt "from source", that is to compile sbt and run it from its resulting classfiles rather than -from published jar files. - -Such a launcher is available within sbt/sbt's build through a custom `sbtOn` command that takes as its first -argument the directory on which you want to run sbt, and the remaining arguments are passed _to_ that sbt -instance. For example: - -I have setup a minimal sbt build in the directory `/s/t`, to run sbt on that directory I call: - -```bash -> sbtOn /s/t -[info] Packaging /d/sbt/scripted/sbt/target/scala-2.12/scripted-sbt_2.12-1.2.0-SNAPSHOT.jar ... -[info] Done packaging. -[info] Running (fork) sbt.RunFromSourceMain /s/t -Listening for transport dt_socket at address: 5005 -[info] Loading settings from idea.sbt,global-plugins.sbt ... -[info] Loading global plugins from /Users/dnw/.dotfiles/.sbt/1.0/plugins -[info] Loading project definition from /s/t/project -[info] Set current project to t (in build file:/s/t/) -[info] sbt server started at local:///Users/dnw/.sbt/1.0/server/ce9baa494c7598e4d59b/sock -> show baseDirectory -[info] /s/t -> exit -[info] shutting down server -[success] Total time: 19 s, completed 25-Apr-2018 15:04:58 -``` - -Please note that this alternative launcher does _not_ have feature parity with sbt/launcher. (Meta) -contributions welcome! :-D - -### Diagnosing build failures - -Globally included plugins can interfere building `sbt`; if you are getting errors building sbt, try disabling all globally included plugins and try again. - -### Running Tests - -sbt has a suite of unit tests and integration tests, also known as scripted tests. - -#### Unit / Functional tests - -Various functional and unit tests are defined throughout the -project. To run all of them, run `sbt test`. You can run a single test -suite with `sbt testOnly` - -#### Integration tests - -Scripted integration tests reside in `sbt/src/sbt-test` and are -written using the same testing infrastructure sbt plugin authors can -use to test their own plugins with sbt. You can read more about this -style of tests [here](http://www.scala-sbt.org/1.0/docs/Testing-sbt-plugins). - -You can run the integration tests with the `sbt scripted` sbt -command. To run a single test, such as the test in -`sbt/src/sbt-test/project/global-plugin`, simply run: - - sbt "scripted project/global-plugin" +See [DEVELOPING](./DEVELOPING.md) Profiling sbt ------------- diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 000000000..8dbebd2df --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,183 @@ +Developer guide +=============== + +### Branch to work against + +sbt uses two branches for development: + +- Development branch: `develop` (this is also called "master") +- Stable branch: `1.$MINOR.x`, where `$MINOR` is current minor version (e.g. `1.1.x` during 1.1.x series) + +### Instruction to build all modules from source + +1. Install the current stable binary release of sbt (see [Setup]), which will be used to build sbt from source. +2. Get the source code. + + ``` + $ mkdir sbt-modules + $ cd sbt-modules + $ for i in sbt io util librarymanagement zinc; do \ + git clone https://github.com/sbt/$i.git && (cd $i; git checkout -b develop origin/develop) + done + $ cd sbt + $ ./sbt-allsources.sh + ``` + +3. To build and publish all components locally, + + ``` + $ ./sbt-allsources.sh + sbt:sbtRoot> publishLocalAllModule + ``` + +### Instruction to build just sbt + +If the change you are making is contained in sbt/sbt, you could publishLocal on sbt/sbt: + +``` +$ sbt +sbt:sbtRoot> publishLocal +``` + +### Using the locally built sbt + +The `publishLocal` above will build and publish version `1.$MINOR.$PATCH-SNAPSHOT` (e.g. 1.1.2-SNAPSHOT) to your local ivy repository. + +To use the locally built sbt, set the version in `build.properties` file in your project to `1.$MINOR.$PATCH-SNAPSHOT` then launch `sbt` (this can be the `sbt` launcher installed in your machine). + +``` +$ cd $YOUR_OWN_PROJECT +$ sbt +> compile +``` + +### Using Jenkins sbt-snapshots nighties + +There is a Jenkins instance for sbt that every night builds and publishes (if successful) a timestamped version +of sbt to http://jenkins.scala-sbt.org/sbt-snapshots and is available for 4-5 weeks. To use it do the following: + +1. Set the `sbt.version` in `project/build.properties` + +```bash +echo "sbt.version=1.2.0-bin-20180423T192044" > project/build.properties +``` + +2. Create an sbt repositories file (`./repositories`) that includes that Maven repository: + +```properties +[repositories] + local + local-preloaded-ivy: file:///${sbt.preloaded-${sbt.global.base-${user.home}/.sbt}/preloaded/}, [organization]/[module]/[revision]/[type]s/[artifact](-[classifier]).[ext] + local-preloaded: file:///${sbt.preloaded-${sbt.global.base-${user.home}/.sbt}/preloaded/} + maven-central + sbt-maven-releases: https://repo.scala-sbt.org/scalasbt/maven-releases/, bootOnly + sbt-maven-snapshots: https://repo.scala-sbt.org/scalasbt/maven-snapshots/, bootOnly + typesafe-ivy-releases: https://repo.typesafe.com/typesafe/ivy-releases/, [organization]/[module]/[revision]/[type]s/[artifact](-[classifier]).[ext], bootOnly + sbt-ivy-snapshots: https://repo.scala-sbt.org/scalasbt/ivy-snapshots/, [organization]/[module]/[revision]/[type]s/[artifact](-[classifier]).[ext], bootOnly + sbt-snapshots: https://jenkins.scala-sbt.org/sbt-snapshots +``` + +3. Start sbt with a stable launcher and the custom repositories file: + +```bash +$ sbt -sbt-jar ~/.sbt/launchers/1.1.4/sbt-launch.jar -Dsbt.repository.config=repositories +Getting org.scala-sbt sbt 1.2.0-bin-20180423T192044 (this may take some time)... +downloading https://jenkins.scala-sbt.org/sbt-snapshots/org/scala-sbt/sbt/1.2.0-bin-20180423T192044/sbt-1.2.0-bin-20180423T192044.jar ... + [SUCCESSFUL ] org.scala-sbt#sbt;1.2.0-bin-20180423T192044!sbt.jar (139ms) +... +[info] sbt server started at local:///Users/dnw/.sbt/1.0/server/936e0f52ed9baf6b6d83/sock +> show sbtVersion +[info] 1.2.0-bin-20180423T192044 +``` + +### Using Jenkins maven-snapshots nightlies + +As an alternative you can request a build that publishes to https://repo.scala-sbt.org/scalasbt/maven-snapshots +and stays there forever by: + +1. Logging into https://jenkins.scala-sbt.org/job/sbt-validator/ +2. Clicking "Build with Parameters" +3. Making sure `deploy_to_bintray` is enabled +4. Hitting "Build" + +Afterwhich start sbt with a stable launcher: `sbt -sbt-jar ~/.sbt/launchers/1.1.4/sbt-launch.jar` + +### Clearing out boot and local cache + +When you run a locally built sbt, the JAR artifacts will be now cached under `$HOME/.sbt/boot/scala-2.12.6/org.scala-sbt/sbt/1.$MINOR.$PATCH-SNAPSHOT` directory. To clear this out run: `reboot dev` command from sbt's session of your test application. + +One drawback of `-SNAPSHOT` version is that it's slow to resolve as it tries to hit all the resolvers. You can workaround that by using a version name like `1.$MINOR.$PATCH-LOCAL1`. A non-SNAPSHOT artifacts will now be cached under `$HOME/.ivy/cache/` directory, so you need to clear that out using [sbt-dirty-money](https://github.com/sbt/sbt-dirty-money)'s `cleanCache` task. + +### Running sbt "from source" - `sbtOn` + +In addition to locally publishing a build of sbt, there is an alternative, experimental launcher within sbt/sbt +to be able to run sbt "from source", that is to compile sbt and run it from its resulting classfiles rather than +from published jar files. + +Such a launcher is available within sbt/sbt's build through a custom `sbtOn` command that takes as its first +argument the directory on which you want to run sbt, and the remaining arguments are passed _to_ that sbt +instance. For example: + +I have setup a minimal sbt build in the directory `/s/t`, to run sbt on that directory I call: + +```bash +> sbtOn /s/t +[info] Packaging /d/sbt/scripted/sbt/target/scala-2.12/scripted-sbt_2.12-1.2.0-SNAPSHOT.jar ... +[info] Done packaging. +[info] Running (fork) sbt.RunFromSourceMain /s/t +Listening for transport dt_socket at address: 5005 +[info] Loading settings from idea.sbt,global-plugins.sbt ... +[info] Loading global plugins from /Users/dnw/.dotfiles/.sbt/1.0/plugins +[info] Loading project definition from /s/t/project +[info] Set current project to t (in build file:/s/t/) +[info] sbt server started at local:///Users/dnw/.sbt/1.0/server/ce9baa494c7598e4d59b/sock +> show baseDirectory +[info] /s/t +> exit +[info] shutting down server +[success] Total time: 19 s, completed 25-Apr-2018 15:04:58 +``` + +Please note that this alternative launcher does _not_ have feature parity with sbt/launcher. (Meta) +contributions welcome! :-D + +### Diagnosing build failures + +Globally included plugins can interfere building `sbt`; if you are getting errors building sbt, try disabling all globally included plugins and try again. + +### Running Tests + +sbt has a suite of unit tests and integration tests, also known as scripted tests. + +#### Unit / Functional tests + +Various functional and unit tests are defined throughout the +project. To run all of them, run `sbt test`. You can run a single test +suite with `sbt testOnly` + +#### Integration tests + +Scripted integration tests reside in `sbt/src/sbt-test` and are +written using the same testing infrastructure sbt plugin authors can +use to test their own plugins with sbt. You can read more about this +style of tests [here](http://www.scala-sbt.org/1.0/docs/Testing-sbt-plugins). + +You can run the integration tests with the `sbt scripted` sbt +command. To run a single test, such as the test in +`sbt/src/sbt-test/project/global-plugin`, simply run: + + sbt "scripted project/global-plugin" + +### Random tidbits + +#### Import statements + +You'd need alternative DSL import since you can't rely on sbt package object. + +```scala +// for slash syntax +import sbt.SlashSyntax0._ + +// for IO +import sbt.io.syntax._ +```