|
| 1 | +--- |
| 2 | +title: Compile Mojo |
| 3 | +keywords: |
| 4 | + - compile |
| 5 | + - maven |
| 6 | + - goal |
| 7 | + - "rascal:compile" |
| 8 | +--- |
| 9 | + |
| 10 | +The `rascal:compile` mojo is executed by default with the `compile` goal of Maven. For every Rascal module in the `srcs` list of configured source modules, it will generate a binary `.tpl` TModule file. It typechecks all the modules which have an older timestamp on their corresponding binary output `.tpl` file, and the downstream damage triggered by these recompile. |
| 11 | + |
| 12 | +The main output for the user is a list of INFO, WARNING and ERROR messages, including their origin location. The compiler produces errors when the source code is not executable at that point. It generates errors, when it is likely the generated code will throw exceptions at run-time or otherwise fail to behave as expected. Information messages are reserved for hinting at deprecated uses of the language or libraries. |
| 13 | + |
| 14 | +The compiler is configured in `pom.xml` in three locations: |
| 15 | +* `<dependencies>...</dependencies> - each dependency leads to a compile-time library path entry, and a run-time JVM classpath entry. |
| 16 | +* the general `<configuration>...</configuration> tags for Rascal mojos: |
| 17 | +```xml |
| 18 | +<plugins> |
| 19 | + <plugin> |
| 20 | + <groupId>org.rascalmpl</groupId> |
| 21 | + <artifactId>rascal-maven-plugin</artifactId> |
| 22 | + <version>${rascal-maven-plugin.version}</version> |
| 23 | + <configuration> |
| 24 | + ...configuration tags go here... |
| 25 | + </configuration> |
| 26 | + </plugin> |
| 27 | +</plugins> |
| 28 | +``` |
| 29 | +* and finally the specific `<configuration>...</configuration>` tag for the `compile` goal. |
| 30 | +```xml |
| 31 | + <plugin> |
| 32 | + <groupId>org.rascalmpl</groupId> |
| 33 | + <artifactId>rascal-maven-plugin</artifactId> |
| 34 | + <version>${rascal-maven-plugin.version}</version> |
| 35 | + <executions> |
| 36 | + <execution> |
| 37 | + <!-- "default-compile" works best, "default-cli" only if used only once --> |
| 38 | + <id>default-compile</id> |
| 39 | + <phase>compile</phase> |
| 40 | + <goals> |
| 41 | + <!-- it is possible to bind to other goals, but not recommended> --> |
| 42 | + <goal>compile</goal> |
| 43 | + </goals> |
| 44 | + <configuration> |
| 45 | + .... configuration tags go here .... |
| 46 | + </configuration> |
| 47 | + </execution> |
| 48 | + </executions> |
| 49 | +</plugin> |
| 50 | +``` |
| 51 | +* The latter overwrites the first, tag-by-tag |
| 52 | + |
| 53 | +Each configuration has the exact same parameters as the keyword fields of a ((util::Reflective::PathConfig)) constructor, and some additional ones: |
| 54 | +* `<srcs><src>${project.basedir}/src/main/rascal</src></srcs>` |
| 55 | +* `<libs>...</libs>` - however, if we leave these alone they are filled automatically via `<dependencies>` |
| 56 | +* `<bin>${project.basedir}/target/classes` however, the default is always good. |
| 57 | +* `<generatedSources>${project.basedir}/src/generated-sources/java</generatedSources>` - will be used to store intermediate generated Java files. The default is fine too. |
| 58 | +* `<ignores><ignore>${project.basedir}/src/main/rascal/Experiments</ignore></ignores>` - allows us to select files and folders reachable from the `srcs` and skip their compilation unless they are required by other non-ignored modules. |
| 59 | +* A number of boolean flags can be used for debugging purposes: `<logPathConfig>`, `<logImports>`, `<logWrittenFiles>`, `<warnUnused>`, `<warnUnusedFormals>`, `<warnUnusedVariables>`, `<warnUnusedPatternFormals>`, `<errorsAsWarnings>` and `<warningsAsErrors>`. The latter two control if a `mvn` run will fail (exit code 1) or succeed (exit code 0) in the presence of warnings or errors. |
| 60 | +* Finally we can instruct the mojo to compile the projects in parallel chunks: |
| 61 | + * the `<parallel>` boolean flag switches the behavior on. |
| 62 | + * `<parallelMax>5</parallelMax>` restricts the number of parallel processes to 5. However the mojo will estimate a proper maximum based on available processors and memory automatically. |
| 63 | + * `<parallelPrechecks>` lists a number of files that will be compiled and made reusable before the other threads start. Typically the utility modules with a high "fan-in" are listed here, to avoid duplicate (re)work by the other processes. |
| 64 | + |
| 65 | +#### Examples |
| 66 | + |
| 67 | +Maven is typically executed on the Un*x or Windows commandline like so: |
| 68 | +```bash |
| 69 | +# typically runs the compiler and the tests before packaging everything |
| 70 | +# in a jar file, and copying it to your local Maven repository: |
| 71 | +mvn install |
| 72 | + |
| 73 | +# like `install` but without copying to the Maven repository; |
| 74 | +mvn package |
| 75 | + |
| 76 | +# If configured as above in an `<execution>` This will run only the Rascal compiler |
| 77 | +mvn rascal:compile |
| 78 | + |
| 79 | +# runs everything _except the Rascal compiler_ |
| 80 | +mvn install -Drascal.compile.skip |
| 81 | +``` |
| 82 | + |
| 83 | +#### Benefits |
| 84 | + |
| 85 | +* The Maven configuration, including the dependencies listed in `pom.xml` enable reuse of other Rascal programs as libraries or development tools. |
| 86 | +* 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` |
| 87 | +* The rascal:compile mojo works find with multi-module Maven projects and parent projects. |
| 88 | + |
| 89 | +#### Pitfalls |
| 90 | + |
| 91 | +* 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._ |
| 92 | +* The rascal:compile mojo is fully configured from the pom.xml. Other sources of configuration |
| 93 | +may still uses the `Sources` fields in `RASCAL.MF`. This discrepancy will be resolved in the coming months. |
| 94 | +* ((getProjectPathConfig)) may produce different configurations for source folders for the same reason. |
0 commit comments