Skip to content

Commit 26bf6d8

Browse files
DedelweissDedelweiss
committed
Sync Contributing section from dotty website to Scala 3 Contributing Guide
- For this sync I choosed some pages to keep and others not.
1 parent 86fe255 commit 26bf6d8

23 files changed

+771
-28
lines changed

‎_overviews/scala3-contribution/arch-context.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Contexts
33
type: section
44
description: This page describes symbols in the Scala 3 compiler.
5-
num: 15
5+
num: 17
66
previous-page: arch-lifecycle
77
next-page: arch-phases
88
---

‎_overviews/scala3-contribution/arch-intro.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
title: High Level Architecture
33
type: chapter
44
description: This page introduces the high level architecture of the Scala 3 compiler.
5-
num: 13
6-
previous-page: procedures-checklist
5+
num: 15
6+
previous-page: procedures-vulpix
77
next-page: arch-lifecycle
88
---
99

‎_overviews/scala3-contribution/arch-lifecycle.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Compiler Overview
33
type: section
44
description: This page describes the lifecycle for the Scala 3 compiler.
5-
num: 14
5+
num: 16
66
previous-page: arch-intro
77
next-page: arch-context
88
---

‎_overviews/scala3-contribution/arch-phases.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Compiler Phases
33
type: section
44
description: This page describes the phases for the Scala 3 compiler.
5-
num: 16
5+
num: 18
66
previous-page: arch-context
77
next-page: arch-types
88
---

‎_overviews/scala3-contribution/arch-symbols.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
title: Symbols
33
type: section
44
description: This page describes symbols in the Scala 3 compiler.
5-
num: 19
5+
num: 21
66
previous-page: arch-time
7-
next-page:
7+
next-page: ides-tools-intro
88
---
99

1010
As discussed previously, `dotc` [maintains time-indexed views][arch-time] of various

‎_overviews/scala3-contribution/arch-time.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Time in the Compiler
33
type: section
44
description: This page describes the concepts of time in the Scala 3 compiler.
5-
num: 18
5+
num: 20
66
previous-page: arch-types
77
next-page: arch-symbols
88
---

‎_overviews/scala3-contribution/arch-types.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Compiler Types
33
type: section
44
description: This page discusses the representation of types in the compiler
5-
num: 17
5+
num: 19
66
previous-page: arch-phases
77
next-page: arch-time
88
---

‎_overviews/scala3-contribution/contribution-intro.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,11 @@ another programming language.
4343
As an example, `dotc` takes text input, verifies that it is a valid Scala program
4444
and then produces as output the same program, but written in Java bytecode, and optionally
4545
in SJSIR when producing Scala.js output.
46+
47+
### Contribute Internals-related Knowledge
48+
If you know anything useful at all about Dotty, feel free to log this knowledge:
49+
50+
- [📜Log the Knowledge](https://github.com/lampepfl/dotty-knowledge/issues/new)
51+
- [🎓More about Logging the Knowledge](https://github.com/lampepfl/dotty-knowledge/blob/master/README.md)
52+
53+
In short, no need to make it pretty, particularly human-readable or give it a particular structure. Just dump the knowledge you have and we'll take it from there.

‎_overviews/scala3-contribution/ides-tools-ide.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: IDEs
3+
type: section
4+
description: This page describes how to use IDEs with Dotty.
5+
num: 23
6+
previous-page: ides-tools-intro
7+
next-page: ides-tools-mill
8+
---
9+
10+
# Using an IDE
11+
12+
You can use either Metals (VS Code, vim) or IntelliJ IDEA as described on the
13+
IDE sections of the [getting-started page](https://docs.scala-lang.org/scala3/getting-started.html) to work
14+
on the Scala 3 codebase. There are however a few additional considerations to take into account.
15+
16+
17+
## Bootstrapping Projects
18+
19+
The sbt build for dotty implements bootstrapping within the same build, so each component has
20+
two projects:
21+
22+
```
23+
sbt:scala3> projects
24+
...
25+
[info] scala3-compiler
26+
[info] scala3-compiler-bootstrapped
27+
...
28+
```
29+
30+
These duplicated projects can be confusing and cause issues in IDEs.
31+
32+
When using Metals, the `-bootstrapped` projects are not exported.
33+
34+
In IntelliJ IDEA, we recommend importing the dotty codebase through BSP, then the `-bootstrapped`
35+
projects are not exported.
36+
37+
38+
## Scala Version warning in Metals
39+
40+
When using VS Code, Metals might show a warning that the Scala version (`3.0.0-[...]-NIGHTLY`)
41+
is not supported. The reason is that the dotty repository sometimes uses a nightly build as
42+
reference compiler. The IDE experience is going to be limited in this case (semantic features will
43+
only within single files).

‎_overviews/scala3-contribution/ides-tools-intro.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: IDEs and Tools
3+
type: chapter
4+
description: This page describes how to use IDEs and tools with Dotty.
5+
num: 22
6+
previous-page: arch-symbols
7+
next-page: ides-tools-ide
8+
---
9+
10+
This chapter of the guide describes how to use IDEs and tools with Dotty.
11+
12+
- How to use [IDEs] with Dotty
13+
- How to use [Mill] with Dotty
14+
- How to use [Scalafix] with Dotty
15+
16+
[ides]: {% link _overviews/scala3-contribution/ides-tools-ide.md %}
17+
[mill]: {% link _overviews/scala3-contribution/ides-tools-mill.md %}
18+
[scalafix]: {% link _overviews/scala3-contribution/ides-tools-scalafix.md %}

‎_overviews/scala3-contribution/ides-tools-mill.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: Mill
3+
type: section
4+
description: This page describes how to use Mill with Dotty.
5+
num: 24
6+
previous-page: ides-tools-ide
7+
next-page: ides-tools-scalafix
8+
---
9+
10+
# Basic Operations with Mill
11+
12+
Here's an example of how to test a project that uses mill:
13+
14+
```bash
15+
mill utest.jvm[2.12.8].test
16+
```
17+
18+
- `utest.jvm` - the name of the compiled module (obtain from `build.sc`)
19+
- `2.12.8` – Scala cross-compile version
20+
- `test` – task to run on the module specified with the specified Scala version
21+
22+
To get mill of the most recent version, first, find it in https://github.com/lihaoyi/mill/releases (e.g. `0.4.2-1-020e28`). Copy the download link and substitute it in the following command instead of `https://github.com/lihaoyi/mill/releases/download/0.4.1/0.4.1`:
23+
24+
```bash
25+
# From http://www.lihaoyi.com/mill/
26+
sudo sh -c '(echo "#!/usr/bin/env sh" && curl -L https://github.com/lihaoyi/mill/releases/download/0.4.1/0.4.1) > /usr/local/bin/mill && chmod +x /usr/local/bin/mill'
27+
```

‎_overviews/scala3-contribution/ides-tools-scalafix.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: Scalafix
3+
type: section
4+
description: This page describes how to use Scalafix with Dotty.
5+
num: 25
6+
previous-page: ides-tools-mill
7+
next-page:
8+
---
9+
10+
# Working with Scalafix
11+
12+
First, create a new rule as follows (command from [scalacenter](https://scalacenter.github.io/scalafix/docs/developers/setup.html)):
13+
14+
```bash
15+
sbt new scalacenter/scalafix.g8 --repo="Repository Name"
16+
```
17+
18+
To run the rule against some codebase:
19+
20+
```bash
21+
scalafix -r file:scalafix/rules/src/main/scala/fix/YourRule.scala your/code/base/
22+
```
23+
24+
Where `YourRule.scala` is the rule you developed and `your/code/base` is the code base you are running the rule against.

‎_overviews/scala3-contribution/procedures-areas.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
title: Common Issue Locations
33
type: section
44
description: This page describes common areas of issues around the Scala 3 compiler.
5-
num: 8
6-
previous-page: procedures-navigation
5+
num: 9
6+
previous-page: procedures-other-debugging
77
next-page: procedures-inspection
88
---
99

‎_overviews/scala3-contribution/procedures-cheatsheet.md

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,17 +14,18 @@ For more in-depth explanations, see the rest of this chapter.
1414

1515
The following commands can be run within `sbt` in the dotty directory:
1616

17-
| Commands |
18-
|-----------------------------------------------------------------------------------------------|
19-
| `testCompilation` Run compilation tests on files that match the first argument. |
20-
| `scala3/scalac` Run the compiler directly, with any current changes. |
21-
| `scala3/scala` Run the main method of a given class name. |
22-
| `repl` Start a REPL with the bootstrapped compiler. |
23-
| `testOnly *CompilationTests -- *pos` Run test `pos` from the compilation test suite. |
24-
| `scala3-compiler/Test/runMain dotty.tools.printTypes` Print types underlying representation |
25-
| `scala3/scalac -print-tasty Foo.tasty` Print the TASTy of top-level class `Foo` |
26-
| `scala3-bootstrapped/test` Run all tests for Scala 3. (Slow, recommended for CI only) |
27-
| `scala3-bootstrapped/publishLocal` Build Scala 3 locally. (Use to debug a specific project) |
17+
| Commands | Description |
18+
|---------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
19+
| `testCompilation sample` | In all test suites, run test files containing the word `sample` in their title. |
20+
| `scala3/scalac` | Run the compiler directly, with any current changes. |
21+
| `scala3/scala` | Run the main method of a given class name. |
22+
| `repl` | Start a REPL with the bootstrapped compiler. |
23+
| `testOnly *CompilationTests -- *pos` | Run test `pos` from the compilation test suite. |
24+
| `scala3-compiler/Test/runMain dotty.tools.printTypes` | Print types underlying representation |
25+
| `scala3/scalac -print-tasty Foo.tasty` | Print the TASTy of top-level class `Foo` |
26+
| `scala3-bootstrapped/test` | Run all tests for Scala 3. (Slow, recommended for CI only) |
27+
| `scala3-bootstrapped/publishLocal` | Build Scala 3 locally. (Use to debug a specific project) |
28+
| `scalac ../issues/Playground.scala` | Compile the given file – path relative to the Dotty directory. Output the compiled class files to the Dotty directory itself. |
2829

2930
## Shell Commands
3031

‎_overviews/scala3-contribution/procedures-checklist.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
title: Pull Request Checklist
33
type: section
44
description: This page describes a checklist before opening a Pull Request to the Scala 3 compiler.
5-
num: 12
5+
num: 13
66
previous-page: procedures-testing
7-
next-page: arch-intro
7+
next-page: procedures-vulpix
88
---
99

1010
Once you solved the issue you were working on, you'll likely want to see your

‎_overviews/scala3-contribution/procedures-debugging.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ type: section
44
description: This page describes navigating around the Scala 3 compiler.
55
num: 7
66
previous-page: procedures-navigation
7-
next-page: procedures-areas
7+
next-page: procedures-other-debugging
88
---
99

1010
The debugger is a powerful tool to navigate the internals of the compiler and track bugs.

‎_overviews/scala3-contribution/procedures-efficiency.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Improving Your Workflow
33
type: section
44
description: This page describes improving efficiency of debugging the Scala 3 compiler.
5-
num: 10
5+
num: 11
66
previous-page: procedures-inspection
77
next-page: procedures-testing
88
---

‎_overviews/scala3-contribution/procedures-inspection.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: How to Inspect Values
33
type: section
44
description: This page describes inspecting semantic values in the Scala 3 compiler.
5-
num: 9
5+
num: 10
66
previous-page: procedures-areas
77
next-page: procedures-efficiency
88
---

‎_overviews/scala3-contribution/procedures-intro.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ This chapter introduces instructions
1313
on how to do basic tasks when fixing compiler issues. The tasks include:
1414
- how to [reproduce an issue][reproduce]
1515
- how to [navigate to where the issue manifests][navigation] itself in the compiler
16+
- How to [debug the compiler][debugging]
17+
- But also some other [debugging techniques][other-debugging]
1618
- find shortcuts to [common issue areas][areas] of the compiler
1719
- how to [inspect various values][inspection] encountered in the compiler
1820
- how to [create a test][testing] for your fix.
@@ -24,3 +26,5 @@ You can find the instructions of how to do the above in the following sections o
2426
[areas]: {% link _overviews/scala3-contribution/procedures-areas.md %}
2527
[inspection]: {% link _overviews/scala3-contribution/procedures-inspection.md %}
2628
[testing]: {% link _overviews/scala3-contribution/procedures-testing.md %}
29+
[debugging]: {% link _overviews/scala3-contribution/procedures-debugging.md %}
30+
[other-debugging]: {% link _overviews/scala3-contribution/procedures-other-debugging.md %}

0 commit comments

Comments
 (0)