From 38adf675dc7c7f4ee0fd0702707eb45a6092d01e Mon Sep 17 00:00:00 2001 From: Paul Gooderham Date: Thu, 3 Jul 2025 15:35:46 -0400 Subject: [PATCH 1/3] Update generate-features.md for generateToSrc option Signed-off-by: Paul Gooderham --- docs/generate-features.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/generate-features.md b/docs/generate-features.md index 1c31c1ed7..c318ff55b 100644 --- a/docs/generate-features.md +++ b/docs/generate-features.md @@ -1,19 +1,27 @@ #### generate-features --- -**This goal modifies the source configuration directory of your application.** This goal 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 goal 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](dev.md) during development. When you start `liberty:dev` 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 server 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 `-DgenerateFeatures=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 `-DgenerateFeatures=false`. The generated features file will be saved in the Liberty configuration directory. If you wish to save the file in the source configuration directory, you can start dev mode with the parameter `-DgenerateToSrc=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. + +###### Parameter + +| Parameter | Description | Required | +| -------- | ----------- | ------- | +| generateToSrc | place the new file `generated-features.xml` in the `src/main/liberty` directory tree rather than in the server definition directory. | No | ##### Lifecycle -This goal is not part of the Maven 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 `compile` goal. The list of features that it generates will be used by the `liberty:create` and the `liberty:install-feature` goals, so run this goal first. +This goal is not part of the Maven 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 `compile` goal. Since it will use the server configuration, it must be run after the `liberty:create` goal. The list of features that it generates will be used by the `liberty:install-feature` goals, so run this goal before installing features. -If this goal 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 goal 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 `target/liberty/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](dev.md#devc-container-mode), ensure that the `generated-features.xml` configuration file is copied to your Docker image via your Dockerfile. ```dockerfile @@ -56,7 +64,7 @@ If there are conflicts with features specified in Liberty configuration files or ##### Example (outside of dev mode) Compile the application code and generate Liberty features. -* `mvn compile liberty:generate-features` +* `mvn compile liberty:create liberty:generate-features` ##### Limitations From ef72e4821f3ce546261a55184de5be75e00b60ea Mon Sep 17 00:00:00 2001 From: Paul Gooderham Date: Thu, 3 Jul 2025 17:56:40 -0400 Subject: [PATCH 2/3] Clarify uses of server configuration directory in generate-features.md Signed-off-by: Paul Gooderham --- docs/generate-features.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/generate-features.md b/docs/generate-features.md index c318ff55b..f52c98f6d 100644 --- a/docs/generate-features.md +++ b/docs/generate-features.md @@ -7,19 +7,19 @@ Scan the class files of an application and create a new `generated-features.xml` This feature is best accessed through [dev mode](dev.md) during development. When you start `liberty:dev` 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 server 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 enabled through dev mode by default. If you need to disable feature generation, you can start dev mode with the parameter `-DgenerateFeatures=false`. The generated features file will be saved in the Liberty configuration directory. If you wish to save the file in the source configuration directory, you can start dev mode with the parameter `-DgenerateToSrc=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. +Feature generation is enabled through dev mode by default. If you need to disable feature generation, you can start dev mode with the parameter `-DgenerateFeatures=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 `-DgenerateToSrc=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. -###### Parameter +###### Command Line Parameter | Parameter | Description | Required | | -------- | ----------- | ------- | -| generateToSrc | place the new file `generated-features.xml` in the `src/main/liberty` directory tree rather than in the server definition directory. | No | +| 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 goal is not part of the Maven 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 `compile` goal. Since it will use the server configuration, it must be run after the `liberty:create` goal. The list of features that it generates will be used by the `liberty:install-feature` goals, so run this goal before installing features. +This goal is not part of the Maven 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 `compile` goal. Since it will use the server configuration directory, it must be run after the `liberty:create` goal. The list of features that it generates will be used by the `liberty:install-feature` goals, so run this goal before installing features. If this goal 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 `target/liberty/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. From 46d38570831885cdc7e61504a378850ee68b18f9 Mon Sep 17 00:00:00 2001 From: Paul Gooderham Date: Fri, 4 Jul 2025 16:29:08 -0400 Subject: [PATCH 3/3] Update dev.md to describe generateToSrc Signed-off-by: Paul Gooderham --- docs/dev.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/dev.md b/docs/dev.md index 773d46c26..c79bbc17f 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -2,9 +2,13 @@ ---- -Start a Liberty instance in dev mode. This goal also invokes the `create`, `install-feature`, and `deploy` goals before starting the runtime. **Note:** This goal is designed to be executed directly from the Maven command line. +Start a Liberty instance in dev mode (development mode). This goal also invokes the `create`, `install-feature`, and `deploy` goals before starting the runtime. **Note:** This goal is designed to be executed directly from the Maven command line. - Starting in version 3.6.1, dev mode invokes the `generate-features` goal when the `generateFeatures` configuration parameter is set to `true`. **This goal modifies the source configuration directory of your application.** See [generate-features](generate-features.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.11.5, dev mode invokes the `generate-features` goal 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.6.1, dev mode invokes the `generate-features` goal when the `generateFeatures` configuration parameter is set to `true`. **In those versions this goal modifies the source configuration directory of your application.** Also, the default value for the `generateFeatures` parameter is `false`. See [generate-features](generate-features.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). Additionally, starting in version 3.5.2, [resource variable filtering](https://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html) and [WAR overlays](https://maven.apache.org/plugins/maven-war-plugin/overlays.html) are supported for loose WAR applications. This is done by automatically detecting appropriate Maven WAR plugin configuration and calling the WAR plugin's [`exploded`](https://maven.apache.org/plugins/maven-war-plugin/exploded-mojo.html) goal and the Maven Resource plugin's [`resource`](https://maven.apache.org/plugins/maven-resources-plugin/resources-mojo.html) goal when appropriate. Behavior for updating/deleting resources can be configured via the [`outdatedCheckPath`](https://maven.apache.org/plugins/maven-war-plugin/exploded-mojo.html#outdatedCheckPath) parameter introduced and then enhanced in maven-war-plugin versions 3.3.1, 3.3.2. @@ -15,8 +19,9 @@ To start the server in a container, see the [devc](#devc-container-mode) section While dev mode is running, perform the following in the command terminal to run the corresponding actions. -* g - toggle the automatic generation of features, type g and press Enter. A new server configuration file will be generated in the SOURCE configDropins/overrides configuration directory. -* o - optimize the list of generated features, type o and press Enter. A new server configuration file will be generated in the SOURCE configDropins/overrides configuration directory. +* g - toggle the automatic generation of features, type g and press Enter. A new server configuration file will be generated in the configDropins/overrides server configuration directory or optionally in the source configuration directory instead. +* s - toggle the output directory for generation of features, type s and press Enter. A new server configuration file will be generated in either the server configuration directory (`target/liberty/wlp/usr/servers/defaultServer`) or in the source configuration directory (`src/main/liberty/config`). +* o - optimize the list of generated features, type o and press Enter. 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. * Enter - run tests on demand, press Enter. * r - restart the server, type r and press Enter. * h - see the help menu for available actions, type h and press Enter. @@ -91,6 +96,11 @@ Start dev mode without allowing to attach a debugger. $ mvn liberty:dev -Ddebug=false ``` +Start dev mode and generate feature values in a file in the src directory. +``` +$ mvn liberty:dev -DgenerateToSrc=true +``` + ###### Additional Parameters The following are the parameters supported by this goal in addition to the [common server parameters](common-server-parameters.md#common-server-parameters) and the [common parameters](common-parameters.md#common-parameters). @@ -101,7 +111,8 @@ The following are the parameters supported by this goal in addition to the [comm | 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 | | debug | Whether to allow attaching a debugger to the running server. The default value is `true`. | No | | debugPort | The debug port that you can attach a debugger to. The default value is `7777`. | 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 set to `true`, run unit and integration tests automatically after every change. The default value is `false`. | No | | recompileDependencies | If set to `true`, when a Java file is changed, recompile all classes in that module and any modules that depend on it. The default value is `false` when running dev mode on a single module, and `true` when running dev mode on a multi module project. | No | | serverStartTimeout | Maximum time to wait (in seconds) to verify that the server has started. The value must be an integer greater than or equal to 0. The default value is `90` seconds. | No | @@ -130,7 +141,7 @@ Start a Liberty server in a local container using the Containerfile or Dockerfil When dev mode runs with container support, it builds a container image and runs the container. You can examine the commands that it uses to build and run the container by viewing the console output of dev mode. Additionally, it still provides the same features as the `dev` goal. It monitors files for changes and runs tests either automatically or on demand. This mode also allows you to attach a debugger to work on your application. You can review the logs generated by your server in the Liberty directory in your project e.g. target/liberty/wlp/usr/servers/defaultServer/logs. -N.B. starting in 3.6.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.11.5, dev mode invokes `generate-features` because the default value of the `generateFeatures` configuration parameter is `true`. In previous versions starting with 3.6.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 target/liberty/wlp/usr/servers/defaultServer/configDropins/overrides/generated-features.xml /config/configDropins/overrides/ ``` @@ -177,8 +188,9 @@ 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. -* g - toggle the automatic generation of features, type g and press Enter. A new server configuration file will be generated in the SOURCE configDropins/overrides configuration directory. -* o - optimize the list of generated features, type o and press Enter. A new server configuration file will be generated in the SOURCE configDropins/overrides configuration directory. +* g - toggle the automatic generation of features, type g and press Enter. A new server configuration file will be generated in the configDropins/overrides server configuration directory or optionally in the source configuration directory instead. +* s - toggle the output directory for generation of features, type s and press Enter. A new server configuration file will be generated in either the server configuration directory (`target/liberty/wlp/usr/servers/defaultServer`) or in the source configuration directory (`src/main/liberty/config`). +* o - optimize the list of generated features, type o and press Enter. 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. * t or Enter - If `changeOnDemandTestAction` is set to `true`, type t and press Enter to run tests on demand. Otherwise, press Enter. * r - rebuild the container image and restart the container, type r and press Enter. * h - see the help menu for available actions, type h and press Enter.