Skip to content

Commit 804239e

Browse files
jurgenvinjujurgenvinju
authored
Merge pull request #64 from usethesource/document-mojos
document mojos
2 parents 157de57 + 02b8cbd commit 804239e

File tree

18 files changed

+348
-43
lines changed

18 files changed

+348
-43
lines changed

‎courses/GettingHelp/GettingHelp.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,7 @@ details:
3030
3. The (open) issues registered with [Github Issues](http://github.com/usethesource/rascal/issues)
3131
* Directly in the Rascal IDE there is help available:
3232
1. On the commandline, type `:help`
33-
2. In Eclipse there is the `Tutor View` which opens all the documentation pages inside Eclipse.
34-
3. In VS Code use the command palette and search for `Rascal` for more commands.
33+
3. In VScode use the command palette and search for `Rascal` for more commands.
3534
* For specific application topics, "Howto" kind of information, etc. please go to ((FurtherReading)).
3635
* There is a lot of documentation on Rascal and its libraries. Read the ((Browsing)) page on how to navigate it.
3736

‎courses/GettingStarted/CreateNewProject/CreateNewProject.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,7 @@ import util::Reflective;
2121
newRascalProject(|home:///my-project-name|)
2222
```
2323

24-
The Eclipse plugin has a "New Project Wizard" you can use as well.
25-
26-
The next step is to import the new project into VS Code or Eclipse, or
24+
The next step is to import the new project into VScode, or
2725
to `cd` to the project's root directory. From there on ((RunningRascal))
2826
with the new project's source and library settings is trivial.
2927

@@ -51,8 +49,7 @@ The `pom.xml` file is the basic setup that names the project and defines its dep
5149
```
5250

5351
Next to that `RASCAL.MF` is required to configure the development environment for the project. Some
54-
information from the `pom.xml` is repeated here, because this file is common between Eclipse, VS Code and empty commandline projects,
55-
and such projects could work with a `pom.xml`:
52+
information from the `pom.xml` is repeated here, because this file is common between VScode and empty commandline projects, and such projects should work with a `pom.xml`:
5653

5754
```MF
5855
((|home:///my-project-name/META-INF/RASCAL.MF|))
@@ -63,3 +60,11 @@ And finally in `src/main/rascal` you'll find the Rascal source files, as configu
6360
```rascal
6461
((|home:///my-project-name/src/main/rascal/Main.rsc|))
6562
```
63+
64+
#### Benefits
65+
66+
* The ((newRascalProject)) sets up a project for use with the Rascal ((MavenPlugin)).
67+
68+
#### Pitfalls
69+
70+
* In `RASCAL.MF` the `Sources` configuration option is deprecated and will soon be replaced by pom.xml's `<srcs>` tag in `pom.xml`.

‎courses/GettingStarted/DownloadAndInstallation/DownloadAndInstallation.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,7 @@ sidebar_position: 1
66
Rascal is deployed as one of four easy-to-use packages:
77

88
1. **A standalone "jar" file**, which can be downloaded [here](https://update.rascal-mpl.org/console/rascal-shell-stable.jar)
9-
2. A **Visual Studio Code extension**, which can be found [here](https://marketplace.visualstudio.com/items?itemName=usethesource.rascalmpl) or search for "Rascal" in the "Extension" view in VS Code itself.
10-
3. An **Eclipse plugin**, for which the update site is <https://update.rascal-mpl.org/stable/>.
11-
4. A set of **Maven MOJOs**, for which the plugin repository is <https://releases.usethesource.io/maven/>
9+
2. A **Visual Studio Code extension**, which can be found [here](https://marketplace.visualstudio.com/items?itemName=usethesource.rascalmpl) or search for "Rascal" in the "Extension" view in VScode itself.
10+
4. A ((MavenPlugin)) with a set of Rascal Mojo's, for which the plugin repository is <https://releases.usethesource.io/maven/>
1211

1312
See ((RunningRascal)) for what to do next.

‎courses/GettingStarted/MavenPlugin/CompileMojo/CompileMojo.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: Compile Mojo
3+
keywords:
4+
- compile
5+
- maven
6+
- goal
7+
- "rascal:compile"
8+
---
9+
10+
#### Synopsis
11+
12+
Basic project configuration for Rascal projects, checking, compilation and running.
13+
14+
#### Decription
15+
16+
The `compile` mojo calls the Rascal static checker and compiler on the source code in a Rascal project. Also it uses information from the libraries the current project depends on (including the standard library). The configuration here is also the core of the configuration for the other maven plugins.
17+
18+
All Rascal projects are assumed to be configured via a Maven `pom.xml` file. To use the Rascal compiler via the `mvn rascal:compile` goal:
19+
1. The Rascal compiler is made available to the project via adding a proper `<plugin>` tag for the `rascal-maven-plugin`.
20+
1. Dependencies on other Rascal or JVM-based projects are declared in with `<dependency>` tags.
21+
1. Running `mvn compile` or `mvn package` or `mvn install` will trigger the compiler, reporting errors, warnings and other information on the go.
22+
1. Other compilers, such as the Java compiler are also triggered, such that code that interacts between Rascal and Java can be loaded and executed later.
23+
1. All binary target files end up in the `./target/classes` folder
24+
1. With `mvn package` and `mvn install` the ((PackageMojo)) finally stores all target code in a `.jar` file.
25+
1. Repeated executions of `mvn compile` make sure to check and compile only the changed Rascal modules.
26+
1. `mvn clean` cleans the target folders to make sure everything is checked and compiled from scratch.
27+
28+
#### Input/output behavior
29+
30+
| *Input* | *Output* | *Description* |
31+
| ------- | -------- | ------------ |
32+
| Module.rsc | Module.tpl | "TModel" that encodes the binary interface of a compiled module. |
33+
| " | Module.constants | Constant values which are references by generated bytecode. |
34+
| " | $Module.java | Java source code that implements a Rascal module. |
35+
| " | $Module.parsers | Pre-generated parsers as used by `$Module.java` |
36+
| " | $ModuleTests.java | (Parametrized) JUnit tests extracted from `Module.rsc` |
37+
38+
Next to these files the compiler outputs messages and their origin location:
39+
* `[ERROR]` messages report on mistakes made in `Module.rsc` that prevent the proper execution of (a part of) a `Module.rsc`. Erroneous code is not executable.
40+
* `[WARNING]` messages report on likely issues in `Module.rsc`; for example likely to be incomplete and throw an exception, or likely to never match and be dead, etc.
41+
* `[INFO]` messages provide information useful for understanding advanced features of Rascal or hint at to be deprecated behavior that a programmer might prepare themselves for.
42+
43+
The configuration tags for the compile mojo are an extended subset of the standard fields of ((data:PathConfig)).
44+
The defaults are chosen such that you hardly have to use these tags.
45+
46+
| *Configuration tag* | *Default* | *Description* |
47+
| ------------------- | ----------| ------------- |
48+
| `<srcs>` | `<src>./src/main/rascal</src>` | list of directories where `.rsc` files can be found |
49+
| `<libs>` | filled with `<dependencies>` | list of jar files or directories for the library dependencies |
50+
| `<ignores>` | empty | list of folders and files to skip while compiling |
51+
| `<generatedSources>` | `./target/generated-sources` | where the compiler stores intermediate Java code |
52+
| `<bin>` | `./target/classes` | where the binary output of the compiler is staged before it goes into the jar file |
53+
| `<logPathConfig>` | false | write the pathConfig to the log before compiling |
54+
| `<logImports>` | false | write imports and extends of each module to the log during compilation |
55+
| `<logWrittenFiles>` | false | log every file written including timestamp during compilation |
56+
| `<warnUnused>` | true | warn about unused declarations |
57+
| `<warnedUnusedFormals>` | true | warn about unused formal parameters (pattern variables of function signatures) |
58+
| `<warnUnusedPatternFormals>` | true | warn about unused variables in patterns |
59+
| `<errorsAsWarnings>` | false | with this the compiler never reports failure in the presence of errors |
60+
| `<warningsAsErrors>` | false | with this the compiler reports failure even if there are only warnings and no errors. Can not be true at the same time with `errorsAsWarnings` |
61+
| `<parallel>` | false | enables parallel compilation of a large group of `.rsc` source files |
62+
| `<parallelMax>` | `5` | restricts the number of parallel compiler processes. The mojo otherwises
63+
computes an estimate based on the number of processors and the available memory |
64+
| `<parallelPrechecks>` | empty | a list of files reachable from `<srcs>` that will be compiled before the
65+
other processes start. |
66+
| `<verbose>` | enables internal debugging prints of the compiler |
67+
68+
#### Examples
69+
70+
The compiler is configured in `pom.xml` in three locations:
71+
* `<dependencies>...</dependencies>` - each dependency leads to a compile-time library path entry, and a run-time JVM classpath entry.
72+
* the general `<configuration>...</configuration>` tags for Rascal mojos:
73+
```xml
74+
<plugins>
75+
<plugin>
76+
<groupId>org.rascalmpl</groupId>
77+
<artifactId>rascal-maven-plugin</artifactId>
78+
<version>${rascal-maven-plugin.version}</version>
79+
<configuration>
80+
...configuration tags go here...
81+
</configuration>
82+
</plugin>
83+
</plugins>
84+
```
85+
* and finally the specific `<configuration>...</configuration>` tag for the `compile` goal.
86+
```xml
87+
<plugin>
88+
<groupId>org.rascalmpl</groupId>
89+
<artifactId>rascal-maven-plugin</artifactId>
90+
<version>${rascal-maven-plugin.version}</version>
91+
<executions>
92+
<execution>
93+
<!-- "default-compile" works best, "default-cli" only if used only once -->
94+
<id>default-compile</id>
95+
<phase>compile</phase>
96+
<goals>
97+
<!-- it is possible to bind to other goals, but not recommended> -->
98+
<goal>compile</goal>
99+
</goals>
100+
<configuration>
101+
.... configuration tags go here ....
102+
</configuration>
103+
</execution>
104+
</executions>
105+
</plugin>
106+
```
107+
* The latter overwrites the first, tag-by-tag
108+
109+
Maven is typically executed on the Un*x or Windows commandline like so:
110+
```bash
111+
# Typically runs the compiler and the tests before packaging everything
112+
# in a jar file, and copying it to your local Maven repository:
113+
mvn install
114+
115+
# like `install` but without copying to the Maven repository;
116+
mvn package
117+
118+
# If configured as above in an `<execution>` This will run only the Rascal compiler
119+
mvn rascal:compile
120+
121+
# runs everything _except the Rascal compiler_
122+
mvn install -Drascal.compile.skip
123+
```
124+
125+
#### Benefits
126+
127+
* The Maven configuration, including the dependencies listed in `pom.xml` enable reuse of other Rascal programs as libraries or development tools.
128+
* The Maven configuration, with the dependencies listed in `pom.xml` enable reuse of other JVM-based projects in the Maven Grand Central, or other repositories listed in the `pom.xml`
129+
* The rascal:compile mojo works find with multi-module Maven projects and parent projects.
130+
131+
#### Pitfalls
132+
133+
* The current rascal:compile mojo executes the static checker and generates a `.tpl` TModel for every Rascal `.rsc` source file. The`.tpl` file enables modular checking against the "binary" interface of other imported and extended modules. _The JVM bytecode generator is not active yet._
134+
* The rascal:compile mojo is fully configured from the pom.xml. Other sources of configuration
135+
may still uses the `Sources` fields in `RASCAL.MF`. This discrepancy will be resolved in the coming months.
136+
* ((getProjectPathConfig)) may produce different configurations for source folders for the same reason.

‎courses/GettingStarted/MavenPlugin/ConsoleMojo/ConsoleMojo.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Console Mojo
3+
---
4+
5+
#### Synopsis
6+
7+
The console mojo starts up a Rascal terminal.
8+
9+
10+
#### Description
11+
12+
It will be configured to read the source code of the current
13+
project, as configured in the `META-INF/RASCAL.MF` file, and it load modules from library projects in jar files, as configured in the `pom.xml` file.
14+
15+
The console mojo does not require further configuration in the pom file, other than the project's dependencies (see ((CompileMojo))). The `RASCAL.MF` file needs a `Sources` field. See also ((CreateNewProject))
16+
17+
```MANIFEST.MF
18+
Project-Name: test-project
19+
Source: src
20+
21+
```
22+
23+
#### Examples
24+
25+
This is an example execution runnig `mvn rascal:console` in the folder `test-project` which holds a `pom.xml` and a `META-INF/RASCAL.MF` file:
26+
27+
```bash
28+
13:17:51 test-project$ mvn rascal:console
29+
[INFO] Scanning for projects...
30+
[INFO]
31+
[INFO] -------------------------< org.rascalmpl:demo >-------------------------
32+
[INFO] Building demo 1.0-SNAPSHOT
33+
[INFO] from pom.xml
34+
[INFO] --------------------------------[ jar ]---------------------------------
35+
[INFO]
36+
[INFO] --- rascal:0.31.0:console (default-cli) @ demo ---
37+
[INFO] The Rascal runtime was resolved at /Users/jurgenv/.m2/repository/org/rascalmpl/rascal/0.42.1/rascal-0.42.1.jar
38+
[INFO] pom.xml: Rascal version is 0.42.1
39+
[INFO] pom.xml: Project root is |file:///Users/jurgenv/git/test-project/|
40+
[INFO] pom.xml: Bin folder is |file:///Users/jurgenv/git/test-project/target/classes|
41+
[INFO] pom.xml: Source module path is:
42+
- |std:///|
43+
- |file:///Users/jurgenv/git/test-project/src|
44+
[INFO] pom.xml: Library module (and classes) path is:
45+
- |file:///Users/jurgenv/.m2/repository/org/rascalmpl/rascal/0.42.1/rascal-0.42.1.jar|
46+
2026-03-26T12:17:55.247168Z main ERROR Log4j API could not find a logging provider.
47+
rascal>import IO;
48+
ok
49+
rascal>println("Hello World!")
50+
Hello World!
51+
ok
52+
rascal>
53+
```
54+
55+
#### Benefits
56+
57+
* when you edit a file in between REPL commands, the REPL will automatically reload Rascal modules and provide warnings and errors if needed.
58+
59+
60+
#### Pitfalls
61+
62+
* when you write Java code and link it to Rascal using the `java` modified (see ((Declarations-Function))), the terminal console is not able to pick up new versions of the Java class files without a restart. In this case:
63+
1. stop the terminal using `:quit`
64+
2. type `mvn compile`
65+
3. restart the terminal using `mvn rascal:console`

‎courses/GettingStarted/MavenPlugin/ExecMojo/ExecMojo.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Exec Mojo
3+
---
4+
5+
#### Synopsis
6+
7+
Start arbitrary Java code from the current project or one of its dependencies during a Maven run.
8+
9+
#### Description
10+
11+
The default configuration required for ((CompileMojo)) is the starting point. To
12+
this you may add:
13+
14+
```pom.xml
15+
<!-- add the name of a main module to start to the configuration -->
16+
<configuration>
17+
<mainModule>MyExampleMainModule</mainModule>
18+
</configuration>
19+
20+
<executions>
21+
<execution>
22+
<id>it-compile</id>
23+
<!-- any phase will do, but people often use generate-test-sources -->
24+
<phase>generate-test-sources</phase>
25+
<goals>
26+
<goal>exec</goal> <!-- the goal must be "exec" to select the current Mojo -->
27+
</goals>
28+
</execution>
29+
</executions>
30+
```
31+
32+
The `MyExampleMainModule` must have a `main` function. If this main function has a `PathConfig pcfg=pathConfig()` keyword parameter,
33+
then the maven plugin will provide the configuration of the current project there.

‎courses/GettingStarted/MavenPlugin/MavenPlugin.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: Maven Plugin
3+
sidebar_position: 4
4+
details:
5+
- mvn
6+
- maven
7+
- compile
8+
- tutor
9+
- exec
10+
- package
11+
---
12+
13+
The [rascal-maven-plugin](http://github.com/usethesource/rascal-maven-plugin) offers these Maven plugins for dealing with Rascal projects:
14+
* ((CompileMojo)) for static checking and compiling Rascal projects.
15+
* ((TutorMojo)) for generating API docs, and compiling documentation courses.
16+
* ((PackageMojo)) for packing compiled Rascal code, source code and documentation into a jar file.
17+
* ((ExecMojo)) for executing arbitrary Rascal code during an arbitrary Maven goal.
18+
* ((ConsoleMojo)) for starting a Rascal ((REPL))
19+
20+
Each of the above is configured in XML in the local `pom.xml` file of a Rascal project. All of them are executed during a `mvn package` or `mvn install` commandline. If the local pom has the right configuration, then each mojo can also be invoked separately:
21+
* `mvn rascal:compile` runs the compiler and `-Drascal.compile.skip` guarantees it is skipped.
22+
* `mvn rascal:tutor` runs the tutor compiler and `-Drascal.tutor.skip` guarantees it is skipped.
23+
* `mvn rascal:package` runs the package rewriter and `-Drascal.package.skip` guarantees it is skipped.
24+
* `mvn rascal:exec` executes some Rascal code, while `-Drascal.exec.skip` makes sure this goal is skipped.
25+
26+
#### Examples
27+
28+
This is a typical `pom.xml` file configuring the *rascal-maven-plugin* that will provide everything
29+
necessary for a Rascal project, except the ((TutorMojo)). This is also the setup that is generated by the ((newRascalProject)) function:
30+
31+
```rascal-prepare
32+
import util::Reflective;
33+
newRascalPomFile(|tmp:///my-project|);
34+
```
35+
36+
```xml
37+
((|tmp:///my-project/pom.xml|))
38+
```
39+
40+
#### Benefits
41+
42+
* Almost zero configuration (due to sensible defaults) for projects that have:
43+
* Rascal source code in `/src/main/rascal`
44+
* Dependencies listed in `pom.xml` `<dependency>` tags
45+
* When using the ((getProjectPathConfig)) function from ((util::Reflective)), and a local `pom.xml` is available, then the produced configuration will be influenced by what is configured in the `pom.xml` file as well.
46+
* All dependencies defined in the `pom.xml` are used to automatically configure the library path of the compiler and the interpreter, as well as the classpath of the compiled or interpreted runtime engine.
47+
* Rascal projects can depend on any other Maven project
48+

‎courses/GettingStarted/MavenPlugin/PackageMojo/PackageMojo.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: Package Mojo
3+
---
4+
5+
#### Synopsis
6+
7+
Prepare compiler output files for distribution in a jar file, and downstream usage in projects and IDEs.
8+
9+
#### Description
10+
11+
The `prepare` plugin takes care of:
12+
* copying source files to the target folder, for later reference by debuggers (source distribution)
13+
* renaming file references in generated code and interface files (`.tpl` and `.constant`) such that they point to the distributed location and not the source project location.
14+
15+
This mojo creates a fresh copy of the target build directory with the renamed entities, and then configures downstream processors to continue with the new directory rather than the old. The `jar` mojo then eventually packages the right files into the jar file.
16+
17+
The mojo makes ample use of the `mvn:///` scheme to refer to project dependencies unambiguously.
18+
19+
#### Benefits
20+
21+
* this enables debugging library projects, including the standard library, with browsing and breakpoint support inside of distributed files.
22+
* this makes sure source files are in the proper place for depending projects to find them.
23+
24+
#### Pitfalls
25+
26+
* this distributes your source code in the main jar file for your project. If you don't want this, then don't use the plugin. However, with the current interpreted it is not possible to depend on libraries which do not distribute their source code.

‎courses/GettingStarted/MavenPlugin/TutorMojo/TutorMojo.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: Tutor Mojo
3+
---
4+
5+
#### Synopsis
6+
7+
Compiles tutor markdown files in a specific folder hierarchy, and Rascal modules from source folders to a comprehensive collection of documentation files in markdown format.
8+
9+
#### Description
10+
11+
(((TODO)))

‎courses/GettingStarted/RunningRascal/RunningRascal.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ sidebar_position: 2
66
#### Running Rascal: starting a terminal with a read-eval-print-loop
77

88
1. On the Unix or Windows [Commandline]((RunningRascal-Commandline)), start a ((RascalShell)) by: `java -jar rascal-<version>.jar`
9-
2. In [VS Code]((RunningRascal-VScode)), in the command palette type `Rascal` and select `Create Rascal Terminal`
9+
2. In [VScode]((RunningRascal-VScode)), in the command palette type `Rascal` and select `Create Rascal Terminal`
1010
4. With Maven, ((CreateNewProject)) first and then type: `mvn rascal:console`
1111

1212
You will be prompted for input right after the version is printed and a lot of information about the current searchpath configuration.

0 commit comments

Comments
 (0)