diff options
Diffstat (limited to 'docs/contributing')
-rw-r--r-- | docs/contributing/eclipse.md | 50 | ||||
-rw-r--r-- | docs/contributing/getting-started.md | 42 | ||||
-rw-r--r-- | docs/contributing/intellij-idea.md | 36 | ||||
-rw-r--r-- | docs/contributing/workflow.md | 81 |
4 files changed, 209 insertions, 0 deletions
diff --git a/docs/contributing/eclipse.md b/docs/contributing/eclipse.md new file mode 100644 index 000000000..46301dc42 --- /dev/null +++ b/docs/contributing/eclipse.md @@ -0,0 +1,50 @@ +--- +layout: default +title: Eclipse +--- + +Building Dotty with Eclipse +=========================== + +Build setup +----------- +You may need to redo these steps when the build changes. + +1. Run `sbt eclipse` +2. In dotty, go to `Properties > java build path > Libraries`. + Remove the Scala Compiler container (currently 2.11.4) and add as an + external jar the latest compiler version in the Ivy cache. This is + currently: + + ``` + .ivy2/cache/me.d-d/scala-compiler/jars/scala-compiler-2.11.5-20160322-171045-e19b30b3cd.jar + ``` + + But that might change in the future. Or, copy the latest scala compiler from + the cache to a stable name and use that as external jar. + +3. It is recommended to change the default output folder (in `Properties > java + build path > Source`) to `dotty/classes` instead of `dotty/bin` because + `dotty/bin` is reserved for shell scripts. + +If you have `CLASSPATH` defined: + +4. Update your classpath to contain any new required external libraries to run + `./bin/dotc`, `./bin/doti` outside of Eclipse. + +5. Open the `Run Configurations` tab, and edit the `tests` configuration so + that it contains a `CLASSPATH` variable which reflects the current + `CLASSPATH`. + +In order for compilation errors related to `ENUM` to be resolved, make sure +that scala-reflect 2.11.5 is on the classpath. + +Running the compiler Main class from Eclipse +-------------------------------------------- +1. Navigate to `dotty.tools.dotc.Main` +2. `Run As... > Scala Application` +3. `Run Configurations > Main$ > Classpath > Bootstrap entries`: + - Add the Scala library (`Advanced...` > `Add library...` > `Scala library`) + - Add the Dotty classfiles (`Add projects...` > `[x] dotty`) +4. `Run Configurations > Main$ > Arguments` and add + `${project_loc}/examples/hello.scala` diff --git a/docs/contributing/getting-started.md b/docs/contributing/getting-started.md new file mode 100644 index 000000000..92afd02f3 --- /dev/null +++ b/docs/contributing/getting-started.md @@ -0,0 +1,42 @@ +--- +layout: default +title: "Getting Started" +--- + +Getting Started +=============== + +Talks on Dotty +-------------- +- [Scala's Road Ahead](https://www.youtube.com/watch?v=GHzWqJKFCk4) by Martin Odersky [\[slides\]](http://www.slideshare.net/Odersky/scala-days-nyc-2016) +- [Compilers are Databases](https://www.youtube.com/watch?v=WxyyJyB_Ssc) by Martin Odersky [\[slides\]](http://www.slideshare.net/Odersky/compilers-are-databases) +- [Dotty: Exploring the future of Scala](https://www.youtube.com/watch?v=aftdOFuVU1o) by Dmitry Petrashko [\[slides\]](https://d-d.me/scalaworld2015/#/). This talk includes details about the design of mini-phases and denotations. +- [Making your Scala applications smaller and faster with the Dotty linker](https://www.youtube.com/watch?v=xCeI1ArdXM4) by Dmitry Petrashko [\[slides\]](https://d-d.me/scaladays2015/#/) +- [Dotty: what is it and how it works](https://www.youtube.com/watch?v=wCFbYu7xEJA) by Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-tutorial/#/) +- [Hacking on Dotty: A live demo](https://www.youtube.com/watch?v=0OOYGeZLHs4) by Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-live-demo/) +- [AutoSpecialization in Dotty](https://vimeo.com/165928176) by Dmitry Petrashko [\[slides\]](https://d-d.me/talks/flatmap2016/#/) +- [Dotty and types: the story so far](https://www.youtube.com/watch?v=YIQjfCKDR5A) by Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/typelevel-summit-oslo/) + +Requirements +------------ +Make sure that you are using Java 8 or later, the output of `java -version` +should contain `1.8`. + +Compiling and running code +-------------------------- +```bash +git clone https://github.com/lampepfl/dotty.git +cd dotty +# Clone dotty-compatible stdlib. Needed for running the test suite. +git clone -b dotty-library https://github.com/DarkDimius/scala.git scala-scala +# Compile code using Dotty +./bin/dotc tests/pos/HelloWorld.scala +# Run it with the proper classpath +./bin/dotr HelloWorld +``` + +Starting a REPL +--------------- +```bash +./bin/dotr +``` diff --git a/docs/contributing/intellij-idea.md b/docs/contributing/intellij-idea.md new file mode 100644 index 000000000..dda04f515 --- /dev/null +++ b/docs/contributing/intellij-idea.md @@ -0,0 +1,36 @@ +--- +layout: default +--- + +Building Dotty with Intellij IDEA +================================= +Dotty compiler support is available in the [Scala plugin nightly] starting +from 2.2.39. You need to install [IDEA 2016.1] to try it. + +## To create a new project with Dotty + +1. Open New Project dialog and select `Scala` > `Dotty` +2. Proceed as usual and don't forget to create or select Dotty SDK. + +## To compile an existing Scala project with Dotty + +1. Create a new Dotty SDK: + `Project Structure` > `Global libraries` > `New Global Library` > `Dotty SDK` +2. Replace Scala SDK with Dotty SDK in: + `Project Structure` > `Modules` > `Dependencies` + +Java 1.8 should be used as the Project/Module SDK. You also need to enable the +Scala Compile Server to use Dotty compiler. + +## Notes +* Dotty support is experimental, many features including code highlighting and + worksheet are not ready yet. +* You can download the latest version of Dotty without creating a new Dotty SDK + with the `Update snapshot` button in the Dotty SDK library settings. +* Please report any problems to the [IntelliJ Scala issue tracker] or write + to the [IntelliJ Scala gitter] + +[Scala plugin nightly]: https://confluence.jetbrains.com/display/SCA/Scala+Plugin+Nightly +[IDEA 2016.1]: https://www.jetbrains.com/idea/nextversion/ +[IntelliJ Scala issue tracker]: https://youtrack.jetbrains.com/issues/SCL +[IntelliJ Scala gitter]: https://gitter.im/JetBrains/intellij-scala diff --git a/docs/contributing/workflow.md b/docs/contributing/workflow.md new file mode 100644 index 000000000..e160999d9 --- /dev/null +++ b/docs/contributing/workflow.md @@ -0,0 +1,81 @@ +--- +layout: default +title: "Workflow" +--- + +Workflow +======== +This document details common workflow patterns when working with Dotty. + +## Compiling files with dotc ## + +From sbt: + +```bash +> run <OPTIONS> <FILE> +``` + +From terminal: + +```bash +$ ./bin/dotc <OPTIONS> <FILE> +``` + +Here are some useful debugging `<OPTIONS>`: + +* `-Xprint:PHASE1,PHASE2,...` or `-Xprint:all`: prints the `AST` after each + specified phase. Phase names can be found by searching + `src/dotty/tools/dotc/transform/` for `phaseName`. +* `-Ylog:PHASE1,PHASE2,...` or `-Ylog:all`: enables `ctx.log("")` logging for + the specified phase. +* `-Ycheck:all` verifies the consistency of `AST` nodes between phases, in + particular checks that types do not change. Some phases currently can't be + `Ycheck`ed, therefore in the tests we run: + `-Ycheck:tailrec,resolveSuper,mixin,restoreScopes,labelDef`. + +Additional logging information can be obtained by changes some `noPrinter` to +`new Printer` in `src/dotty/tools/dotc/config/Printers.scala`. This enables the +`subtyping.println("")` and `ctx.traceIndented("", subtyping)` style logging. + +## Running tests ## + +```bash +$ sbt +> partest --show-diff --verbose +``` + +## Running single tests ## +To test a specific test tests/x/y.scala (for example tests/pos/t210.scala): + +```bash +> partest-only-no-bootstrap --show-diff --verbose tests/partest-generated/x/y.scala +``` + +Currently this will re-run some tests and do some preprocessing because of the +way partest has been set up. + +## Inspecting Trees with Type Stealer ## + +There is no power mode for the REPL yet, but you can inspect types with the +type stealer: + +```bash +$ ./bin/dotr +scala> import test.DottyTypeStealer._; import dotty.tools.dotc.core._; import Contexts._,Types._ +``` + +Now, you can define types and access their representation. For example: + +```scala +scala> val s = stealType("class O { type X }", "O#X") +scala> implicit val ctx: Context = s._1 +scala> val t = s._2(0) +t: dotty.tools.dotc.core.Types.Type = TypeRef(TypeRef(ThisType(TypeRef(NoPrefix,<empty>)),O),X) +scala> val u = t.asInstanceOf[TypeRef].underlying +u: dotty.tools.dotc.core.Types.Type = TypeBounds(TypeRef(ThisType(TypeRef(NoPrefix,scala)),Nothing), TypeRef(ThisType(TypeRef(NoPrefix,scala)),Any)) +``` + +## Pretty-printing ## +Many objects in the dotc compiler implement a `Showable` trait (e.g. `Tree`, +`Symbol`, `Type`). These objects may be prettyprinted using the `.show` +method |