Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Getting Started

2.1. Install Windup
Copy link

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

2.2. Execute Windup
Copy link

2.2.1. Run Windup
Copy link

Use the following steps to run Windup against your application.

  1. Open a terminal and navigate to the WINDUP_HOME/bin directory.

  2. 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 --target eap --packages com.acme org.apache
    Copy to Clipboard Toggle word wrap

    At a minimum, you must specify the input archive or directory (--input) and the target technology (--target). Use the --sourceMode argument to run Windup against application source code. See Windup Command-Line Arguments for a detailed description of all available command-line arguments.

    Warning

    Depending on the size of the application and the hardware Windup is running on, this command can take a very long time. It is recommended to specify one or more packages to evaluate. For additional tips on how to improve performance, see Optimize Windup Performance.

    You will see the following message in the terminal upon completion: 

    Windup report created: PATH_TO_REPORTS/index.html
              Access it at this URL: file:///PATH_TO_REPORTS/index.html
    Copy to Clipboard Toggle word wrap

  3. Review the report.

    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
Copy link

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 --packages org.jboss.seam
Copy to Clipboard Toggle word wrap
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 --packages com.acme org.apache
Copy to Clipboard Toggle word wrap
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
Copy to Clipboard Toggle word wrap

2.2.3. Windup Help
Copy link

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
Copy to Clipboard Toggle word wrap

2.2.4. Windup Command-Line Arguments
Copy link

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

Tip

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.

Tip

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.

Expand
Table 2.1. Input File Argument Description Table
Input File Type--explodedApp Argument--sourceMode ArgumentNeither 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]
    Copy to Clipboard Toggle word wrap

    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.

--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 determines which rulesets are used during migration. Example: --source eap

Tip

For the list of the available --source servers or frameworks, pass the --listSourceTechnologies argument to the windup command.

--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. If you do not specify this option, you are prompted to select a target. The default target technology is eap.

Tip

For the list of the available --target servers or frameworks, pass the --listTargetTechnologies argument to the windup command.

--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.

Tip

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
Copy to Clipboard Toggle word wrap
--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
Copy link

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 {ProductShortName} 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
Copy to Clipboard Toggle word wrap

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.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat