document mojos

courses/GettingHelp/GettingHelp.md

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

courses/GettingStarted/CreateNewProject/CreateNewProject.md

@@ -21,9 +21,7 @@ import util::Reflective;
 newRascalProject(|home:///my-project-name|)
 ```
 
-The Eclipse plugin has a "New Project Wizard" you can use as well.
-
-The next step is to import the new project into VS Code or Eclipse, or
+The next step is to import the new project into VScode, or
 to `cd` to the project's root directory. From there on ((RunningRascal))
 with the new project's source and library settings is trivial.
 
@@ -51,8 +49,7 @@ The `pom.xml` file is the basic setup that names the project and defines its dep
 ```
 
 Next to that `RASCAL.MF` is required to configure the development environment for the project. Some
-information from the `pom.xml` is repeated here, because this file is common between Eclipse, VS Code and empty commandline projects,
-and such projects could work with a `pom.xml`:
+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`:
 
 ```MF
 ((|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
 ```rascal
 ((|home:///my-project-name/src/main/rascal/Main.rsc|))
 ```
+
+#### Benefits
+
+* The ((newRascalProject)) sets up a project for use with the Rascal ((MavenPlugin)).
+
+#### Pitfalls
+
+* 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

@@ -6,8 +6,7 @@ sidebar_position: 1
 Rascal is deployed as one of four easy-to-use packages:
 
 1. **A standalone "jar" file**, which can be downloaded [here](https://update.rascal-mpl.org/console/rascal-shell-stable.jar)
-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.
-3. An **Eclipse plugin**, for which the update site is <https://update.rascal-mpl.org/stable/>.
-4. A set of **Maven MOJOs**, for which the plugin repository is <https://releases.usethesource.io/maven/>
+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.
+4. A ((MavenPlugin)) with a set of Rascal Mojo's, for which the plugin repository is <https://releases.usethesource.io/maven/>
 
 See ((RunningRascal)) for what to do next.

courses/GettingStarted/MavenPlugin/CompileMojo/CompileMojo.md

@@ -0,0 +1,136 @@
+---
+title: Compile Mojo
+keywords:
+    - compile
+    - maven
+    - goal
+    - "rascal:compile"
+---
+
+#### Synopsis
+
+Basic project configuration for Rascal projects, checking, compilation and running.
+
+#### Decription
+
+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.
+
+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:
+1. The Rascal compiler is made available to the project via adding a proper `<plugin>` tag for the `rascal-maven-plugin`. 
+1. Dependencies on other Rascal or JVM-based projects are declared in with `<dependency>` tags.
+1. Running `mvn compile` or `mvn package` or `mvn install` will trigger the compiler, reporting errors, warnings and other information on the go.
+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.
+1. All binary target files end up in the `./target/classes` folder
+1. With `mvn package` and `mvn install` the ((PackageMojo)) finally stores all target code in a `.jar` file.
+1. Repeated executions of `mvn compile` make sure to check and compile only the changed Rascal modules. 
+1. `mvn clean` cleans the target folders to make sure everything is checked and compiled from scratch.
+
+#### Input/output behavior
+
+| *Input* | *Output* | *Description* |
+| ------- | -------- | ------------ |
+| Module.rsc | Module.tpl       | "TModel" that encodes the binary interface of a compiled module. |
+|      "     | Module.constants | Constant values which are references by generated bytecode.      |
+|      "     | $Module.java     | Java source code that implements a Rascal module.                |
+|      "     | $Module.parsers  | Pre-generated parsers as used by `$Module.java`                  |
+|      "     | $ModuleTests.java | (Parametrized) JUnit tests extracted from `Module.rsc`          | 
+
+Next to these files the compiler outputs messages and their origin location:
+* `[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.
+* `[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.
+* `[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.
+
+The configuration tags for the compile mojo are an extended subset of the standard fields of ((data:PathConfig)).
+The defaults are chosen such that you hardly have to use these tags.
+
+| *Configuration tag* | *Default* | *Description* |
+| ------------------- | ----------| ------------- |
+| `<srcs>`            | `<src>./src/main/rascal</src>` | list of directories where `.rsc` files can be found |
+| `<libs>`            | filled with `<dependencies>` | list of jar files or directories for the library dependencies |
+| `<ignores>`         | empty     | list of folders and files to skip while compiling |
+| `<generatedSources>` | `./target/generated-sources` | where the compiler stores intermediate Java code |
+| `<bin>`             | `./target/classes` | where the binary output of the compiler is staged before it goes into the jar file |
+| `<logPathConfig>` | false | write the pathConfig to the log before compiling |
+| `<logImports>` | false | write imports and extends of each module to the log during compilation |
+| `<logWrittenFiles>` | false | log every file written including timestamp during compilation |
+| `<warnUnused>` | true | warn about unused declarations |
+| `<warnedUnusedFormals>` | true | warn about unused formal parameters (pattern variables of function signatures) |
+| `<warnUnusedPatternFormals>` | true | warn about unused  variables in patterns |
+| `<errorsAsWarnings>` | false | with this the compiler never reports failure in the presence of errors |
+| `<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` |
+| `<parallel>` | false | enables parallel compilation of a large group of `.rsc` source files |
+| `<parallelMax>` | `5` | restricts the number of parallel compiler processes. The mojo otherwises
+computes an estimate based on the number of processors and the available memory |
+| `<parallelPrechecks>` | empty | a list of files reachable from `<srcs>` that will be compiled before the
+other processes start. |
+| `<verbose>` | enables internal debugging prints of the compiler |
+
+#### Examples
+
+The compiler is configured in `pom.xml` in three locations:
+* `<dependencies>...</dependencies>` - each dependency leads to a compile-time library path entry, and a run-time JVM classpath entry.
+* the general `<configuration>...</configuration>` tags for Rascal mojos:
+```xml
+<plugins>
+    <plugin>
+        <groupId>org.rascalmpl</groupId>
+        <artifactId>rascal-maven-plugin</artifactId>
+        <version>${rascal-maven-plugin.version}</version>
+        <configuration>
+        ...configuration tags go here...
+        </configuration>
+    </plugin>
+</plugins>
+```
+* and finally the specific `<configuration>...</configuration>` tag for the `compile` goal.
+```xml
+ <plugin>
+    <groupId>org.rascalmpl</groupId>
+    <artifactId>rascal-maven-plugin</artifactId>
+    <version>${rascal-maven-plugin.version}</version>
+    <executions>
+        <execution>
+            <!-- "default-compile" works best, "default-cli" only if used only once -->
+            <id>default-compile</id> 
+            <phase>compile</phase>
+            <goals>
+                <!-- it is possible to bind to other goals, but not recommended> -->
+                <goal>compile</goal>
+            </goals>
+            <configuration>
+               .... configuration tags go here ....
+            </configuration>
+        </execution>
+    </executions>
+</plugin>
+```
+* The latter overwrites the first, tag-by-tag
+
+Maven is typically executed on the Un*x or Windows commandline like so:
+```bash
+# Typically runs the compiler and the tests before packaging everything 
+# in a jar file,  and copying it to your local Maven repository:
+mvn install
+
+# like `install` but without copying to the Maven repository;
+mvn package 
+
+# If configured as above in an `<execution>` This will run only the Rascal compiler
+mvn rascal:compile 
+
+# runs everything _except the Rascal compiler_
+mvn install -Drascal.compile.skip 
+```
+
+#### Benefits
+
+* The Maven configuration, including the dependencies listed in `pom.xml` enable reuse of other Rascal programs as libraries or development tools.
+* 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`
+* The rascal:compile mojo works find with multi-module Maven projects and parent projects.
+
+#### Pitfalls
+
+* 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._
+* The rascal:compile mojo is fully configured from the pom.xml. Other sources of configuration
+may still uses the `Sources` fields in `RASCAL.MF`. This discrepancy will be resolved in the coming months.
+* ((getProjectPathConfig)) may produce different configurations for source folders for the same reason.

courses/GettingStarted/MavenPlugin/ConsoleMojo/ConsoleMojo.md

@@ -0,0 +1,65 @@
+---
+title: Console Mojo
+---
+
+#### Synopsis
+
+The console mojo starts up a Rascal terminal. 
+
+
+#### Description
+
+It will be configured to read the source code of the current
+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.
+
+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))
+
+```MANIFEST.MF
+Project-Name: test-project
+Source: src
+
+```
+
+#### Examples
+
+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:
+
+```bash
+13:17:51 test-project$ mvn rascal:console
+[INFO] Scanning for projects...
+[INFO] 
+[INFO] -------------------------< org.rascalmpl:demo >-------------------------
+[INFO] Building demo 1.0-SNAPSHOT
+[INFO]   from pom.xml
+[INFO] --------------------------------[ jar ]---------------------------------
+[INFO] 
+[INFO] --- rascal:0.31.0:console (default-cli) @ demo ---
+[INFO] The Rascal runtime was resolved at /Users/jurgenv/.m2/repository/org/rascalmpl/rascal/0.42.1/rascal-0.42.1.jar
+[INFO] pom.xml: Rascal version is 0.42.1
+[INFO] pom.xml: Project root is |file:///Users/jurgenv/git/test-project/|
+[INFO] pom.xml: Bin folder   is |file:///Users/jurgenv/git/test-project/target/classes|
+[INFO] pom.xml: Source module path is:
+  - |std:///|
+  - |file:///Users/jurgenv/git/test-project/src|
+[INFO] pom.xml: Library module (and classes) path is:
+  - |file:///Users/jurgenv/.m2/repository/org/rascalmpl/rascal/0.42.1/rascal-0.42.1.jar|
+2026-03-26T12:17:55.247168Z main ERROR Log4j API could not find a logging provider.
+rascal>import IO;
+ok
+rascal>println("Hello World!")
+Hello World!
+ok
+rascal>
+```
+
+#### Benefits
+
+* when you edit a file in between REPL commands, the REPL will automatically reload Rascal modules and provide warnings and errors if needed.
+
+
+#### Pitfalls
+
+* 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:
+   1. stop the terminal using `:quit`
+   2. type `mvn compile`
+   3. restart the terminal using `mvn rascal:console`

courses/GettingStarted/MavenPlugin/ExecMojo/ExecMojo.md

@@ -0,0 +1,33 @@
+---
+title: Exec Mojo
+---
+
+#### Synopsis
+
+Start arbitrary Java code from the current project or one of its dependencies during a Maven run.
+
+#### Description
+
+The default configuration required for ((CompileMojo)) is the starting point. To
+this you may add:
+
+```pom.xml
+<!-- add the name of a main module to start to the configuration -->
+<configuration>
+   <mainModule>MyExampleMainModule</mainModule>
+</configuration>
+
+<executions>
+    <execution>
+        <id>it-compile</id>
+        <!-- any phase will do, but people often use generate-test-sources -->
+        <phase>generate-test-sources</phase>
+        <goals>
+            <goal>exec</goal> <!-- the goal must be "exec" to select the current Mojo -->
+        </goals>
+    </execution>
+</executions>
+```
+
+The `MyExampleMainModule` must have a `main` function. If this main function has a `PathConfig pcfg=pathConfig()` keyword parameter,
+then the maven plugin will provide the configuration of the current project there.

courses/GettingStarted/MavenPlugin/MavenPlugin.md

@@ -0,0 +1,48 @@
+---
+title: Maven Plugin
+sidebar_position: 4
+details:
+  - mvn
+  - maven
+  - compile
+  - tutor
+  - exec
+  - package
+---
+
+The [rascal-maven-plugin](http://github.com/usethesource/rascal-maven-plugin) offers these Maven plugins for dealing with Rascal projects:
+* ((CompileMojo)) for static checking and compiling Rascal projects.
+* ((TutorMojo)) for generating API docs, and compiling documentation courses.
+* ((PackageMojo)) for packing compiled Rascal code, source code and documentation into a jar file. 
+* ((ExecMojo)) for executing arbitrary Rascal code during an arbitrary Maven goal.
+* ((ConsoleMojo)) for starting a Rascal ((REPL))
+
+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:
+* `mvn rascal:compile` runs the compiler and `-Drascal.compile.skip` guarantees it is skipped.
+* `mvn rascal:tutor` runs the tutor compiler and `-Drascal.tutor.skip` guarantees it is skipped.
+* `mvn rascal:package` runs the package rewriter and `-Drascal.package.skip` guarantees it is skipped.
+* `mvn rascal:exec` executes some Rascal code, while `-Drascal.exec.skip` makes sure this goal is skipped.
+
+#### Examples
+
+This is a typical `pom.xml` file configuring  the *rascal-maven-plugin* that will provide everything
+necessary for a Rascal project, except the ((TutorMojo)). This is also the setup that is generated by the ((newRascalProject)) function:
+
+```rascal-prepare
+import util::Reflective;
+newRascalPomFile(|tmp:///my-project|);
+```
+
+```xml
+((|tmp:///my-project/pom.xml|))
+```
+
+#### Benefits
+
+* Almost zero configuration (due to sensible defaults) for projects that have:
+   * Rascal source code in `/src/main/rascal`
+   * Dependencies listed in `pom.xml` `<dependency>` tags
+* 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.
+* 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.
+* Rascal projects can depend on any other Maven project
+

courses/GettingStarted/MavenPlugin/PackageMojo/PackageMojo.md

@@ -0,0 +1,26 @@
+---
+title: Package Mojo
+---
+
+#### Synopsis
+
+Prepare compiler output files for distribution in a jar file, and downstream usage in projects and IDEs.
+
+#### Description
+
+The `prepare` plugin takes care of:
+    * copying source files to the target folder, for later reference by debuggers (source distribution)
+    * 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.
+
+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.
+
+The mojo makes ample use of the `mvn:///` scheme to refer to project dependencies unambiguously.
+
+#### Benefits
+
+* this enables debugging library projects, including the standard library, with browsing and breakpoint support inside of distributed files.
+* this makes sure source files are in the proper place for depending projects to find them.
+
+#### Pitfalls
+
+* 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

@@ -0,0 +1,11 @@
+---
+title: Tutor Mojo
+---
+
+#### Synopsis
+
+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.
+
+#### Description
+
+(((TODO)))

courses/GettingStarted/RunningRascal/RunningRascal.md

@@ -6,7 +6,7 @@ sidebar_position: 2
 #### Running Rascal: starting a terminal with a read-eval-print-loop
 
 1. On the Unix or Windows [Commandline]((RunningRascal-Commandline)), start a ((RascalShell)) by: `java -jar rascal-<version>.jar`
-2. In [VS Code]((RunningRascal-VScode)), in the command palette type `Rascal` and select `Create Rascal Terminal`
+2. In [VScode]((RunningRascal-VScode)), in the command palette type `Rascal` and select `Create Rascal Terminal`
 4. With Maven, ((CreateNewProject)) first and then type: `mvn rascal:console`
 
 You will be prompted for input right after the version is printed and a lot of information about the current searchpath configuration. 

courses/Rascal/Errors/CompileTimeErrors/ModuleImport/ModuleImport.md

@@ -28,9 +28,6 @@ This can be caused by
 Remedies:
 
 *  Correct the mispelled name.
-*  In Eclipse the safest way to execute a Rascal module is to select it in the Package Explorer, 
-right click on it and then select `Run as Rascal Application`.
-
 *  At the command line, change directory to where the toplevel module of your program is located and then execute the Rascal Shell.
 
 #### Examples