document mojos

courses/GettingHelp/GettingHelp.md

@@ -30,7 +30,6 @@ 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 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

@@ -8,8 +8,7 @@ import IO;
 remove(|home:///my-project-name|, recursive=true);
 ```
 
-Rascal projects, generally, work the same in all three IDE contexts:
-* Eclipse
+Rascal projects, generally, work the same in all IDE contexts:
 * VScode
 * Commandline
 
@@ -22,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 VScode 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.
 
@@ -52,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, VScode 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|))
@@ -64,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

@@ -7,7 +7,6 @@ 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 VScode 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/>
+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,132 @@
+---
+title: Compile Mojo
+keywords:
+    - compile
+    - maven
+    - goal
+    - "rascal:compile"
+---
+
+All Rascal projects are assumed to be configured via a Maven `pom.xml` file. To use the Rascal compler 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.
+
+#### Configuring the compiler with Maven
+
+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
+
+The configuration tags are an extended subset of the standard fields of ((util::Reflective::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
+
+Maven is typically executed on the Un*x or Windows commandline like so:
+```bash
+#! /bin/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,3 @@
+---
+title: Console Mojo
+---

courses/GettingStarted/MavenPlugin/ExecMojo/ExecMojo.md

@@ -0,0 +1,4 @@
+---
+title: Exec Mojo
+---
+

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,3 @@
+---
+title: Package Mojo
+---

courses/GettingStarted/MavenPlugin/TutorMojo/TutorMojo.md

@@ -0,0 +1,4 @@
+---
+title: Tutor Mojo
+---
+

courses/GettingStarted/RunningRascal/RunningRascal.md

@@ -7,7 +7,6 @@ sidebar_position: 2
 
 1. On the Unix or Windows [Commandline]((RunningRascal-Commandline)), start a ((RascalShell)) by: `java -jar rascal-<version>.jar`
 2. In [VScode]((RunningRascal-VScode)), in the command palette type `Rascal` and select `Create Rascal Terminal`
-3. In [Eclipse]((RunningRascal-Eclipse)), from the button bar select the button with the Rascal logo.
 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/GettingStarted/Troubleshooting/StackOverflow/StackOverflow.md

@@ -12,7 +12,6 @@ To be able to generate parsers Rascal uses stack space from the Java Virtual Mac
 
 If you get exceptions better configure your JVM with this `-Xss32m`
 
-* For Eclipse, this configuration goes into your `eclipse.ini` file. See ((EditingEclipseIni)) for more information.
 * On the commandline, you can use `java -Xss32m ...`
 * In VScode the Rascal language server already configures this automatically.
 * The same for the Rascal Maven plugins; they are configured with big stack sizes.

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

courses/RascalAmendmentProposals/RAP10/RAP10.md

@@ -12,7 +12,7 @@ sidebar_position: 10
 
 ## Abstract
 
-Rascal can be executed in JVM threads (as in the Eclipse context for example) and also we plan to add concurrency features to Rascal itself ((RAP8)). This puts a lot more pressure on our IO mechanism than before, leading to races on disk and on other external resources identified by values of type `loc`.
+Rascal can be executed in JVM threads and also we plan to add concurrency features to Rascal itself ((RAP8)). This puts a lot more pressure on our IO mechanism than before, leading to races on disk and on other external resources identified by values of type `loc`.
 
 We propose to extend the URIResolverRegistry (which is Rascal’s generic resource access mechanism) with a cross-cutting “locking” feature that is safe (up to *unpredicted* aliasing of location URIs). 
 
@@ -21,7 +21,7 @@ A second part of the proposal is to expose this locking feature on the language
 ## Motivation
 
 * Many use cases of Rascal involve file IO  
-  * Often in a dynamic context where multiple file processors read and write concurrently, such as the Eclipse IDE or an LSP server.  
+  * Often in a dynamic context where multiple file processors read and write concurrently, such as the an LSP server.  
   * More and more in a concurrent and even parallel context, where multi-core architectures are used to speed up larger computations  
 * File IO is hazardous in a concurrent context, due to race conditions  
 * So, we need some form of locking mechanism on file IO.