diff options
Diffstat (limited to 'subprojects/docs/src/develop/contributing/ide-setup.md')
-rw-r--r-- | subprojects/docs/src/develop/contributing/ide-setup.md | 94 |
1 files changed, 94 insertions, 0 deletions
diff --git a/subprojects/docs/src/develop/contributing/ide-setup.md b/subprojects/docs/src/develop/contributing/ide-setup.md new file mode 100644 index 00000000..742035e0 --- /dev/null +++ b/subprojects/docs/src/develop/contributing/ide-setup.md | |||
@@ -0,0 +1,94 @@ | |||
1 | --- | ||
2 | SPDX-FileCopyrightText: 2021-2023 The Refinery Authors | ||
3 | SPDX-License-Identifier: EPL-2.0 | ||
4 | sidebar_position: 2 | ||
5 | title: IDE setup | ||
6 | --- | ||
7 | |||
8 | # Setting up the development environment | ||
9 | |||
10 | ## IntelliJ IDEA | ||
11 | |||
12 | We prefer [IntelliJ IDEA](https://www.jetbrains.com/idea/) as a Java development environment. | ||
13 | No special preparations should be necessary for importing the project as a Gradle project into IDEA: | ||
14 | |||
15 | 1. See the [required tools](/develop/contributing#required-tools) for compiling Refinery about obtaining the required JDK version. You'll also need a version of IntelliJ IDEA that supports **Java 21** (version **2023.3** or later). | ||
16 | |||
17 | 2. Clone the project git repository and open it in IntelliJ IDEA. Make sure to _open_ the project instead of creating a _new_ one in the same directory. | ||
18 | |||
19 | 3. IntelliJ IDEA should build and index the project. If there are errors, it is likely that the `JAVA_HOME` was incorrectly set: | ||
20 | * In _Project Structure > Project settings > Project > SDK_, a Java 21 compatible JDK should be selected. | ||
21 | * In _Project Structure > Project settings > Project > Language level_, either _SDK default_ or _21_ should be selected. | ||
22 | * Make sure that each module in _Project Structure > Project settings > Module_ uses the _Project default_ language level in _Sources > Language level_ and the _Project SDK_ in _Dependencies > Module SDK._ | ||
23 | * In _Settings > Gradle settings > Gralde Projects > Gradle_, the _Distribution_ should be set to _Wrapper_ and the _Gradle JVM_ should be set to _Project SDK._ | ||
24 | |||
25 | 4. We recommend installing the latest _SonarLint_ plugin in _Settings > Plugins_ to get real-time code quality analysis in your IDE. | ||
26 | |||
27 | :::note | ||
28 | |||
29 | You'll need [Eclipse](#eclipse) to edit Xtext (`*.xtext`) and MWE2 (`*.mwe2`) files and Ecore class diagrams (`*.aird`, `*.ecore`, `*.genmodel`). | ||
30 | If you do not plan on making changes to such files, feel free to skip the Eclipse installation steps below. | ||
31 | |||
32 | You'll also need [VS Code](#vs-code) to edit the TypeScript code in Refinery. | ||
33 | |||
34 | ::: | ||
35 | |||
36 | ## Eclipse | ||
37 | |||
38 | 1. See the [required tools](/develop/contributing#required-tools) for compiling Refinery about obtaining the required JDK version. | ||
39 | |||
40 | 2. Download and extract the [Eclipse IDE for Java and DSL Developers 2023-12](https://www.eclipse.org/downloads/packages/release/2023-12/r/eclipse-ide-java-and-dsl-developers) package. | ||
41 | |||
42 | 3. Launch Eclipse and create a new workspace. | ||
43 | |||
44 | 4. Open _Help > Eclipse Marketplace_ and install the following software: | ||
45 | * _EclEmma Java Code Coverage_ | ||
46 | * _EcoreTools : Ecore Diagram Editor_ | ||
47 | * _Sirius_ (ignore the warning during installation about the solution _Sirius_ not being available) | ||
48 | * _SonarLint_ | ||
49 | |||
50 | 5. Open _Window > Preferences_ and set the following preferences: | ||
51 | * _General > Workspace > Text file encoding_ should be _UTF-8_. | ||
52 | * _General > Workspace > New text file line delimiter_ should be _Unix_. | ||
53 | * Add the JDK 21 to _Java > Installed JREs_. | ||
54 | * Make sure JDK 21 is selected for _JavaSE-21_ at _Java > Installed JREs > Execution Environments_. | ||
55 | * Set _Gradle > Java home_ to the `JAVA_HOME` directory (the directory which contains the `bin` directory) of JDK 21. Here, Buildship will show a yellow warning sign, which can be safely ignored. | ||
56 | * Set _Java > Compiler > JDK Compliance > Compiler compliance level_ to _21_. | ||
57 | |||
58 | 6. Clone the project Git repository but _do not_ import it into Eclipse yet. | ||
59 | |||
60 | 7. Open a new terminal and run | ||
61 | ```bash posix2windows | ||
62 | ./gradlew prepareEclipse | ||
63 | ``` | ||
64 | in the cloned repository. | ||
65 | * This should complete without any compilation errors. | ||
66 | * To troubleshoot any error, see the [instructions about compiling Refinery](/develop/contributing#compiling). | ||
67 | |||
68 | 8. Select _File > Import... > Gradle > Existing Gradle Project_ and import the cloned repository in Eclipse. | ||
69 | * Make sure to select the root of the repository (containing this file) as the _Project root directory_ and that the _Gradle distribution_ is _Gradle wrapper_. | ||
70 | * If you have previously imported the project into Eclipse, this step will likely fail. In that case, you should remove the projects from Eclipse, run `git clean -fxd` in the repository, and start over from step 8. | ||
71 | |||
72 | ## VS Code | ||
73 | |||
74 | We recommend [VSCodium](https://github.com/VSCodium/vscodium) or [Visual Studio Code](https://code.visualstudio.com/) to work with the parts of Refinery that are written is TypeScript. | ||
75 | |||
76 | 1. See the [required tools](/develop/contributing#required-tools) for compiling Refinery about obtaining the required JDK version. You'll also need a version of IntelliJ IDEA that supports **Java 21** (version **2023.3** or later). | ||
77 | |||
78 | 2. Install the following VS Code extensions: | ||
79 | * _EditorConfig for VS Code_ [[Open VSX](https://open-vsx.org/extension/EditorConfig/EditorConfig)] [[Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)] | ||
80 | * _ZipFS - a zip file system_ [[Open VSX](https://open-vsx.org/extension/arcanis/vscode-zipfs)] [[Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=arcanis.vscode-zipfs)] | ||
81 | * _ESLint_ [[Open VSX](https://open-vsx.org/extension/dbaeumer/vscode-eslint)] [[Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)] | ||
82 | * _XState VSCode_ [[Open VSX](https://open-vsx.org/extension/statelyai/stately-vscode)] [[Extension Marketplace](https://marketplace.visualstudio.com/items?itemName=statelyai.stately-vscode)] | ||
83 | |||
84 | 3. Clone the project Git repository but _do not_ import it into VS Code yet. | ||
85 | |||
86 | 4. Run | ||
87 | ```bash posix2windows | ||
88 | ./gradlew installFrontend | ||
89 | ``` | ||
90 | to install all required Node.js tooling. | ||
91 | |||
92 | 5. Open the repository with _Open Folder…_ in VS Code. | ||
93 | * When asked, select that you _Trust_ the folder. | ||
94 | * When asked, enable using the TypeScript and ESLint tooling specified in the repository. | ||