Skip to content

Document generate-features and generateToSrc #971

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
turkeylurkey wants to merge 3 commits into
base: generate-features-update
Choose a base branch
from
Open

Document generate-features and generateToSrc #971

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
aa8f6d2
Update generateFeatures.md for generateToSrc option
turkeylurkey Jul 3, 2025
d35fb52
Clarify uses of server configuration directory in generateFeatures.md
turkeylurkey Jul 3, 2025
00e1378
Update libertyDev.md to describe generateToSrc
turkeylurkey Jul 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions docs/generateFeatures.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,27 @@
## generateFeatures task
---

**This task modifies the source configuration directory of your application.** This task has a runtime dependency on IBM WebSphere Application Server Migration Toolkit for Application Binaries, which is separately licensed under IBM License Agreement for Non-Warranted Programs. For more information, see the [license](https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/wasdev/license/wamt).
**Note:** This task has a runtime dependency on IBM WebSphere Application Server Migration Toolkit for Application Binaries, which is separately licensed under IBM License Agreement for Non-Warranted Programs. For more information, see the [license](https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/wasdev/license/wamt).

Scan the class files of an application and create a new `generated-features.xml` Liberty configuration file in the source configuration directory that contains the Liberty features the application requires.
Scan the class files of an application and create a new `generated-features.xml` Liberty configuration file in the server configuration directory that contains the Liberty features the application requires. You can alternatively save the file in the source configuration directory of your application using the `generateToSrc` parameter.

This feature is best accessed through [dev mode](libertyDev.md). When you start `libertyDev` your application will be compiled and the class files will be scanned to verify that all the required Liberty features are included in your server configuration. Then as you work, dev mode will continue to monitor the project to confirm the Liberty features configured are up to date. If you implement a new interface in Java, the scanner will determine if that API is connected to a Liberty feature, then update the configuration and install the feature. If you remove a feature from `server.xml`, dev mode will determine if that feature is actually necessary, and if so, add it to the generated configuration file as described below.

Feature generation is disabled through dev mode by default. If you need to enable feature generation, you can start dev mode with the parameter `--generateFeatures=true`. When running dev mode, you can toggle the generation of features off and on by typing 'g' and pressing Enter. Normally dev mode only scans a class file that has just been updated, but you can tell dev mode to rescan all class files by typing 'o' and pressing Enter. This will optimize the feature list in the generated configuration file.
Feature generation is enabled through dev mode by default. If you need to disable feature generation, you can start dev mode with the parameter `--generateFeatures=false`. The generated features file will be saved in the server configuration directory. If you wish to save the file in the source configuration directory, you can start dev mode with the parameter `--generateToSrc=true`. When running dev mode, you can toggle the generation of features off and on by typing 'g' and pressing Enter. You can toggle the location of the generated file by typing 's' and pressing Enter.

Normally dev mode only scans a class file that has just been updated, but you can tell dev mode to rescan all class files by typing 'o' and pressing Enter. This will optimize the feature list in the generated configuration file.

###### Command Line Parameter

| Parameter | Description | Required |
| -------- | ----------- | ------- |
| generateToSrc | If set to `true`, place the new file `generated-features.xml` in the `src/main/liberty` directory tree rather than in the server configuration directory. The default value is `false`.| No |

##### Lifecycle

This task is not part of the lifecycle, so to use it in your build you will need to understand its dependencies. Since it will scan the class files of your application, it must be run after the `compileJava` task. The list of features that it generates will be used by the `libertyCreate` and the `installFeature` tasks, so run this task first.
This task is not part of the lifecycle, so to use it in your build you will need to understand its dependencies. Since it will scan the class files of your application, it must be run after the `compileJava` task. This task uses the server configuration directory so it has a dependency on the `libertyCreate` task which will run if there is no Liberty server detected. Finally the `installFeature` task will run after this task.

If this task detects Liberty features used in your project but not present in your Liberty configuration, it will create a new file `configDropins/overrides/generated-features.xml` in the `src/main/liberty/config` directory of your project. The `generated-features.xml` file will contain a list of features required for your project. If the `generated-features.xml` file has been created in the past and no additional features have been detected, this file will be retained.
If this task detects Liberty features used in your project but not present in your Liberty configuration, it will create a new file `configDropins/overrides/generated-features.xml` in the `build/wlp/usr/servers/defaultServer` directory or optionally in the `src/main/liberty/config` directory of your project. The `generated-features.xml` file will contain a list of features required for your project. If the `generated-features.xml` file has been created in the past and no additional features have been detected, this file will be retained.

If you are using [devc](libertyDev.md#libertydevc-task-container-mode), ensure that the `generated-features.xml` configuration file is copied to your Docker image via your Dockerfile.
```dockerfile
Expand Down
41 changes: 26 additions & 15 deletions docs/libertyDev.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
## libertyDev Task

Start a Liberty instance in dev mode. This task also invokes the `libertyCreate`, `installFeature`, and `deploy` tasks before starting the runtime.
**Note:** This task is designed to be executed directly from the Gradle command line.
Start a Liberty instance in dev mode (development mode). This task also invokes the `libertyCreate`, `installFeature`, and `deploy` tasks before starting the runtime. **Note:** This task is designed to be executed directly from the Gradle command line.

Starting in version 3.4.1, dev mode invokes the `generateFeatures` task when the `generateFeatures` configuration parameter is set to `true`. **This task modifies the source configuration directory of your application.** See [generateFeatures](generateFeatures.md) for details. The default value for the `generateFeatures` parameter is `false`. When auto-generation of features is turned on, dev mode has a runtime dependency on IBM WebSphere Application Server Migration Toolkit for Application Binaries, which is separately licensed under IBM License Agreement for Non-Warranted Programs. For more information, see the [license](https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/wasdev/license/wamt).
Starting in version 3.9.4 dev mode invokes the `generateFeatures` task by default. The `generated-features.xml` file is placed in the server configuration directory by default. These defaults can be changed using command line parameters or the behaviors can be modified by [console actions](#Console-Actions).

In previous versions starting in version 3.4.1, dev mode invokes the `generateFeatures` task when the `generateFeatures` configuration parameter is set to `true`. **In those versions this task modifies the source configuration directory of your application.** Also, the default value for the `generateFeatures` parameter is `false`. See [generateFeatures](generateFeatures.md) for details.

When auto-generation of features is turned on, dev mode has a runtime dependency on IBM WebSphere Application Server Migration Toolkit for Application Binaries, which is separately licensed under IBM License Agreement for Non-Warranted Programs. For more information, see the [license](https://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/wasdev/license/wamt).

**Limitations:** This task is not supported with Spring Boot applications.

Expand All @@ -15,11 +18,12 @@ To start the server in a container, see the [libertyDevc](#libertydevc-task-cont

While dev mode is running, perform the following in the command terminal to run the corresponding actions.

* <kbd>g</kbd> - To toggle the automatic generation of features, type <kbd>g</kbd> and press <kbd>Enter</kbd>. A new server configuration file will be generated in the SOURCE configDropins/overrides configuration directory.
* <kbd>o</kbd> - To optimize the list of generated features, type <kbd>o</kbd> and press <kbd>Enter</kbd>. A new server configuration file will be generated in the SOURCE configDropins/overrides configuration directory.
* <kbd>g</kbd> - toggle the automatic generation of features, type <kbd>g</kbd> and press <kbd>Enter</kbd>. A new server configuration file will be generated in the configDropins/overrides server configuration directory or optionally in the source configuration directory instead.
* <kbd>s</kbd> - toggle the output directory for generation of features, type <kbd>s</kbd> and press <kbd>Enter</kbd>. A new server configuration file will be generated in either the server configuration directory (`build/wlp/usr/servers/defaultServer`) or in the source configuration directory (`src/main/liberty/config`).
* <kbd>o</kbd> - optimize the list of generated features, type <kbd>o</kbd> and press <kbd>Enter</kbd>. All the class files will be scanned and a new server configuration file will be generated in the configDropins/overrides server or source configuration directory.
* <kbd>t</kbd> or <kbd>Enter</kbd> - If `changeOnDemandTestAction` is enabled, type <kbd>t</kbd> and press <kbd>Enter</kbd> to run tests on demand. Otherwise, press <kbd>Enter</kbd>.
* <kbd>r</kbd> - To restart the server, type <kbd>r</kbd> and press <kbd>Enter</kbd>.
* <kbd>h</kbd> - To see the help menu for available actions, type <kbd>h</kbd> and press <kbd>Enter</kbd>.
* <kbd>r</kbd> - restart the server, type <kbd>r</kbd> and press <kbd>Enter</kbd>.
* <kbd>h</kbd> - see the help menu for available actions, type <kbd>h</kbd> and press <kbd>Enter</kbd>.
* <kbd>q</kbd> - stop the server and quit dev mode, press <kbd>Ctrl</kbd>-<kbd>C</kbd>, or type <kbd>q</kbd> and press <kbd>Enter</kbd>.

### Features
Expand All @@ -30,8 +34,8 @@ The following are dev mode supported code changes. Changes to your server such a

* Java source file changes and Java test file changes are detected, recompiled, and picked up by your running server.
* Added dependencies to your `build.gradle` are detected and added to your classpath. Dependencies that are Liberty features will be installed via the `installFeature` task. Any other changes to your `build.gradle` will require restarting dev mode to be detected.
* Resource file changes are detected and copied into your `target` directory.
* Configuration directory and configuration file changes are detected and copied into your `target` directory. Added features to your `server.xml` will be installed and picked up by your running server. Adding a configuration directory or configuration file that did not previously exist while dev mode is running will require restarting dev mode to be detected.
* Resource file changes are detected and copied into your `build` directory.
* Configuration directory and configuration file changes are detected and copied into your `build` directory. Added features to your `server.xml` will be installed and picked up by your running server. Adding a configuration directory or configuration file that did not previously exist while dev mode is running will require restarting dev mode to be detected.

### Multi-Project Builds

Expand Down Expand Up @@ -80,14 +84,20 @@ Start dev mode without allowing to attach a debugger.
$ gradle libertyDev --libertyDebug=false
```

Start dev mode and generate feature values in a file in the src directory.
```
$ gradle libertyDev --generateToSrc=true
```

### Command Line Parameters

The following are optional command line parameters supported by this task.

| Parameter | Description | Required |
| -------- | ----------- | ------- |
| compileWait | Time in seconds to wait before processing Java changes. If you encounter compile errors while refactoring, increase this value to allow all files to be saved before compilation occurs. The default value is `0.5` seconds. | No |
| generateFeatures | If set to `true`, when a Java file, server configuration file, or build file is changed, generate features required by the application in the source configuration directory. The default value is `false`. | No |
| generateFeatures | If set to `true`, when a Java file, server configuration file, or build file is changed, generate features required by the application in the server configuration directory. The default value is `true`. | No |
| generateToSrc | If set to `true`, when features are generated, store the `generated-features.xml` file in the source configuration directory (`src/main/liberty/config`). The default value is `false`. | No |
| hotTests | If this option is enabled, run tests automatically after every change. The default value is `false`. | No |
| libertyDebug | Whether to allow attaching a debugger to the running server. The default value is `true`. | No |
| libertyDebugPort | The debug port that you can attach a debugger to. The default value is `7777`. | No |
Expand Down Expand Up @@ -196,7 +206,7 @@ When dev mode runs with container support, it builds a container image and runs

This task requires applications to be installed as loose applications. Information on configuring loose applications can be found in the [deploy task parameter documentation](deploy.md#Parameters) and the [Liberty server configuration](libertyExtensions.md#liberty-server-configuration).

N.B. starting in 3.4.1, dev mode invokes `generate-features` if the `generateFeatures` configuration parameter is set to true. Ensure that the `generated-features.xml` configuration file is copied to your container image via your Containerfile/Dockerfile.
N.B. starting in 3.9.4, dev mode invokes `generateFeatures` because the default value of the `generateFeatures` configuration parameter is `true`. In previous versions starting in 3.4.1, the default value was `false`. Ensure that the `generated-features.xml` configuration file is copied to your container image via your Containerfile/Dockerfile.
```dockerfile
COPY --chown=1001:0 build/wlp/usr/servers/defaultServer/configDropins/overrides/generated-features.xml /config/configDropins/overrides/
```
Expand Down Expand Up @@ -241,11 +251,12 @@ Dev mode offers different levels of file tracking and deployment depending on th

While dev mode is running in container mode, perform the following in the command terminal to run the corresponding actions.

* <kbd>g</kbd> - To toggle the automatic generation of features, type <kbd>g</kbd> and press <kbd>Enter</kbd>. A new server configuration file will be generated in the SOURCE configDropins/overrides configuration directory.
* <kbd>o</kbd> - To optimize the list of generated features, type <kbd>o</kbd> and press <kbd>Enter</kbd>. A new server configuration file will be generated in the SOURCE configDropins/overrides configuration directory.
* <kbd>g</kbd> - toggle the automatic generation of features, type <kbd>g</kbd> and press <kbd>Enter</kbd>. A new server configuration file will be generated in the configDropins/overrides server configuration directory or optionally in the source configuration directory instead.
* <kbd>s</kbd> - toggle the output directory for generation of features, type <kbd>s</kbd> and press <kbd>Enter</kbd>. A new server configuration file will be generated in either the server configuration directory (`build/wlp/usr/servers/defaultServer`) or in the source configuration directory (`src/main/liberty/config`).
* <kbd>o</kbd> - optimize the list of generated features, type <kbd>o</kbd> and press <kbd>Enter</kbd>. All the class files will be scanned and a new server configuration file will be generated in the configDropins/overrides server or source configuration directory.
* <kbd>t</kbd> or <kbd>Enter</kbd> - If `changeOnDemandTestAction` is enabled, type <kbd>t</kbd> and press <kbd>Enter</kbd> to run tests on demand. Otherwise, press <kbd>Enter</kbd>.
* <kbd>r</kbd> - To rebuild the container image and restart the container, type <kbd>r</kbd> and press <kbd>Enter</kbd>.
* <kbd>h</kbd> - To see the help menu for available actions, type <kbd>h</kbd> and press <kbd>Enter</kbd>.
* <kbd>r</kbd> - rebuild the container image and restart the container, type <kbd>r</kbd> and press <kbd>Enter</kbd>.
* <kbd>h</kbd> - see the help menu for available actions, type <kbd>h</kbd> and press <kbd>Enter</kbd>.
* <kbd>q</kbd> - stop the server and quit dev mode, press <kbd>Ctrl</kbd>-<kbd>C</kbd>, or type <kbd>q</kbd> and press <kbd>Enter</kbd>.

### Linux Limitations
Expand Down