Wompiler CLI

A preprocessor that can be used in multi-layer projects to retrieve files from lower-layer repositories and generate mirror files.

Installation

See Slab | Entwicklungsumgebung einrichten (setting up your machine).

npm i -g @informaticon/web.compiler

Requirements

• Node.js (Active LTS or Maintenance).
• For running wompiler watch, watchman is required.

Compatibility

Wompiler 2.11.x and earlier versions require Node 14.

For Product Owners

If you are using lib.sbt.base.cli-hook-plugin, it is recommended that you set up a hook for runDetachedCommands to run wompiler watch. See lib.sbt.base.cli-hook-plugin | Using Wompiler with this plugin to learn why other wompiler commands should not be used in hooks.

In the README file, document which (wompiler) commands developers should run to update, run, or deploy the project. Use the Usage section as a guide.

When wompiler is used in GitHub Actions, install a fixed major version:

npm i -g @informaticon/web.compiler@3

Usage

[!IMPORTANT] Refer to your project's README file for information about how to use wompiler with it.

General tipps:

• Run wompiler update and wompiler precompile after you modify a version.json file.
  • Note that wompiler update may introduce changes to the build files (e.g., dependencies_l*.sbt). Reload any running SBT process in that case.
• Run wompiler clean to delete files generated by wompiler (See Note about wompiler clean)
• Run wompiler watch to automatically precompile files as whenever they are modified.
  • Note that this command might be run automatically when starting the project using sbt run—depending on whether the runDetachedCommands hook is configured accordingly.
• For a full list of commands please execute the wompiler --help command.

Note about wompiler clean

This will delete the following directories or files relative to your current working directory.

[!CAUTION] Wompiler will not check whether you are located in a valid project. It also will not validate the type of file it deletes (file / directory).

| Path in root project | Path in subproject | |:--------------------------|:-------------------------------------------------| | ./.update.* | <subproject.dir>/.update.* | | ./package.json | <subproject.dir>/package.json | | ./conf/application.conf | <subproject.dir>/conf/<subproject.name>.conf | | ./conf/routes | <subproject.dir>/conf/<subproject.name>.routes | | ./app/mirror | <subproject.dir>/app/mirror | | ./app/inclMirror | <subproject.dir>/app/inclMirror |

<subproject.dir> is the path to the subproject, relative to the working directory and <subproject.name> is the subproject name (see Subprojects)

Subprojects

Wompiler supports Multi-project builds. To be specific, it aims to support the way Informaticon uses subprojects. Please read the associated slab post: https://slab.informaticon.com/posts/scs-in-subprojekte-aufteilen-dmeeqdkq

Currently, there are some limitations with subprojects. Missing requirements and bugs should be reported as issues with the Subprojects Milestone.

(Sub)project Detection

[!IMPORTANT] The current Version of Wompiler does not use the *.sbt files for finding projects! The projects are detected by finding version.json files.

Root Project: If a version.json is present in the working directory or if no version.json is present at all in the subtree, then the current working directory is considered to be the root directory of the root project.

Subprojects: Every descendant directory of the working directory that contains a version.json file is the root directory of a subproject. The name of the project is the basename of that directory.

Resource Files

We have to use unique resource names for files in all conf directories of projects. Therefore, we use the name of the subproject in the names of the resource files, with exceptions for the root project.

Root Project:

• Routes: ./conf/layeredRoutes/<layer>.routes
  • Example: ./conf/layeredRoutes/l1.routes
  • Result: ./conf/routes (generated)
• Configuration: ./conf/application_<layer>.conf
  • Example: ./conf/application_l1.conf
  • Result: ./conf/application.conf (generated)

Subprojects:

<subproject.dir> is the path to the root directory of the subproject, relative to the working directory / root project directory.

• Routes: <subproject.dir>/conf/layeredRoutes/<layer>.routes
  • Example: ./modules/common/conf/layeredRoutes/l1.routes
  • Result: ./modules/common/conf/common.routes (generated)
• Configuration: <subproject.dir>/conf/<subproject.name>_<layer>.conf
  • Example: ./modules/common/conf/common_l1.conf
  • Result: ./modules/common/conf/common.conf (generated)

Limitations

See LIMITATIONS.md.

Contributing

[!NOTE] Build the project using a "Current" or "LTS" (Active) Node version. See Node Release Schedule.

If you want to contribute to the wompiler project, follow the steps below.

1. Clone the Repository
2. Run npm i to install dependencies
3. Implement your fixes or features on a separate branch
4. Test your code
5. "Install" your changes locally by running npm link in the root folder of the wompiler project. (Only once)
6. Build the project after each change: npm run build
7. Change directories to a web project you can test your changes with
8. Run wompiler using the commands you're familiar with, like wompiler precompile or any custom alias. Because you ran the link command, this now runs your development version of wompiler. *
9. When you're done testing, use npm i -g @informaticon/web.compiler to re-install the production version of wompiler.
10. Commit your changes
11. Open a Pull Request on GitHub

* If you want to attach a debugger, you need to run node --inspect-brk <PATH-TO-WOMPILER>/dist/cli.js <command>. On Windows, an example might look like this:
node --inspect-brk %userprofile%\AppData\Roaming\npm\node_modules\@informaticon\web.compiler\dist\cli.js precompile.

Release

Only create a new release if your changes have been reviewed and merged into master/next.

1. Update version and automatically create git tag
   npm version (major|minor|patch) on master
   or npm version (premajor|preminor|prepatch|prerelease) --preid=rc on next
2. Push the newly created tag
   git push origin --tags