Plugin Documentation

This report describes goals, parameters details, requirements and sample usage of this plugin.

Goals

Goals available for this plugin:

Goal Description
cds:add Adds support of a feature to the CAP Java project. If the feature already exists, nothing is done.
Call mvn cds:add -Dfeature=MTX or mvn com.sap.cds:cds-maven-plugin:add -Dfeature=MTX to add Multitenancy support.

Note: This goal can only be executed from the command line.

cds:auto-build Performs an initial CDS build (same as mvn cds:build) and then watches for changes in the CDS model. If changes are detected, the CDS model is re-built automatically. In contrast to mvn cds:watch this goal does not start the CAP Java application.
Note: This goal can only be executed from the command line.

cds:build Perform a CDS build with Java class generation executing the following goals of the cds-maven-plugin in this order:
  1. cds:install-node
  2. cds:install-cdsdk
  3. cds:resolve
  4. cds:cds
  5. cds:generate
The list of goals and their order is fixed. Any Java property provided on the command line with the -D option is forwarded to the invoked goals.
Call mvn cds:build or mvn com.sap.cds:cds-maven-plugin:build to perform the CDS build. This goal is very useful for local development to test changes to the CDS model.

Note: This goal can only be executed from the command line.

cds:cds Execute CDS commands on the CAP Java project.
Call mvn cds:cds or mvn com.sap.cds:cds-maven-plugin:cds on the command line to execute all configured CDS commands of the project in current directory.

Several CDS commands can be configured in one execution block and they’re executed in the specified order. If a command execution fails, the overall goal execution is stopped and the Maven build fails.

Note: This goal requires the installation of the @sap/cds-dk with a minimum version 4.0.0, either locally or globally. The goal cds:install-cdsdk can be used for this task.

cds:clean Delete generated files and directories of the previous build from the CAP Java project.
Call mvn cds:clean or mvn com.sap.cds:cds-maven-plugin:clean to execute cleaning from the command line.

This goal deletes the following files and directories from the resource directory of the CAP Java project:
  • file: src/main/resources/**/csn.json
  • file: src/main/resources/**/schema.sql
  • directory: src/main/resources/**/edmx/
  • directory: ${codeOutputDirectory}

cds:generate Generates Java POJOs for type-safe access to the CDS model.

This goal scans the resource directory for a csn.json file and uses it for Java source code generation. It also adds the code output directory to the project's source code directories configuration. This allows you to use the generated Java classes in your custom code without any additional configuration in the project.

Note: If you call this goal from the command line (mvn cds:generate) and you want to leverage the configuration (e.g. basePackage) from the pom.xml, you have to specify the execution id (mvn cds:generate@<execution.id>) of this goal from the pom.xml: 
...
<execution>
  <id>cds.generate</id>
  <goals>
    <goal>generate</goal>
  </goals>
  <configuration>
    <basePackage>cds.gen</basePackage>
  </configuration>
</execution>
...
For this example, the required command line is mvn cds:generate@cds.generate.

If you call this goal without the execution id, you have to provide the configuration with properties on the command line (mvn cds:generate -Dcds.generate.basePackage=cds.gen).

cds:help Display help information on cds-maven-plugin.
Call mvn cds:help -Ddetail=true -Dgoal=<goal-name> to display parameter details.
cds:install-cdsdk
Deprecated. As of version 3.6.0, replaced by goal cds:npm with arguments ci and a devDependency to @sap/cds-dk in package.json. This goal will be removed in next major version.

Install the @sap/cds-dk into a CAP Java project.
By default, this goal looks for an already installed @sap/cds-dk and skips installation if it was found. It doesn't validate the found version against the requested version and the existing @sap/cds-dk could be outdated. Add property -Dcds.install-cdsdk.force=true to the Maven command line to force the installation of the @sap/cds-dk in the configured version.

Note: This goal ignores any dependency (including version) to @sap/cds-dk, @sap/cds or @sap/cds-compiler in the package.json of the CAP Java project.

Alternative way to install the @sap/cds-dk:
If you need to install additional Node.js modules in your CAP Java project, we recommend to use a different approach for the installation. In that case, maintain all dependencies, including the @sap/cds-dk, as a devDependency in the package.json: 
"devDependencies": {
   "@sap/cds-dk": "version"
}

Also remove the execution of goal cds:install-cdsdk from your pom.xml and replace it with goal cds:npm: 
<execution>
  <id>cds.install-dependencies</id>
  <goals>
    <goal>npm</goal>
  </goals>
  <configuration>
    <arguments>install</arguments>
  </configuration>
</execution>
This execution configuration runs the npm install command during each Maven build for your project and installs @sap/cds-dk and other dependencies. The npm cliwill install the dependencies, if they are not installed or not available in the requested versions.
The cds.install-cdsdk.global property needs to be removed from the pom.xml as the version is already maintained in package.json.

cds:install-node Download a Node.js distribution and install it on the local file system.
If the requested version is already installed, the download and installation is skipped.

This goal also considers proxy configurations in the ~/.m2/settings.xml. If there's an active proxy for the host in the downloadUrl configured, it is used.

The goal also supports basic authentication at the downloadUrl. The optional parameter serverId can be used to reference a server configuration from settings.xml, which provides username and password. See also Settings Reference for further details about server configuration in settings.xml.

Once executed, this goal exposes the following locations as project properties:
  • ${cds.node.executable}: Location of the node executable
  • ${cds.npm.executable}: Location of the npm executable
  • ${cds.npx.executable}: Location of the npx executable
  • ${cds.node.directory}: Directory containing the Node.js executables (node/npm/npx), can be used to enhance the $PATH environment variable
If the goal is skipped, the properties are set to the globally available executables: node, npm and npx.

cds:npm Execute an npm command on the CAP Java project. For example, it can be used to perform an npm install to install npm dependencies which are maintained in package.json.
Call mvn cds:npm -Darguments="..." or mvn com.sap.cds:cds-maven-plugin:npm -Darguments="..." to execute npm with given arguments.

cds:npx Execute an npx command on the CAP Java project.
cds:resolve Extracts models from dependency JARs and places them in target/cds/ for reuse by the CDS Compiler.
Models in JARs are expected to be placed in the cds resources folder. All contents in this folder are copied to target/cds/. It is recommended to specify a unique folder structure for your models, for example by reusing group ID and artifact ID of the JAR.
Here is an example JAR layout: 
com/example/.../Some.class
cds/
  com.example.cds/
    my-reuse-models/
      index.cds
      Foo.cds
      data/
        com.example.cds-Foo.csv
      i18n/
        i18n.properties
You can then refer to these reuse models in your CDS files: 
using { com.example.cds.Foo as Foo } from 'com.example.cds/my-reuse-models';
If your dependency is listed in the srv/pom.xml the reuse models are only available in CDS files placed in the srv folder. This ensures that multiple independent application modules can define their reuse artifacts independently. If you place a dependency in the root pom.xml the reuse models are available in all modules, including the db folder.
cds:version Prints detailed version information about the CAP Java project on the console.
Call cds:version or mvn com.sap.cds:cds-maven-plugin:version to get detailed version information.

This goal shows the following version information about the CAP Java project and build environment:
  • version of CAP Java SDK including CDS4J
  • console output of command line cds version
  • version and location of Apache Maven
  • version and location of Java runtime
  • OS information

cds:watch Starts a CAP Java application and watches for changes in the CDS model. If changes are detected, a cds:build is performed and the application is automatically restarted. Call mvn cds:watch or mvn com.sap.cds:cds-maven-plugin:watch to start the CAP Java application.

With Spring Boot Developer Tools
In order to get even faster development cycles locally, add an optional dependency to the Spring Boot Developer Tools in the pom.xml: 
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-devtools</artifactId>
  <optional>true</optional>
</dependency>
In this case the watch goal leaves the restart of the application to the Developer Tools, which is faster. The CAP Java application is started with a trigger file configured, used to signal the restart: --spring.devtools.restart.trigger-file=.reloadtrigger. The watch goal touches this trigger file after the cds:build is finished to signal the Spring Boot Developer Tools a safe application restart.
The trigger file is also touched, if any other file in the project has changed and no cds:build is performed. This behaviour ensures that the application is restarted, if a Java source file was changed in an IDE and a restart makes sense to test the changes.

Without Spring Boot Developer Tools
Without a dependency to the Spring Boot Developer Tools, this goal recognises all changes of included files and fully rebuilds and restarts the application.

Start test application
By default, this goal uses spring-boot:run to start the application, but it also supports running an optional test-application. This behaviour can be enabled by setting the property -DtestRun or -DtestRun=true at the Maven command line.

Note: This goal can only be executed from the command line.

System Requirements

The following specifies the minimum requirements to run this Maven plugin:

Maven 3.6.3
JDK 17

System Requirements History

The following specifies the minimum requirements to run this Maven plugin for historical versions:

Plugin Version Maven JDK
from 3.0.0 to 3.6.0 3.6.3 -
from 2.0.0 to 2.10.5 3.5.0 -
from 1.9.0 to 1.34.8 3.3.1 -
from 1.5.0 to 1.8.4 3.5.0 -

Usage

You should specify the version in your project's plugin configuration:

<project>
  ...
  <build>
    <!-- To define the plugin version in your parent POM -->
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>com.sap.cds</groupId>
          <artifactId>cds-maven-plugin</artifactId>
          <version>3.6.0</version>
        </plugin>
        ...
      </plugins>
    </pluginManagement>
    <!-- To use the plugin goals in your POM or parent POM -->
    <plugins>
      <plugin>
        <groupId>com.sap.cds</groupId>
        <artifactId>cds-maven-plugin</artifactId>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

For more information, see "Guide to Configuring Plug-ins"