Skip to content

Commit 796222c

Browse files
biboudisbiboudis
committed
Improve Eclipse documentation, workflow and testing
1 parent 6e46455 commit 796222c

File tree

11 files changed

+95
-103
lines changed

11 files changed

+95
-103
lines changed

‎docs/docs/contributing/debug-tests.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,14 @@ Both are usually pre-installed on Mac OS and linux distributions.
1414

1515
First, compile the file `tests/debug/while.scala`:
1616

17-
```
18-
bin/dotc tests/debug/while.scala
17+
```shell
18+
$ dotc tests/debug/while.scala
1919
```
2020

2121
Second, run the compiled class with debugging enabled (suppose the main class is `Test`):
2222

23-
```
24-
bin/dotr -d Test
23+
```shell
24+
dotr -d Test
2525
```
2626

2727
Third, start JDB:
@@ -36,7 +36,7 @@ You can run `help` for commands that supported by JDB.
3636

3737
### 1. Annotate the source code with debug information.
3838

39-
Following file (`tests/debug/while.scala`) is an example of annoated source code:
39+
Following file (`tests/debug/while.scala`) is an example of annotated source code:
4040

4141
```Scala
4242
object Test {

‎docs/docs/contributing/eclipse.md

Lines changed: 38 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -6,27 +6,51 @@ title: Building Dotty with Eclipse
66
Setup
77
-----------
88

9-
1. Run `sbt ;managedSources;eclipse`
9+
You can setup Eclipse by using _[Scala IDE for Eclipse](http://scala-ide.org/)_ directly to run Dotty. Alternatively you can download
10+
your Eclipse distribution of choice and enable the Scala IDE from the Eclipse Marketplace, separately.
1011

11-
2. It is recommended to change the default output folder (in `Properties > java
12+
Assuming you have cloned dotty's repository from Github (and run `sbt managedSources` as described in
13+
[Getting Started](getting-started.md)) you can now proceed to set up Dotty with Eclipse.
14+
15+
- Note: It is recommended to change the default output folder (in `Properties > java
1216
build path > Source`) to `dotty/classes` instead of `dotty/bin` because
1317
`dotty/bin` is reserved for shell scripts.
1418

15-
If you have `CLASSPATH` defined:
19+
Optional: if you have `CLASSPATH` defined:
1620

17-
3. Update your classpath to contain any new required external libraries to run
21+
1. Update your classpath to contain any new required external libraries to run
1822
`./bin/dotc`, `./bin/dotr` outside of Eclipse.
1923

20-
4. Open the `Run Configurations` tab, and edit the `tests` configuration so
24+
1. Open the `Run Configurations` tab, and edit the `tests` configuration so
2125
that it contains a `CLASSPATH` variable which reflects the current
2226
`CLASSPATH`.
27+
28+
29+
Import to Eclipse
30+
-----------------
31+
32+
First step is to import dotty to Eclipse. This is done by selecting `File > Import` from the menu and selecting
33+
_Existing Projects into Workplace_.
34+
35+
![](../../images/eclipse/eclipse-import.png "Import Dotty to Eclipse")
36+
37+
On the next window, select the bare minimum configuration to run Dotty. You will need the compiler, library and the
38+
interfaces.
39+
40+
![](../../images/eclipse/eclipse-select.png "Import Dotty Projects")
41+
42+
43+
Running/Debugging
44+
---------------------------------------------------
45+
46+
To run/debug Dotty you have to create a new configuration from `Run > Run Configurations`. First select the project on the
47+
package explorer and then select the aforementioned option. On the `Main` tab you must have `dotty-compiler` for the
48+
_Project_ and `dotty.tools.dotc.Main` for the _Main class_. Specify the arguments you want for the compiler on the
49+
`Arguments` tab (e.g, flags and source files) and then proceed to the `Classpath` tab. There you must
50+
specify three `Bootstrap Entries` which are the compiler, interfaces and the library as shown in the screenshot below.
51+
Additionally you need to specify the scala-asm library as an external jar dependency. This can be found on your local
52+
`~/.ivy2/cache/` directory.
53+
54+
![](../../images/eclipse/eclipse-runconfiguration.png "Import Dotty Projects")
2355

24-
Running the compiler Main class from Eclipse
25-
--------------------------------------------
26-
1. Navigate to `dotty.tools.dotc.Main`
27-
2. `Run As... > Scala Application`
28-
3. `Run Configurations > Main$ > Classpath > Bootstrap entries`:
29-
- Add the Scala library (`Advanced...` > `Add library...` > `Scala library`)
30-
- Add the Dotty classfiles (`Add projects...` > `[x] dotty`)
31-
4. `Run Configurations > Main$ > Arguments` and add
32-
`${project_loc}/tests/pos/HelloWorld.scala`
56+
The compiler can be run and debugged using the same configuration. To contribute to dotty please follow the [Dotty Developer Guidelines](https://github.com/lampepfl/dotty/blob/master/CONTRIBUTING.md).

‎docs/docs/contributing/getting-started.md

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ title: Getting Started
55

66
Requirements
77
------------
8-
Make sure that you are using Java 8 or later, the output of `java -version`
8+
Make sure that you are using Java 8 or later. The output of `java -version`
99
should contain `1.8`.
1010

1111
Compiling and Running
@@ -15,11 +15,11 @@ Start by cloning the repository:
1515
```bash
1616
$ git clone --recursive https://github.com/lampepfl/dotty.git
1717
$ cd dotty
18-
$ sbt managedSources ## Needed for IDE import to succeed
18+
$ sbt managedSources # Needed for IDE import to succeed
1919
```
2020

2121
Dotty provides a standard sbt build: compiling, running and starting a repl can
22-
all be done from within sbt using
22+
all be done from within sbt:
2323

2424
```bash
2525
$ sbt
@@ -28,13 +28,21 @@ $ sbt
2828
hello world
2929
```
3030

31-
there is also a bash script that can be used in the same way:
31+
There are also bash scripts that can be used in the same way. Assuming that you have cloned the Dotty repo locally, append
32+
the following line on your `.bash_profile`:
3233

33-
```bash
34+
```shell
35+
export PATH=$HOME/dotty/bin:$PATH
36+
```
37+
38+
and you will be able to run the corresponding commands directly from your console:
39+
40+
```shell
3441
# Compile code using Dotty
35-
./bin/dotc tests/pos/HelloWorld.scala
42+
dotc tests/pos/HelloWorld.scala
43+
3644
# Run it with the proper classpath
37-
./bin/dotr HelloWorld
45+
dotr HelloWorld
3846
```
3947

4048

@@ -52,5 +60,5 @@ scala>
5260
or via bash:
5361

5462
```bash
55-
$ ./bin/dotr
63+
$ dotr
5664
```

‎docs/docs/contributing/intellij-idea.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,10 @@ title: Building Dotty with Intellij IDEA
66
Setup
77
-----
88

9-
You can setup IntelliJ [IDEA >= 2016.1](https://www.jetbrains.com/idea/nextversion) to contribute to Dotty.
9+
You can setup IntelliJ [IDEA >= 2016.1](https://www.jetbrains.com/idea/nextversion) to run Dotty.
1010

11-
Assuming you have cloned dotty's repository from Github you can now proceed with importing it to IDEA by selecting the
11+
Assuming you have cloned dotty's repository from Github (and run `sbt managedSources` as described in [Getting Started](getting-started.md))
12+
you can now proceed with importing it to IDEA by selecting the
1213
corresponding option from the startup menu. Navigate on the corresponding directory and select it. Next, you need
1314
to select the model of the import and as the screenshot shows, select SBT.
1415

‎docs/docs/contributing/testing.md

Lines changed: 13 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,6 @@ layout: doc-page
33
title: Testing in Dotty
44
---
55

6-
<aside class="warning">
7-
This page should be updated as soon as scala-partest is removed
8-
</aside>
9-
106
Running all tests in Dotty is as simple as:
117

128
```bash
@@ -21,63 +17,39 @@ These tests can be found in `<sub-project>/test` and are used to check
2117
functionality of specific parts of the codebase in isolation e.g: parsing,
2218
scanning and message errors.
2319

24-
Running a single unit test class from sbt is as simple as:
20+
To run all tests in e.g., for the compiler test-suite you can write:
2521

2622
```bash
27-
> testOnly absolute.path.to.TestClass
23+
> dotty-compiler/test
2824
```
2925

30-
You can further restrict the executed tests to a subset of `TestClass` methods
31-
as follows:
26+
To run a single test class you use `testOnly` and the fully qualified class name.
27+
For example:
3228

3329
```bash
34-
> testOnly absolute.path.to.TestClass -- *methodName
30+
> dotty-compiler/testOnly dotty.tools.dotc.transform.TreeTransformerTest
3531
```
3632

37-
## Integration tests
38-
These tests are Scala source files expected to compile with Dotty (pos tests),
39-
along with their expected output (run tests) or errors (neg tests).
40-
41-
All of these tests are contained in the `./tests/*` directories.
42-
43-
## scala-partest
44-
Historically these tests needed a structure which was generated by running the
45-
unit tests, and then that structure was in turn used by
46-
[scala-partest](http://github.com/scala/scala-partest) to run compilation tests
47-
in parallel.
48-
49-
This test suite can still be used (and is currently a part of the CI to check
50-
that it has the same outcome as the new test suite). It is invoked from sbt by
51-
running one of the following commands:
33+
You can further restrict the executed tests to a subset of methods by appending ``-- *method_name``
34+
as in the example below:
5235

5336
```bash
54-
> partest-only-no-bootstrap
55-
> partest-only
56-
> partest
37+
> dotty-compiler/testOnly dotty.tools.dotc.transform.TreeTransformerTest -- *canOverwrite
5738
```
5839

59-
- `partest-only-no-bootstrap` will only run the integration tests
60-
- `partest-only` will bootstrap the compiler and run the integration tests
61-
- `partest` will bootstrap the compiler, run the unit tests and then the
62-
integration tests
63-
64-
## dotty parallel test suite
65-
The new test suite will soon become the standard integration test runner. It
66-
has several advantages over the old implementation:
40+
## Integration tests
41+
These tests are Scala source files expected to compile with Dotty (pos tests),
42+
along with their expected output (run tests) or errors (neg tests).
6743

68-
- integrates with JUnit, without the need for setup
69-
- reuses the same VM for compilation
70-
- allows filtering of tests
71-
- runs much faster (almost 2x)
44+
All of these tests are contained in the `./tests/*` directories.
7245

7346
Currently to run these tests you need to invoke from sbt:
7447

7548
```bash
7649
> testOnly dotty.tools.dotc.CompilationTests
7750
```
7851

79-
This might be aliased in the future. It is also possible to run tests filtered
80-
by using:
52+
It is also possible to run tests filtered by using the `vulpix` command, again from sbt:
8153

8254
```bash
8355
> vulpix i2147.scala

‎docs/docs/contributing/workflow.md

Lines changed: 9 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,20 @@ layout: doc-page
33
title: Workflow
44
---
55

6-
This document details common workflow patterns when working with Dotty.
7-
8-
## Cloning and building ##
9-
10-
```bash
11-
# Start by cloning the repository:
12-
git clone --recursive https://github.com/lampepfl/dotty.git
13-
cd dotty
14-
```
6+
Check [Getting Started](getting-started.md) for instructions on how to obtain the source code of dotty and
7+
[Eclipse](eclipse.md) or [IntelliJ-IDEA](intellij-idea.md).
8+
This document details common workflow patterns when working with Dotty before using the debugging tools.
159

1610
## Compiling files with dotc ##
1711

18-
From sbt:
12+
As we have seen you can compile a test file either from sbt:
1913

2014
```bash
2115
$ sbt
2216
> dotc <OPTIONS> <FILE>
2317
```
2418

25-
From terminal:
19+
or from terminal:
2620

2721
```bash
2822
$ ./bin/dotc <OPTIONS> <FILE>
@@ -40,25 +34,10 @@ Here are some useful debugging `<OPTIONS>`:
4034
`Ycheck`ed, therefore in the tests we run:
4135
`-Ycheck:tailrec,resolveSuper,mixin,restoreScopes,labelDef`.
4236

43-
Additional logging information can be obtained by changes some `noPrinter` to
37+
More powerful logging capabilities can be enabled by changing some `noPrinter` to
4438
`new Printer` in `compiler/src/dotty/tools/dotc/config/Printers.scala`. This enables the
4539
`subtyping.println("")` and `ctx.traceIndented("", subtyping)` style logging.
4640

47-
## Running single tests ##
48-
To test a specific test tests/x/y.scala (for example tests/pos/t210.scala):
49-
50-
```bash
51-
> vulpix pos/t210.scala
52-
```
53-
54-
The `vulpix` task uses its argument for a substring test. For example, you
55-
could run both a negative and a positive test with the same name
56-
(`pos/i2101.scala` & `neg/i2101.scala`):
57-
58-
```bash
59-
> vulpix i2101.scala
60-
```
61-
6241
## Inspecting Trees with Type Stealer ##
6342

6443
There is no power mode for the REPL yet, but you can inspect types with the
@@ -71,7 +50,7 @@ scala> import dotty.tools.DottyTypeStealer._; import dotty.tools.dotc.core._; im
7150

7251
Now, you can define types and access their representation. For example:
7352

74-
```scala
53+
```bash
7554
scala> val s = stealType("class O { type X }", "O#X")
7655
scala> implicit val ctx: Context = s._1
7756
scala> val t = s._2(0)
@@ -84,3 +63,5 @@ u: dotty.tools.dotc.core.Types.Type = TypeBounds(TypeRef(ThisType(TypeRef(NoPref
8463
Many objects in the dotc compiler implement a `Showable` trait (e.g. `Tree`,
8564
`Symbol`, `Type`). These objects may be prettyprinted using the `.show`
8665
method
66+
67+
To contribute to dotty please follow the [Dotty Developer Guidelines](https://github.com/lampepfl/dotty/blob/master/CONTRIBUTING.md).

‎docs/docs/index.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,17 @@ layout: doc-page
33
title: "Dotty Documentation"
44
---
55

6-
The Dotty compiler is currently somewhat lacking in documentation - PRs
7-
welcome! But, we've attempted to gather the most essential knowledge in these
8-
pages.
6+
Dotty is a platform to try out new language concepts and compiler technologies for Scala.
7+
The focus is mainly on simplification. We remove extraneous syntax (e.g. no XML literals),
8+
and try to boil down Scala’s types into a smaller set of more fundamental constructors.
9+
The theory behind these constructors is researched in DOT, a calculus for dependent object types.
10+
11+
In this documentation you will find information on how to use the Dotty compiler on your machine, navigate through
12+
the code, setup Dotty with your favorite IDE and more!
13+
14+
Contents
15+
-------
916

10-
Index
11-
-----
1217
* Usage
1318
- [Migrating from Scala 2](usage/migrating.md)
1419
- [Dotty projects with cbt](usage/cbt-projects.md)

‎docs/docs/resources/talks.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ title: Talks
66
Talks on Dotty
77
--------------
88
- (ScalaDays 2016, Berlin) [Scala's Road Ahead](https://www.youtube.com/watch?v=GHzWqJKFCk4) by Martin Odersky [\[slides\]](http://www.slideshare.net/Odersky/scala-days-nyc-2016)
9+
910
- (JVMLS 2015) [Compilers are Databases](https://www.youtube.com/watch?v=WxyyJyB_Ssc) by Martin Odersky [\[slides\]](http://www.slideshare.net/Odersky/compilers-are-databases)
1011

1112
Deep Dive with Dotty

‎docs/images/eclipse/eclipse-import.png

155 KB
Loading

‎docs/images/eclipse/eclipse-runconfiguration.png

208 KB
Loading

0 commit comments

Comments
 (0)