Skip to content

Fix #2180: Docs update #2422

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
May 15, 2017
Merged

Fix #2180: Docs update #2422

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6e46455
Update IDEA and talks
biboudis May 10, 2017
796222c
Improve Eclipse documentation, workflow and testing
biboudis May 12, 2017
6f04a90
Improve Eclipse/IDEA pages
biboudis May 12, 2017
f769faa
Update sidebar
biboudis May 12, 2017
2024307
Add some minor stylistic aspects
biboudis May 12, 2017
36d96f8
Make sbt eclipse command clearer
biboudis May 12, 2017
0acf3ba
Adjust command prompts and improve description of testOnly syntax
biboudis May 15, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 29 additions & 21 deletions docs/docs/contributing/backend.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
---
layout: doc-page
title: Working with the backend
title: Working with the Backend
---

The compiler backend is based on a fork of the Scala 2.11 `GenBCode` backend and
lives at https://github.com/lampepfl/scala/tree/sharing-backend. The dotty
source tree contains a git submodule in the directory
lives at

> https://github.com/lampepfl/scala/tree/sharing-backend.

The dotty source tree contains a git submodule in the directory
[scala-backend](https://github.com/lampepfl/dotty/tree/master/scala-backend)
that points to this fork. We do not compile every file in this submodule,
instead we add the subset of files we need to the dotty-compiler project in the
Expand All @@ -16,39 +19,44 @@ their content is not automatically updated when you do `git checkout` or `git
pull`, instead everytime you switch branch, you need to do:

``` shell
git submodule update --init
$ git submodule update --init
```

## Environment setup

1. Set the following git configuration options to make working with submodules
easier, see the [Git Book](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
1. Set the following git configuration options to make working with submodules easier,
see the [Git Book](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
for more information:
``` shell
git config --global diff.submodule log
git config --global status.submodulesummary 1
git config --global push.recurseSubmodules check
$ git config --global diff.submodule log
$ git config --global status.submodulesummary 1
$ git config --global push.recurseSubmodules check
```

2. Fork https://github.com/lampepfl/scala (in the following commands,
`dotty-staging/scala` is used as a placeholder for your
own fork).
3. ```shell
cd scala-backend
git remote add scala-staging [email protected]:dotty-staging/scala.git
cd ..
```
2. Fork scala from github

> https://github.com/lampepfl/scala

(in the following commands, `dotty-staging/scala` is used as a placeholder for your own fork).

3. Add the new remote to track the upstream branch
```shell
$ cd scala-backend
$ git remote add scala-staging [email protected]:dotty-staging/scala.git
$ cd ..
```

## Workflow when changing to the backend

```shell
cd scala-backend
git checkout -b my-feature-branch
$ cd scala-backend
$ git checkout -b my-feature-branch

# Make some changes ...
$ git push -u scala-backend

git push -u scala-backend
# Open a PR against https://github.com/lampepfl/scala/tree/sharing-backend
cd ..
$ cd ..
```

Once your PR has been merged into the backend, you'll need to make another PR
Expand Down
10 changes: 5 additions & 5 deletions docs/docs/contributing/debug-tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ Both are usually pre-installed on Mac OS and linux distributions.

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

```
bin/dotc tests/debug/while.scala
```shell
$ dotc tests/debug/while.scala
```

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

```
bin/dotr -d Test
```shell
dotr -d Test
```

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

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

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

```Scala
object Test {
Expand Down
55 changes: 40 additions & 15 deletions docs/docs/contributing/eclipse.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,30 +3,55 @@ layout: doc-page
title: Building Dotty with Eclipse
---

Build setup
Setup
-----------

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

2. It is recommended to change the default output folder (in `Properties > java
Assuming you have cloned dotty's repository from Github (and run `sbt managedSources` as described in
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Eclipse, you need to run sbt ;managedSources;eclipse

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This point still needs to be fixed

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added the sbt eclipse in the line below!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see it?

[Getting Started](getting-started.md)) you can now proceed to set up Dotty with Eclipse. In addition to the previous
command you need to run `sbt eclipse` to generate the project structure for Eclipse.
Copy link
Contributor Author

@biboudis biboudis May 12, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ping @smarter

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah I see now, thanks. But I would prefer to not leave this critical command inside a line of text, I think it'd be better to have it in a real code block.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Basically something like:

1. Follow the instructions in the [Getting Started](...) page
2. Generate the Eclipse configuration files:
```
sbt eclipse
```


- Note: 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:
Optional: if you have `CLASSPATH` defined:

3. Update your classpath to contain any new required external libraries to run
1. Update your classpath to contain any new required external libraries to run
`./bin/dotc`, `./bin/dotr` outside of Eclipse.

4. Open the `Run Configurations` tab, and edit the `tests` configuration so
1. Open the `Run Configurations` tab, and edit the `tests` configuration so
that it contains a `CLASSPATH` variable which reflects the current
`CLASSPATH`.


Import to Eclipse
-----------------

First step is to import dotty to Eclipse. This is done by selecting `File > Import` from the menu and selecting
_Existing Projects into Workplace_.

![](../../images/eclipse/eclipse-import.png "Import Dotty to Eclipse")

On the next window, select the bare minimum configuration to run Dotty. You will need the compiler, library and the
interfaces.

![](../../images/eclipse/eclipse-select.png "Import Dotty Projects")


Running/Debugging
---------------------------------------------------

To run/debug Dotty you have to create a new configuration from `Run > Run Configurations`. First select the project on the
package explorer and then select the aforementioned option. On the `Main` tab you must have `dotty-compiler` for the
_Project_ and `dotty.tools.dotc.Main` for the _Main class_. Specify the arguments you want for the compiler on the
`Arguments` tab (e.g, flags and source files) and then proceed to the `Classpath` tab. There you must
specify three `Bootstrap Entries` which are the compiler, interfaces and the library as shown in the screenshot below.
Additionally you need to specify the scala-asm library as an external jar dependency. This can be found on your local
`~/.ivy2/cache/` directory.

![](../../images/eclipse/eclipse-runconfiguration.png "Import Dotty Projects")

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}/tests/pos/HelloWorld.scala`
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).
35 changes: 16 additions & 19 deletions docs/docs/contributing/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,9 @@ layout: doc-page
title: 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`
Make sure that you are using Java 8 or later. The output of `java -version`
should contain `1.8`.

Compiling and Running
Expand All @@ -26,11 +15,11 @@ Start by cloning the repository:
```bash
$ git clone --recursive https://github.com/lampepfl/dotty.git
$ cd dotty
$ sbt managedSources ## Needed for IDE import to succeed
$ sbt managedSources # Needed for IDE import to succeed
```

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

```bash
$ sbt
Expand All @@ -39,13 +28,21 @@ $ sbt
hello world
```

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

```bash
```shell
export PATH=$HOME/dotty/bin:$PATH
```

and you will be able to run the corresponding commands directly from your console:

```shell
# Compile code using Dotty
./bin/dotc tests/pos/HelloWorld.scala
dotc tests/pos/HelloWorld.scala

# Run it with the proper classpath
./bin/dotr HelloWorld
dotr HelloWorld
```


Expand All @@ -63,5 +60,5 @@ scala>
or via bash:

```bash
$ ./bin/dotr
$ dotr
```
72 changes: 49 additions & 23 deletions docs/docs/contributing/intellij-idea.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,33 +3,59 @@ layout: doc-page
title: 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.
Setup
-----

## To create a new project with Dotty
You can setup IntelliJ [IDEA >= 2016.1](https://www.jetbrains.com/idea/nextversion) to run Dotty.

1. Open New Project dialog and select `Scala` > `Dotty`
2. Proceed as usual and don't forget to create or select Dotty SDK.
Assuming you have cloned dotty's repository from Github (and run `sbt managedSources` as described in [Getting Started](getting-started.md))
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

, at the end of this line for inner voice to be able to take a breath.

you can now proceed with importing it to IDEA by selecting the
corresponding option from the startup menu. Navigate on the corresponding directory and select it. Next, you need
to select the model of the import and as the screenshot shows, select SBT.

## To compile an existing Scala project with Dotty
![](../../images/idea/idea-import.png "Import Dotty in IDEA")

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`
Next, you select the version of the JDK that this project relies on and verify that you have selected 1.8 (assuming
its installed on your local machine). Otherwise, specify it by pressing *New*.

Java 1.8 should be used as the Project/Module SDK. You also need to enable the
Scala Compile Server to use Dotty compiler.
![](../../images/idea/idea-sdk.png "Select the JDK")

## 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]
On the final window we must select which modules we can import. Here, we are presented with the full list of SBT projects
that are defined in Dotty. You can either select all (expect performance degradation by IDEA if you select all) or
select only the `dotty` module. In order to do that, unselect all modules and select on `dotty`. IDEA, then, automatically
selects all the necessary dependencies and you press OK.

[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
![](../../images/idea/idea-sbt.png "Select modules to import")

Running/Debugging
-------

To run the compiler you can do it either as an sbt command or via debugging the compiler.
For the first option you can fire up sbt from the `Terminal` window of IDEA or you can do it externally.
For example, to run a test you can write with or without flags:

```shell
dotc tests/pos/Arrays.scala
```

If you are interested in debugging the compiler you can enable the necessary agent on the JVM.
This is done in two steps. For the first step you need to pass the
necessary flag to the running VM. For convenience, this is already in comments on the `Build.scala` file under the
`project` directory. The string you need to uncomment is the following:

> `"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005"`

Uncomment the line and reload the project file with the `reload` command on sbt.
Now, each time you run `dotc` the compiler listens at the designated address and waits the agent to connect.
For, the second step you need to create a configuration for Debug through IDEA:

> Run > Edit Configurations > Add New Configuration > (select) Remote

![](../../images/idea/idea-debug.png "Create a Debug Configuration")

Now every time you run `dotc` you can set your breakpoints and hit the `Debug dotty-debug` button (since we used that name for
the sample configuration above). The default data on the configuration match the enabled agent on the VM so, probably,
you will not need to change anything else.

To contribute to dotty please follow the [Dotty Developer Guidelines](https://github.com/lampepfl/dotty/blob/master/CONTRIBUTING.md).

Loading