Tooling - CLI

Command Line Interface for the Causewaystuff Tooling ecosystem.

Prerequisites

From the root of the git repo, build the tooling using Java 11:

mvn install -D module-tooling -Dskip.essential

This will generate the command line CLI as an executable jar in its target directory (tooling/cli/target).

Available Commands

Use the help command to see a list of available commands:

calling for help
java -jar tooling/cli/target/causeway-tooling-cli.jar --help

which (currently) generates the following:

Usage: cli [-hV] [-o=<outputPath>] [-p=<projectRootPath>] [COMMAND]
CLI for the Apache Causeway Tooling Ecosystem
  -h, --help      Show this help message and exit.
  -w, --overview=<overviewPath>
                  path to write the overview file (default: NONE = write to std.out)
  -x, --index=<indexPath>
                  path to write the refguide index files (default: NONE = write to std.out)
  -p, --project=<projectRootPath>
                  path to the (multi-module) project root (default: current dir)
  -V, --version   Print version information and exit.
Commands:
  projdoc   Writes all generated (AsciiDoc) to given output.
  overview  Writes a System Overview document (AsciiDoc) to given output.
  index     Writes a Global Index (AsciiDoc) to given output.

The "projdoc" command is the usual command to use, as it performs both the "overview" and "index" commands.

By default, the current directory is used as the target to perform commands in.

Configuration File

The causeway-tooling.yml configuration file (found in the root of the repo) provides default options for each command, as well as global defaults applicable to all commands:

causeway-tooling.yml
global: (1)
  option ...
  option ...
command:
  overview: (2)
    option ...
    option ...
    ...
  index:    (3)
    option ...
    option ...
    ...
1 configuration applicable to all commands
2 configuration for the "overview" command (also used by the "projdoc" command)
3 configuration for the "index" command (also used by the "projdoc" command)
This configuration file is mapped onto the CLIConfig bean. Inspect its source code for more detailed information.

Commands

All commands accept the following common parameters:

  • -p indicates the location of the multi-project root pom.xml

    in other words, the root of the git repo.

A number of global configuration options can be specified under the global entry in the causeway-tooling.yml file.

causeway-tooling.yml
global:
  licenseHeader: "Licensed to the Apache Software Foundation (ASF) ..."   (1)
1 license header to include with each generated adoc file

Project documentation (projdoc)

This command generates both a system overview and generates the global index, and as such is the command that you will probably want to use most of the time. See those two commands for further details.

Usage

The projdoc command is usually invoked as follows:

java -jar tooling/cli/target/causeway-tooling-cli.jar \
    -p . \
    -w core/adoc \
    -x antora/components/refguide-index \
    projdoc

where :

  • -p is a global options for all commands

  • -w is the option for the overview sub-command, specifying the output root path

  • -x is the option for the index sub-command

  • projdoc selects this sub-command (which simply runs both overview and index sub-commands)

Configuration

The projdoc command has no specific configuration. However, as it is effectively just the combination of the overview and index commands, note that those two commands do have their own configuration settings; see overview configuration and index configuration respectively.

System Overview (overview)

This command generates the System Overview (`.adoc) page.

This page summarises the contents of each section (defined by the commands.overview.sections configuration key), also with a C4 diagram showing how the modules relate.

Usage

The overview command is usually invoked as follows:

java -jar tooling/cli/target/causeway-tooling-cli.jar \
    -p . \
    -v core/adoc \
    overview

where :

  • -p is a global options for all commands

  • -w is the option for the overview sub-command, specifying the output root path

  • overview selects this sub-command

There are no command-specific options.

Configuration

The overview command supports a number of command-specific configuration options:

causeway-tooling.yml
commands:
  overview:
    rootFolder:                                                     (1)
    pagesPath: "modules/_overview/pages"                            (2)
    systemOverviewFilename: "about.adoc"                            (3)
    description: "These tables summarize all Maven artifacts ..."   (4)
    sections:                                                       (5)
      ...
      Persistence: org.apache.causeway.persistence
      JDO: "org.apache.causeway.persistence:causeway-persistence-jdo.*"
      JPA: "org.apache.causeway.persistence:causeway-persistence-jpa.*"
      ...
1 the output target root for generated overview adoc; corresponds to command line option -v (if empty the current dir is used)
2 sub-folder name for adoc pages
3 name of the System Overview (adoc) file
4 System Overview summary description text
5 Logical grouping of modules for the system overview, but also used to determine which modules to scan for index files.

If not specified the natural Maven project hierarchy is reflected as is. This is discussed in more detail below.

The sections configuration key is used to group module artifacts into named sections. It consists of key:value pairs:

  • the key is the section name (eg "App", or "JDO")

  • the value is a pattern that identifies Maven artifacts.

This pattern in turn can be either:

  • an exact Maven groupId, such as org.apache.causeway.persistence

    This matches all Maven modules with exactly that groupId.

  • a Maven groupId with wildcard, such as org.apache.causeway.core.*

    This matches all Maven modules whose groupId pattern matches the groupId.

  • a Maven group and artifact optionally with wildcard, such as org.apache.causeway.persistence:causeway-persistence-jdo.*

    This matches all Maven modules whose groupId pattern equals the specified groupId and whose artifactId pattern matches the specified artifactId.

If a Maven module matches more than one section, then the more specific section (with both group and artifact) is used.

These different types of sections are exploited by the overview command, described below.

Sections that match on a groupID are placed under a level 2 heading, while sections matching on group and artifact are placed under a level 3 heading. By sequencing the sections correctly, this therefore allows a hierarchy to be created.

For example, in the config example above the sections defined will render "Persistence" section at level 2 (because its pattern is only for a groupId), and then the "JDO" and "JPA" sections underneath at level 3 (because there patterns also include an artifactId).

Index (index)

This command generates the Document Global Index (.adoc) files.

Any class found with magic {@index} in its java-doc section at type level, will be included with the Document Global Index.

AsciiDoc files may refer to the Document Global Index via xref or include statements using paths such as refguide:applib:index/annotation/Xxx.adoc.

Usage

The index command is usually invoked as follows:

java -jar tooling/cli/target/causeway-tooling-cli.jar \
    -p . \
    -x antora/components/refguide-index \
    index

where :

  • -p is a global options for all commands

  • -x is the option for the index sub-command, specifying the output root path

  • index selects this sub-command

Configuration

The index command supports a number of command-specific configuration options:

causeway-tooling.yml
commands:
  index:
    rootFolder:                                                             (1)
    documentGlobalIndexPath: "pages/index"                                  (2)
    documentGlobalIndexXrefPageIdFormat: "system:generated:index/%s.adoc"   (3)
    namespacePartsSkipCount: 3                                              (4)
    fixOrphanedAdocIncludeStatements: true                                  (5)
1 the output target root for generated index adoc files; corresponds to command line option -x (if empty the current dir is used)
2 sub-folder name for the Document Global Index
3 format for include statements via which other adoc files may refer to the Document Global Index
4 how many namespace parts in a fqn one wants to skip, eg. in org.apache.causeway.applib.Xxx if we skip 3 namespace parts we’ll end up with applib.Xxx
5 whether to activate the OrphanedIncludeStatementFixer.

The CLI also has an experimental OrphanedIncludeStatementFixer that checks orphaned index references in all adoc files and tries to fix them.

Limitations

There are currently a couple of limitations:

  • the Document Global Index can only contain classes unique by their simple name, otherwise the OrphanedIncludeStatementFixer would not be able to reason about how to fix orphaned references.

  • the OrphanedIncludeStatementFixer also can fix up references to classes that have been moved, but it cannot fix up orphans where the class has been renamed.