foam3

FOAM Build

Pom-O-Matic Solve your Build troubles with Pom-O-Matic!

The FOAM build is a node tool which executes Javascript methods (Tasks) against Project Object Model (POM)(or a more lighthearted acronym expansion: Pom-O-Matic) files.

The build manages options and tasks:

POMs are JSON files which identify source code, application configuration, and build instructions. They are hierarchical and can exist at any level of a code repository.

There are two types of POMs

  1. Tooling - poms which configure the Build environment itself.
    • options and tasks add support for build specific command line options and methods to process the source code.
    • For example, JavaTooling adds options to allow the configuration of the Java target version, and provide command line arguments to control creating a JAR file or start the JVM with JDPA enabled. And adds tasks for building and starting from JAR file locally or building a TAR file for remote deployment.
    • Multiple Tooling POMs can define the same task name; All will be executed in the order encountered during tooling setup.
    • The build defaults to Tooling task all when no tasks are specified on the command line. (see JavaTooling)
  2. Build - poms which declare build inputs.
    • Such as code and deployment configuration to include.
    • For example, specifying the models to generate Java from and specifying the configuration to include in a JAR file.

There are three distinct build phases:

  1. Tooling - the build loads Tooling POMs which add options for command line control, and build tasks specific to the type of code generation, compilation, and deployment to be supported.
  2. Environment and Registration - the build processes the Build POMs to:
    1. set environment variable values for options added during the Tooling phase
      • (i.e., Java target release = 21)
    2. register Build POM tasks to be run when same-named Tooling tasks are run
      • (i.e., buildJavaOpts JAVA_OPTS=-Dxyz before the JVM is started). 
         foam.POM({
...
envs: {
 appName: 'foam',
},
...
tasks: [
 function javacParameters() {
JAVA_RELEASE = 21;
 },
 function buildJavaOpts() {
JAVA_OPTS += `` -DGO_HOME=${APP_HOME}``;
 }
  3. Task - the build processes the command line arguments, for options added during the Tooling phase, and prepares a set of tasks which are then executed. The tasks themselves, act on the Build POMs.

Command Line Arguments

Three input styles are supported

The word style arguments can be listed individually or comma seperated.

Usage

Build examples for each Tooling feature is available with task usage

$ node foam3/tools/build.js --usage

Help on Help

Build help is generated by the help option and can be invoked in a number of ways:

Help output is broken in three sections: options, tasks, environment variables (envs). Help can display just one of the sections by passing an argument to help.

For example, the following will only output the environment variables.

$ node foam3/tools/build.js --help:envs

Help can also output the usage or information of a single option, task, or environment variable.

$ node foam3/tools/build.js --help:topic

For example, the following will only output usage of help itself

$ node foam3/tools/build.js --help:help

Help will output partial matches when an exact match for the help topic is not found.

Troubleshooting

Option –show-envs will cause the build to output the final value of all options at the point of exit on error, or just before start CORE.

POMs (Incomplete)

POMs are hierarchical and a POM is responsible for the files in it’s directory and child directories which themselves do not contain a POM.

POM structure

TODO

Build POM Fields

Creating a Build POM Tasks

TODO

Tooling POM Fields

Project specific Tooling

The build looks for tooling poms in:

For example, Custom tooling located in tools/CustomTooling.pom can be added into the build with:

-T+Custom

NOTE The tooling directive -T must proceed all other build arguments.

Creating a POM Environment Variable

TODO

Creating a POM Option

TODO

Creating a POM Tasks

TODO

Test Cases and Benchmarks

Option –flags:test will include all source and configuration flagged as test to allow using test and benchmark logic form a normally built application.

Options and Tasks of interest

Additional Tooling

Building Third-Party from Source

Third party repositories can be built from source with the addition of a small pom file.

Create a pom file at the root of your project with a name matching the the repository, ThirdParty-pom.js for example. In it, specify javaFiles, resources, licenses, and javaDependencies. Note the paths are relative to your root project.

Example:

```
foam.POM({
  name: 'ThirdParty',
  javaFiles: [
    { '../ThirdParty/src/main/java/*' }
  ],
  copy: [
    { source: '../ThirdParty/src/main/resources' }
  ],
  licenses: `
    // Add license header
  `,
  javaDependencies: [
    ...
  ]
})
```

Add this pom file to your root project pom projects section.

```
foam.POM({
  ...
  projects: [
    ...
    { name: 'ThirdParty-pom' }
  ],
  ...
})
```

Build as you would normally for your project.

Enabling Java Preview Features

Java Preview Features can be specified as such in a pom:

```
foam.POM({
  ...

  tasks: [
    function buildJavaOps() {
      JAVA_OPTS += ` --add-modules jdk.incubator.vector --enable-preview`;
    }
  ],

```
This site is open source. Improve this page.