Chapter 2. Getting Started

2.1. Install Windup

Download the latest Windup ZIP distribution.
Extract the ZIP file in to a directory of your choice.

2.2. Execute Windup

2.2.1. Run Windup

Use the following steps to run Windup against your application.

Open a terminal and navigate to the WINDUP_HOME/bin directory.
Execute the windup script, or windup.bat for Windows, and specify the appropriate arguments.
```
$ ./windup --input /path/to/jee-example-app-1.0.0.ear --output /path/to/output --source weblogic --target eap:6 --packages com.acme org.apache
```
- --input: The application to be evaluated. See the --input argument description.
- --output: The output directory for the generated reports. See the --output argument description.
- --source: The source technology for the application migration. See the --source argument description.
- --target: The target technology for the application migration. See the --target argument description.
- --packages: The packages to be evaluated. This argument is highly recommended to improve performance. See the --packages argument description.
See Windup Command-Line Arguments for a detailed description of all available command-line arguments.
Review the report.
Upon completion, you will see the following message in the terminal.
```
Windup report created: PATH_TO_REPORTS/index.html
              Access it at this URL: file:///PATH_TO_REPORTS/index.html
```
Navigate to the output directory and open the index.html file in a web browser. See the Review the Reports section for more details on evaluating report data.

See Windup Command Examples below for concrete examples of commands that use source code directories and archives located in the Windup GitHub repository.

2.2.2. Windup Command Examples

Running Windup on Source Code

The following command runs against the Windup seam-booking-5.2 test application source code. It evaluates all org.jboss.seam packages and creates a directory named 'seam-booking-report' in the /home/username/windup-reports/ directory to contain the reporting output.

$ WINDUP_HOME/bin/windup --sourceMode --input /home/username/windup-source/test-files/seam-booking-5.2/ --output /home/username/windup-reports/seam-booking-report --target eap:6 --packages org.jboss.seam

Running Windup on an Application Archive

The following command runs against the Windup jee-example-app-1.0.0.ear test EAR archive. It evaluates all com.acme and org.apache packages and creates a directory named 'jee-example-app-1.0.0.ear-report' in the /home/username/windup-reports/ directory to contain the reporting output.

$ WINDUP_HOME/bin/windup  --input /home/username/windup-source/test-files/jee-example-app-1.0.0.ear --output /home/username/windup-reports/jee-example-app-1.0.0.ear-report --target eap:6 --packages com.acme org.apache

Override Windup 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:

$ WINDUP_HOME/bin/windup -Dwindup.decompiler=procyon --input INPUT_ARCHIVE_OR_DIRECTORY --output OUTPUT_REPORT_DIRECTORY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2

2.2.3. Windup Help

To see the complete list of available arguments for the windup command, open a terminal, navigate to the WINDUP_HOME directory, and execute the following command:

$ WINDUP_HOME/bin/windup --help

2.2.4. Windup Command-Line Arguments

The following is a detailed description of the available Windup command line arguments.

Note

To run the Windup command without prompting, for example when executing from a script, use --batchMode to take the default values for unspecified parameters and --overwrite to force delete the output directory. Also be sure to specify the required --input and --target arguments.

See the description for each argument for more details.

--additionalClassPath JAR_OR_DIRECTORY_1 JAR_OR_DIRECTORY_2

Use this option to add additional JAR files or directories to the class path so they are available for decompilation or other analysis. For example, --additionalClassPath MyClasses.jar com/mycompany/.

--addonDir DIRECTORY

Add the specified directory as a custom add-on repository.

--batchMode

Specifies that Windup should be run in a non-interactive mode without prompting for confirmation. This mode takes the default values for any parameters not passed in via the command line.

--debug

Run Windup in debug mode.

--discoverPackages

Lists all available packages in the input application or source.

--enableClassNotFoundAnalysis

Enables analysis of Java files that are not available on the class path. This should be left off if some classes will be unavailable at analysis time.

--enableCompatibleFilesReport

Enables generation of 'Compatible Files' report. Due to processing all files without found issues, this report may take a long time for large applications.

--enableTattletale

Enables Tattletale-embedded processing and Windup will generate a Tattletale report for each application.

--excludePackages PACKAGE_1 PACKAGE_2 PACKAGE_N

This is a space-delimited list of the packages to be excluded by Windup. For example, entering "com.mycompany.commonutilities" would exclude all classes whose package name begins with "com.mycompany.commonutilities".

This parameter is very important when dealing with large applications as it can greatly reduce execution time.

--excludeTags TAG_1 TAG_2

Do not process rules that contain the specified tags. This option can be used if it is found that a particular set of rules is highlighting too much unnecessary information in the report. If this option is not specified, all tags are processed.

Note

For the list of the available tags, pass the --listTags argument to the windup command.

--explodedApp

If used, indicates the directory contains source files for a single application or directory entries for multiple applications. See the Input File Argument Description Table for details.

--exportCSV

Export the report data to a CSV file on your local file system. Windup creates the file in the directory specified by the --output argument. The CSV file can be imported into a spreadsheet program for data manipulation and analysis. For details, see Export the Report in CSV Format.

--help

Display the Windup help message.

--immutableAddonDir DIRECTORY

Add the specified directory as a custom read-only add-on repository.

--includeTags TAG_1 TAG_2

In Windup, each rule is associated with a set of tags. Tags are just simple strings that succinctly describe the function of the rule. Common tags include "ejb", "log4j", and "hibernate". To see the full list of tags, use the --listTags argument.

When one or more tags are specified here, then only rules with these tags will be processed. If this option is not specified, then all tags are processed.

--input INPUT_ARCHIVE_OR_DIRECTORY […]

Each input argument is a fully qualified path to a file or directory containing one or more applications to be migrated. Multiple paths are separated by a space. This argument is required and can appear multiple times in the command.

When used in combination with the following arguments, the file input type is evaluated as follows.

Table 2.1. Input File Argument Description Table
Input File Type	`--explodedApp` Argument	`--sourceMode` Argument	Neither Argument Specified
Directory	Directory evaluated as a single application.	Directory evaluated as a single application.	Each directory entry is evaluated as a single application.
File	Argument is ignored and the file is evaluated as a single application.	The file is evaluated as a compressed project.	The file is evaluated as a single application.

--install GROUP_ID:ARTIFACT_ID[:VERSION]

Install the specified add-ons. For example, --install core-addon-x or --install org.example.addon:example,1.0.0.

--keepWorkDirs

Instructs Windup to not delete temporary working files, such as the graph database and unzipped archives. This is useful for debugging purposes.

--list

List installed add-ons.

--listSourceTechnologies

List all available source technologies.

--listTags

List all available tags.

--listTargetTechnologies

List all available target technologies.

--mavenize

Create a Maven project directory structure based on the structure and content of the application. This creates pom.xml files using the appropriate Java EE API and the correct dependencies between project modules. See also the --mavenizeGroupId option.

--mavenizeGroupId

When used with the --mavenize option, all generated pom.xml files will use this value for their <groupId>. If this parameter is omitted, Windup will attempt to determine an appropriate <groupId> based on the application, or will default to com.mycompany.mavenized.

--offline

If specified, do all processing offline and do not fetch updates or other data from the Internet.

--output OUTPUT_REPORT_DIRECTORY

This is the fully qualified path to the directory that will contain the report information produced by Windup.

If omitted, the report will be generated in an INPUT_ARCHIVE_OR_DIRECTORY.report directory.
If the output directory exists, you will be prompted with the following (with a default of N).
```
Overwrite all contents of "/home/username/OUTPUT_REPORT_DIRECTORY" (anything already in the directory will be deleted)? [y,N]
```
However, if you specify the --overwrite argument, Windup will proceed to delete and recreate the directory. See the description of this argument for more information.

--overwrite

Specify this argument only if you are certain you want to force Windup to delete the existing OUTPUT_REPORT_DIRECTORY directory. If you do not specify this argument and the --output directory exists, you are prompted to choose whether to overwrite the contents.

Warning

Be careful not to specify a report output directory that contains important information!

--packages PACKAGE_1 PACKAGE_2 PACKAGE_N

A space delimited list of the packages to be evaluated by Windup. It is highly recommended to use this argument.

In most cases, you are interested only in evaluating custom application class packages and not standard Java EE or 3rd party packages. The PACKAGE_N argument is a package prefix; all subpackages will be scanned. For example, to scan the packages com.mycustomapp and com.myotherapp, use --packages com.mycustomapp com.myotherapp argument on the command line.
While you can provide package names for standard Java EE 3rd party software like org.apache, it is usually best not to include them as they should not impact the migration effort.
Warning
If you omit the --packages argument, every package in the application is scanned, which can impact performance. It is best to provide this argument with one or more packages. For additional tips on how to improve performance, see Optimize Windup Performance.

--remove GROUP_ID:ARTIFACT_ID[:VERSION]

Remove the specified add-ons. For example, --remove core-addon-x or --remove org.example.addon:example,1.0.0.

--source SOURCE_1 SOURCE_2

A space-delimited list of one or more source technologies, servers, platforms, or frameworks to migrate from. This argument, in conjunction with the --target argument, helps to determine which rulesets are used. Use the --listSourceTechnologies argument to list all available sources.

The --source argument now provides version support, which follows the Maven version range syntax. This instructs Windup to only run the rulesets matching the specified versions. For example, --source eap:5.

Warning

When migrating to JBoss EAP, be sure to specify the version, for example, eap:6. Specifying only eap will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path.

See Supported Migration Paths for which JBoss EAP version is appropriate for your source platform.

--sourceMode

If used, indicates the application to be evaluated contains source files rather than compiled binaries. See the Input File Argument Description Table for details.

--target TARGET_1 TARGET_2

A space-delimited list of one or more target technologies, servers, platforms, or frameworks to migrate to. This argument, in conjunction with the --source argument, helps to determine which rulesets are used. If you do not specify this option, you are prompted to select a target. Use the --listTargetTechnologies argument to list all available targets.

The --target argument now provides version support, which follows the Maven version range syntax. This instructs Windup to only run the rulesets matching the specified versions. For example, --target eap:7.

Warning

When migrating to JBoss EAP, be sure to specify the version in the target, for example, eap:6. Specifying only eap will run rulesets for all versions of JBoss EAP, including those not relevant to your migration path.

See Supported Migration Paths for which JBoss EAP version is appropriate for your source platform.

--updateRulesets

Update the core rulesets distributed with Windup. It first checks for the existence of newer release, and if found, replaces the current rulesets directory with the new one.

Note

To update the rulesets without analyzing an application, pass only this argument on the windup command line as in the following example.

$ WINDUP_HOME/bin/windup --updateRulesets

--userIgnorePath CUSTOM_IGNORE_DIRECTORY

Windup looks for file names matching the pattern *windup-ignore.txt to identify files that should be ignored. By default, it looks for these files in the ~/.windup/ignore/ and WINDUP_HOME/ignore/ directories, but this option allows you to create files with this pattern name in a different directory.

--userRulesDirectory CUSTOM_RULES_DIRECTORY

By default, Windup looks for rules in the ${user.home}/.windup/rules/ directory. This option allows you to provide the fully qualified path to a user directory containing additional custom XML rules that should be loaded and executed by Windup. The ruleset files must use one of the following extensions: *.windup.groovy or *.windup.xml.

--version

Display the Windup version.

2.3. Access the Report

When you execute Windup, the report is generated in the OUTPUT_REPORT_DIRECTORY that you specify using the --output argument in the command line. This output directory contains the following files and subdirectories:

OUTPUT_REPORT_DIRECTORY/
├── index.html          // Landing page for the report
├── EXPORT_FILE.csv     // Optional export of data in CSV format
├── archives/           // Archives extracted from the application
├── mavenized/          // Optional Maven project structure
├── reports/            // Generated HTML reports
├── stats/              // Performance statistics

Use a browser to open the index.html file located in the report output directory. See the Review the Reports section for information on navigating the Windup reports.

Chapter 2. Getting Started

2.1. Install Windup

2.2. Execute Windup

2.2.1. Run Windup

2.2.2. Windup Command Examples

Running Windup on Source Code

Running Windup on an Application Archive

Override Windup Properties

2.2.3. Windup Help

2.2.4. Windup Command-Line Arguments

2.3. Access the Report

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links