diff --git a/courses/GettingStarted/MavenPlugin/MavenPlugin.md b/courses/GettingStarted/MavenPlugin/MavenPlugin.md index 993ebc075..6331ac3b8 100644 --- a/courses/GettingStarted/MavenPlugin/MavenPlugin.md +++ b/courses/GettingStarted/MavenPlugin/MavenPlugin.md @@ -16,12 +16,15 @@ The [rascal-maven-plugin](http://github.com/usethesource/rascal-maven-plugin) of * ((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)) +* ((TestMojo)) for running Rascal tests. -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. +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 by the respective stage, or separately: +* `mvn compile` or `mvn rascal:compile` runs the compiler and `-Drascal.compile.skip` guarantees it is skipped. +* `mvn compile` or `mvn rascal:tutor` runs the tutor compiler and `-Drascal.tutor.skip` guarantees it is skipped. +* `mvn package` or `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. +* `mvn test` or `mvn rascal:test` runs all test in all modules and reports the result in `target/rascal-test-results`, while `-Drascal.test.skip` makes sure this goal is skipped. +* `mvn rascal:console` starts up a Rascal terminal with the same configuration as `mvn rascal:test` would use. #### Examples @@ -46,3 +49,7 @@ newRascalPomFile(|tmp:///my-project|); * 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 +#### Pitfalls + +* Watch out that `` tags can be different for each `` goal. Specifically `` can be (should be) different between compile and tutor. +* Maven will always executer earlies stages first. So `mvn package` will execute `compile`, `test` and `package` (at least). Use `-Drascal..skip` to avoid double work. \ No newline at end of file diff --git a/courses/GettingStarted/MavenPlugin/PackageMojo/PackageMojo.md b/courses/GettingStarted/MavenPlugin/PackageMojo/PackageMojo.md index c9c3cdf68..087fcadb0 100644 --- a/courses/GettingStarted/MavenPlugin/PackageMojo/PackageMojo.md +++ b/courses/GettingStarted/MavenPlugin/PackageMojo/PackageMojo.md @@ -8,7 +8,7 @@ Prepare compiler output files for distribution in a jar file, and downstream usa #### Description -The `prepare` plugin takes care of: +The `package` 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. diff --git a/courses/GettingStarted/MavenPlugin/TestMojo/TestMojo.md b/courses/GettingStarted/MavenPlugin/TestMojo/TestMojo.md new file mode 100644 index 000000000..b30dcdfe9 --- /dev/null +++ b/courses/GettingStarted/MavenPlugin/TestMojo/TestMojo.md @@ -0,0 +1,93 @@ +--- +title: Test Mojo +keywords: + - unit test + - mvn test +--- + +#### Synopsis + +`mvn test` runs all rascal test functions in all Rascal modules that reachable from the configured source folders. + +#### Description + +If you add a test execution to the pom configuration: +* then `mvn test` will run all available tests. +* in interactive mode a progress bars are shown per module and for all modules. +* in `target/rascal-test-reports`, each JSON file reports on one module. + +For example: +``` + + org.rascalmpl + rascal-maven-plugin + 0.32.0 + + ${project.build.outputDirectory} + + ${project.basedir}/src + + + + + default-compile + compile + + compile + + + + default-test + test + + test + + + + +``` + +Additionally you can configure parallel test execution like so: +``` + + true + 10 + + ${project.basedir}/src/MyInitialTests.rsc + + +``` + +The `parallelPreChecks` are optional. They can be used to trigger basic tests first; if those fail it does not make much +sense to try the other tests. + +#### Benefits + +* runs the Rascal tests exactly in the same context as the REPL on the terminal, so if you need to debug all you have to do is start a repl using VScode or `mvn rascal:console` and import the failing module. +* outputs JSON test reports directly used by the github action `ctrf-io/github-test-reporter@v1` + +Example github action: + +``` + - name: Publish Test Reports + if: ${{ !cancelled() }} + uses: ctrf-io/github-test-reporter@v1 + with: + report-path: 'target/rascal-test-reports/*.json' + github-report: true + file-report: true + pull-request-report: true + summary-delta-report: true + insights-report: true + fail-rate-report: true + slowest-report: true + upload-artifact: true + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +### Pitfalls + +* Uses the interactive progress bar by default, which would spam a build log with a line for every update. + * Use `mvn -B` or `mvn -Drascal.monitor.batch` to turn off the progress bar in CI environments + * Also if there is an environment variable named `CI` the progress bar will be turned off (as is the case for GitHub actions) \ No newline at end of file diff --git a/courses/GettingStarted/MavenPlugin/TutorMojo/TutorMojo.md b/courses/GettingStarted/MavenPlugin/TutorMojo/TutorMojo.md index 69f71ea17..edf46f8f4 100644 --- a/courses/GettingStarted/MavenPlugin/TutorMojo/TutorMojo.md +++ b/courses/GettingStarted/MavenPlugin/TutorMojo/TutorMojo.md @@ -4,8 +4,80 @@ 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. +Compiles [tutor]((course: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))) +Just run `mvn compile` or `mvn rascal:tutor` to compile the documentation +in the current project. The resulting documentation in docusaurus Markdown format is packaged in the +jar file under `/docs/Packages/./` for later processing in a website or an IDE. This includes: +* one folder for every course sourced in ``, recursively every concept file leads to a new folder and a new index file. +* one folder for every module folder in ``, recursively every module becomes one markdown file and every folder becomes a nested folder. See ((DocumentingCode)) for more information. +* [screenshots](Tutor:Markup-Screenshots) made by the tutor pages are saved in the target folder + +When embedded executable code in .rsc modules or .md concept files fails unexpectedly, the `mvn rascal:tutor` build fails with an error message. The same holds for missing or ambiguous links. + +[Linking](Tutor:Markup-Links) concepts is possible between concepts and modules within the same project, _and_ between any project that links to a concept in a depending project (see `` in the pom.xml. + +The tutor may have its own configuration in an `` block. This is used to add course material next to the module API, or to remove the module API from the documentation entirely. For example: + +``` + + default-cli + compile + + tutor + + + ${project.build.outputDirectory} + |http://github.com/myOrg/myProject/blob/main| + |http://github.com/myOrg/myProject/issues| + + ${project.basedir}/src + ${project.basedir}/doc/Motivation + ${project.basedir}/doc/References + + + +``` + +See ((course:Tutor)) for more information on how annotated Rascal modules and +concept files in markdown format are used to compile documentation. + +This is the complete list of tutor parameters and their defaults: + +| parameter | example/default | note | +| --- | --- | --- | +| bin | `./target/classes/` | target folder where `docs` will reside | +| srcs | `./src/main/rascal` | list of local source folders for Rascal modules and concept files | +| ignores | `./src/main/rascal/prelude` | will not generate any documentation reachable from this folder | +| sources | `http://github.com/usethesource/${project.name}/blob/main` | website of the project's home. | +| issues | `http://github.com/usethesource/${project.name}/issues` | website of the project's issue tracker. | +| license | ./LICENSE.md | local file that contains the (open-source) license. | +| citation | ./CITATION.MD | local file that explains how to cite this project. | +| funding | ./FUNDING.MD | local file that documents the money sources. | +| authors | ./AUTHORS.MD | local file that explains authorship of the code in this project. | +| version | `${project.version}` | the current version of this project. | +| releaseNotes | ./RELEASE-NOTES.md | the release notes in inverse chronological order. | +| isPackageCourse | true | stores output in `/docs/Packages/.`, or in `/docs/` when `false`. | +| includeLibraries | false | when true copies the libraries we depend on from `Library.jar!/docs/*` to `/docs/*` +| errorsAsWarnings | false | when true will not fail the build even if errors are present | +| warningsAsErrors | false | when true will fail the build even if only warnings are reported | + +Note that issues, license, citation, funding, authors and releaseNotes files must exist or else the build will fail. + +### Benefits + +* Using the tutor it is easy to create beautiful documentation that integrates seemlessly into http://www.rascalmpl.org +* Writing ((CodeExamples)) is a way to write documented tests. At compile-time all examples are tested for unexpected failures. +* The tutor compiler is incremental. Repeated `mvn rascal:tutor` will only re-index and re-compile changed files. +* The tutor compiler generates errors with accurate file names and line numbers, for easy fixing. +* Every library package is always documented online with the relevant documentation on licenses, authors, funding, citation, API and +specific user documentation. + +### Pitfalls + +* By default the tutor generates markdown in `/Packages/.` and all links are relative to these subfolder. +* The incremental compiler never removes information from the index. So after `mvn clean` new broken links can be found. +* There is no IDE integration for tutor compilation yet. +* Pitfalls: the first time it can take some effort to collect all the relevant information on license, authors, funding, citation, etc. \ No newline at end of file