Compile Mojo

rascal-0.42.1

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:

The Rascal compiler is made available to the project via adding a proper <plugin> tag for the rascal-maven-plugin.
Dependencies on other Rascal or JVM-based projects are declared in with <dependency> tags.
Running mvn compile or mvn package or mvn install will trigger the compiler, reporting errors, warnings and other information on the go.
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.
All binary target files end up in the ./target/classes folder
With mvn package and mvn install the Package Mojo finally stores all target code in a .jar file.
Repeated executions of mvn compile make sure to check and compile only the changed Rascal modules.
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 Path Config. 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:

<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.

 <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:

# 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.
Get Project Path Config may produce different configurations for source folders for the same reason.

Synopsis​

Decription​

Input/output behavior​

Examples​

Benefits​