diff --git a/docs/cli-guide-mtr/master.adoc b/docs/cli-guide-mtr/master.adoc index 6cf8f8f759..6e2eb8da7a 100644 --- a/docs/cli-guide-mtr/master.adoc +++ b/docs/cli-guide-mtr/master.adoc @@ -34,7 +34,7 @@ include::topics/installing-web-console-or-cli-tool.adoc[leveloffset=+2] include::topics/cli-run.adoc[leveloffset=+2] // Use OpenRewrite recipes -include::topics/using-openrewrite-recipes.adoc[leveloffset=+3] +include::topics/mtr-using-openrewrite-recipes.adoc[leveloffset=+3] // Available OpenRewrite recipes include::topics/available-openrewrite-recipes.adoc[leveloffset=+4] diff --git a/docs/cli-guide/master.adoc b/docs/cli-guide/master.adoc index 14c138294f..4a35da3916 100644 --- a/docs/cli-guide/master.adoc +++ b/docs/cli-guide/master.adoc @@ -35,7 +35,7 @@ include::topics/about-cli.adoc[leveloffset=+2] include::topics/installing-cli-tool.adoc[leveloffset=+2] // Run the CLI -include::topics/cli-run.adoc[leveloffset=+2] +include::topics/mta-cli-run.adoc[leveloffset=+2] // Analyze application source code include::topics/mta-cli-analyze.adoc[leveloffset=+3] @@ -44,7 +44,7 @@ include::topics/mta-cli-analyze.adoc[leveloffset=+3] include::topics/mta-cli-transform.adoc[leveloffset=+3] // Use OpenRewrite recipes -include::topics/using-openrewrite-recipes.adoc[leveloffset=+3] +// include::topics/mta-using-openrewrite-recipes.adoc[leveloffset=+3] // Available OpenRewrite recipes include::topics/available-openrewrite-recipes.adoc[leveloffset=+4] diff --git a/docs/topics/cli-run.adoc b/docs/topics/cli-run.adoc index d8e7bd37e8..92f33f12bd 100644 --- a/docs/topics/cli-run.adoc +++ b/docs/topics/cli-run.adoc @@ -11,11 +11,11 @@ You can run {ProductShortName} against your application. .Procedure . Open a terminal and navigate to the `<{ProductShortName}_HOME>/bin/` directory. -. Execute the `{mta-cli}` script, or `{mta-cli}.exe` for Windows, and specify the appropriate arguments: +. Execute the `windup-cli` script, or `windup-cli.bat` for Windows, and specify the appropriate arguments: + [source,terminal,subs="attributes+"] ---- -$ ./{mta-cli} --input /path/to/jee-example-app-1.0.0.ear \ +$ ./windup-cli --input /path/to/jee-example-app-1.0.0.ear \ --output /path/to/output --source weblogic --target eap:6 \ --packages com.acme org.apache ---- @@ -38,7 +38,9 @@ The following command analyzes the `com.acme` and `org.apache` packages of the l [source,terminal,subs="attributes+"] ---- -$ <{ProductShortName}_HOME>/{mta-cli} \ + +$ <{ProductShortName}_HOME>/bin/windup-cli \ + --input /path/to/jee-example-app-1.0.0.ear \ --output /path/to/report-output/ --source eap:5 --target eap:7 \ --packages com.acme org.apache @@ -52,7 +54,9 @@ The following command analyzes the `org.jboss.seam` packages of the link:https:/ [source,terminal,subs="attributes+"] ---- -$ <{ProductShortName}_HOME>/{mta-cli} --sourceMode --input /path/to/seam-booking-5.2/ \ + +$ <{ProductShortName}_HOME>/bin/windup-cli --sourceMode --input /path/to/seam-booking-5.2/ \ + --output /path/to/report-output/ --target eap:6 --packages org.jboss.seam ---- [] @@ -63,13 +67,26 @@ The following command analyzes the `com.acme` and `org.apache` packages of the l [source,terminal,subs="attributes+"] ---- -$ <{ProductShortName}_HOME>/{mta-cli} --input /path/to/jee-example-app-1.0.0.ear \ + +$ <{ProductShortName}_HOME>/windup-cli --input /path/to/jee-example-app-1.0.0.ear \ + --output /path/to/report-output/ \ --target eap:7 --target cloud-readiness --packages com.acme org.apache ---- [] [discrete] +=== Overriding {ProductShortName} properties + +To override the default _Fernflower_ decompiler, pass the `-Dwindup.decompiler` argument on the command line. For example, to use the _Procyon_ decompiler, use the following syntax: + +[source,terminal,subs="attributes+"] +---- +$ <{ProductShortName}_HOME>/bin/windup-cli -Dwindup.decompiler=procyon \ + --input --output \ + --target --packages +---- + [id="cli-bash-completion_{context}"] == {ProductShortName} {CLINameTitle} Bash completion @@ -77,7 +94,9 @@ The {ProductShortName} {CLIName} provides an option to enable Bash completion fo [source,terminal,subs="attributes+"] ---- -$ <{ProductShortName}_HOME>/{mta-cli} [TAB] + +$ <{ProductShortName}_HOME>/bin/windup-cli [TAB] + ---- [discrete] @@ -88,7 +107,7 @@ To enable Bash completion for the current shell, execute the following command: [source,terminal,subs="attributes+"] ---- -$ source <{ProductShortName}_HOME>/bash-completion/{mta-cli} +$ source <{ProductShortName}_HOME>/bash-completion/windup-cli ---- [discrete] @@ -101,22 +120,24 @@ The following commands allow Bash completion to persist across restarts: + [source,terminal,subs="attributes+"] ---- -source <{ProductShortName}_HOME>/bash-completion/{mta-cli} +source <{ProductShortName}_HOME>/bash-completion/windup-cli ---- * To enable Bash completion for all users across system restarts, copy the {ProductName} {CLIName} Bash completion file to the `/etc/bash_completion.d/` directory as the root user. + [source,terminal,subs="attributes+"] ---- -# cp <{ProductShortName}_HOME>/bash-completion/{mta-cli} /etc/bash_completion.d/ +# cp <{ProductShortName}_HOME>/bash-completion/windup-cli /etc/bash_completion.d/ ---- [id="accessing-help_{context}"] == Accessing {ProductShortName} help -To see the complete list of available arguments for the `{mta-cli}` command, open a terminal, navigate to the `<{ProductShortName}_HOME>` directory, and execute the following command: +To see the complete list of available arguments for the `windup-cli` command, open a terminal, navigate to the `<{ProductShortName}_HOME>` directory, and execute the following command: [source,terminal,subs="attributes+"] ---- -$ <{ProductShortName}_HOME>/{mta-cli} --help + +$ <{ProductShortName}_HOME>/bin/windup-cli --help + ---- diff --git a/docs/topics/mta-cli-run.adoc b/docs/topics/mta-cli-run.adoc new file mode 100644 index 0000000000..e72214444d --- /dev/null +++ b/docs/topics/mta-cli-run.adoc @@ -0,0 +1,70 @@ +// Module included in the following assemblies: +// +// * docs/cli-guide/master.adoc + +:_content-type: PROCEDURE +[id="cli-run_{context}"] += Running the {CLINameTitle} + +You can run {ProductShortName} against your application. + +.Procedure + +. Open a terminal and navigate to the `<{ProductShortName}_HOME>/` directory. + +. Execute the `{mta-cli}` script, or `{mta-cli}.exe` for Windows, and specify the appropriate arguments: + ++ +[source,terminal,subs="attributes+"] +---- +$ ./{mta-cli} analyze --input /path/to/jee-example-app-1.0.0.ear \ + --output /path/to/output --source weblogic --target eap6 \ +---- ++ +* `--input`: The application to be evaluated. +* `--output`: The output directory for the generated reports. +* `--source`: The source technology for the application migration. + +. Access the report. + +[id="command-examples_{context}"] +== {ProductShortName} command examples + +[discrete] +=== Running {ProductShortName} on an application archive + +The following command analyzes the link:https://github.com/windup/windup/blob/master/test-files/jee-example-app-1.0.0.ear[jee-example-app-1.0.0.ear] example EAR archive for migrating from JBoss EAP 5 to JBoss EAP 7: + +[source,terminal,subs="attributes+"] +---- +$ <{ProductShortName}_HOME>/{mta-cli} analyze \ + --input /path/to/jee-example-app-1.0.0.ear \ + --output /path/to/report-output/ --source eap5 --target eap7 \ +---- +[] + +[discrete] +=== Running {ProductShortName} on source code + +The following command analyzes the link:https://github.com/windup/windup/tree/master/test-files/seam-booking-5.2[seam-booking-5.2] example source code for migrating to JBoss EAP 6. + +[source,terminal,subs="attributes+"] +---- + +$ <{ProductShortName}_HOME>/{mta-cli} analyze --mode source-only --input /path/to/seam-booking-5.2/ \ + --output /path/to/report-output/ --target eap6 --packages org.jboss.seam +---- +[] +[discrete] +=== Running cloud-readiness rules + +The following command analyzes the link:https://github.com/windup/windup/blob/master/test-files/jee-example-app-1.0.0.ear[jee-example-app-1.0.0.ear] example EAR archive for migrating to JBoss EAP 7. It also evaluates for cloud readiness: + +[source,terminal,subs="attributes+"] +---- +$ <{ProductShortName}_HOME>/{mta-cli} analyze --input /path/to/jee-example-app-1.0.0.ear \ + --output /path/to/report-output/ \ + --target eap7 +---- +[] + diff --git a/docs/topics/using-openrewrite-recipes.adoc b/docs/topics/mta-using-openrewrite-recipes.adoc similarity index 100% rename from docs/topics/using-openrewrite-recipes.adoc rename to docs/topics/mta-using-openrewrite-recipes.adoc diff --git a/docs/topics/mtr-using-openrewrite-recipes.adoc b/docs/topics/mtr-using-openrewrite-recipes.adoc new file mode 100644 index 0000000000..edede93f41 --- /dev/null +++ b/docs/topics/mtr-using-openrewrite-recipes.adoc @@ -0,0 +1,59 @@ +// Module included in the following module: +// +// * docs/cli-guide-mtr/master.adoc + +[id=using-openrewrite-recipes_{context}] += Using OpenRewrite recipes + +[IMPORTANT] +==== +OpenRewrite recipe support is provided as Technology Preview only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. + +See link:{KBArticleTechnologyPreview}[Technology Preview features support scope] on the Red Hat Customer Portal for information about the support scope for Technology Preview features. +==== + +You can refactor the source code of Java applications by using link:https://docs.openrewrite.org/[OpenRewrite] recipes with the {ProductShortName} CLI. + +For example, the OpenRewrite recipe `org.jboss.windup.JavaxToJakarta` renames imported `javax` packages to their `jakarta` equivalents. + +.Procedure + +. Run `windup-cli`, specifying the recipe name, the path to the configuration file, and the application: ++ +[source,terminal,subs="attributes+"] +---- +$ ./windup-cli --openrewrite --input \ + "-Drewrite.configLocation=" \ + "-DactiveRecipes=" --goal dryRun +---- + +* `"-DactiveRecipes="`: Specify the OpenRewrite recipe, for example, `org.jboss.windup.JavaxToJakarta`. + +* `--input`: Specify the application to be refactored. The application must be the top of the source code project containing a Maven Project Object Model (POM) XML file, `pom.xml`. + +* `-Drewrite.configLocation=` : The location of the `rewrite.yaml` configuration file to use. + The shipped `rewrite.yaml` configuration files are located in your +`<{ProductShortName}_HOME>/rules/openrewrite` subfolder, for example,`" -Drewrite.configLocation=<{ProductShortName}_HOME>/rules/openrewrite/jakarta/javax/imports/rewrite.yaml"`. + +* `"-DactiveRecipes="`: Specify the OpenRewrite recipe, for example, `org.jboss.windup.JavaxToJakarta`. ++ +You can include more than one recipe by specifying each in the `activeRecipes` parameter. For example, to include the recipes `org.jboss.windup.JavaxInjectToJakartaInject` and `org.jboss.windup.JavaxEjbToJakartaEjb"`, enter the following for `"-DactiveRecipes="`: ++ +[source, terminal,subs="attributes+"] +---- + "-DactiveRecipes=org.jboss.windup.JavaxInjectToJakartaInject, \ + org.jboss.windup.JavaxEjbToJakartaEjb" +---- + +* `--goal`: Optional: The OpenRewrite Maven goal to run. +** `dryRun` : The script returns a list of proposed changes. Ignore the `"Run 'mvn rewrite:run' to apply the recipes"` message. +** `run`: The script applies the changes. + +. Run `windup-cli` with `--goal run` to apply the recipe: ++ +[source,terminal,subs="attributes+"] +---- +$ ./windup-cli --openrewrite --input \ + "-Drewrite.configLocation=" \ + "-DactiveRecipes=" --goal run +----