Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Get 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. Overview
Copy link

These instructions use the replaceable variable WINDUP_HOME to refer to the fully qualified path to your Windup installation. For more information, see About the WINDUP_HOME Variable.

2.2.2. Run Windup
Copy link

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

  2. Run Windup against the application using the appropriate command.

    See Windup Command Line Arguments below for a detailed description of the available command line arguments.

    • The basic command to run Windup uses the following syntax. 

      For Linux:     $ bin/windup --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --source SOURCE_TECHNOLOGY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
For Windows:   > bin\windup.bat --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --source SOURCE_TECHNOLOGY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
      Copy to Clipboard Toggle word wrap

    • To evaluate an application archive, use the following syntax: 

      bin/windup --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --source SOURCE_TECHNOLOGY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N --target eap
      Copy to Clipboard Toggle word wrap

    • To run Windup against application source code, add the --sourceMode argument: 

      bin/windup  --sourceMode --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --source SOURCE_TECHNOLOGY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
      Copy to Clipboard Toggle word wrap

    • To override the default Fernflower decompiler, pass the -Dwindup.decompiler argument on the command line. For example, to use the Procyon compiler, use the following syntax: 

      bin/windup -Dwindup.decompiler=procyon --input INPUT_ARCHIVE_OR_FOLDER --output OUTPUT_REPORT_DIRECTORY --source SOURCE_TECHNOLOGY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
      Copy to Clipboard Toggle word wrap

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

  3. You should see the following result upon completion of the command: 

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

    Depending on the size of the application and the hardware Windup is running on, this command can take a very long time. For tips on how to improve performance, see Optimize Windup Performance.

  4. Open the OUTPUT_REPORT_DIRECTORY/index.html file in a browser to access the report. The following subdirectories in the OUTPUT_REPORT_DIRECTORY contain the supporting information for the report: 

    OUTPUT_REPORT_DIRECTORY/
├── archives/
├── graph/
├── reports/
├── stats/
├── index.html
├── OPTIONAL_EXPORTED_CSV_FILE.csv
    Copy to Clipboard Toggle word wrap
  5. For details on how to evaluate the report data, see Review the Report.

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: 

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.

--input INPUT_ARCHIVE_OR_FOLDER
This is the fully qualified path of the application archive or folder you plan to migrate. This argument is required.
--output OUTPUT_REPORT_DIRECTORY (optional)

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

  • If omitted, the report will be generated in a INPUT_ARCHIVE_OR_FOLDER.report folder.

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

    Warning

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

--sourceMode (optional)
If specified, indicates the application to be evaluated contains source files rather than compiled binaries.
--source SOURCE_1 SOURCE_2 (optional)

A space delimited list of one or more source technologies, servers, platforms, or frameworks to migrate from.

Tip

For the list of the available --source servers or frameworks, use the --listSourceTechnologies argument on the windup command line as in the following example. 

bin/windup --listSourceTechnologies
Copy to Clipboard Toggle word wrap
--target TARGET_1 TARGET_2 (optional)

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, use the --listTargetTechnologies argument on the windup command line as in the following example. 

bin/windup --listTargetTechnologies
Copy to Clipboard Toggle word wrap
--packages PACKAGE_1 PACKAGE_2 PACKAGE_N (optional)

A space delimited list of the packages to be evaluated by Windup.

  • In most cases, you are interested only in evaluating custom application class packages and not standard Java EE or 3rd party packages. For example, if the MyCustomApp application uses the package com.mycustomapp, you provide that package using the --packages argument on the command line.
  • It is not necessary to provide the standard Java EE packages, like java.util or javax.ejb.

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

--overwrite (optional)
Specify this argument only if you are certain you want to force Windup to delete the existing OUTPUT_REPORT_DIRECTORY folder. If you do not specify this argument and the --output folder exists, you are prompted to choose whether to overwrite the contents.
--includeTags TAG_1 TAG_2 (optional)

Limit processing to rules that contain the specified tags. If this option is not specified, all tags are processed. Multiple tags are delimited by spaces.

Tip

For the list of the available tags, use the --listTags argument on the windup command line as in the following example. 

bin/windup --listTag
Copy to Clipboard Toggle word wrap
--excludeTags TAG_1 TAG_2 (optional)
Do not process rules that contain the specified tags. If this option is not specified, all tags are processed.
--userRulesDirectory CUSTOM_RULES_DIRECTORY (optional)
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 XML ruleset files must use one of the following extensions: *.windup.groovy or *.windup.xml.
--userIgnorePath CUSTOM_IGNORE_DIRECTORY (optional)
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.
--exportCSV (optional)
Export the report data to a CSV formatted file on your local file system. Windup creates the file in the folder specified by the --output argument. The CSV file can be imported into your favorite spreadsheet program for data manipulation and analysis. For details, see Export the Report for Use by Spreadsheet Programs.
--additionalClassPath JAR_OR_DIRECTORY_1 JAR_OR_DIRECTORY_2 (optional)

Use this option to add additional JAR files or directories to the classpath. For example: 

--additionalClassPath MyClasses.jar com/mycompany/
Copy to Clipboard Toggle word wrap
--excludePackages PACKAGE_1 PACKAGE_2 PACKAGE_N (optional)
This is a space-delimited list of the packages to be excluded by Windup.
--offline (optional)
If specified, do all processing offline and do not fetch information from the internet.
--updateRulesets (optional)

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. 

bin/windup --updateRulesets
Copy to Clipboard Toggle word wrap
--batchMode (optional)
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.

2.2.5. Windup Command Examples
Copy link

The following examples report against applications located in the Windup source test-files directory.

2.2.5.1. Source Code Example
Copy link

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

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

2.2.5.2. Archive Example
Copy link

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

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

2.2.5.3. Windup Quickstart Examples
Copy link

For more concrete examples, see the Windup quickstarts located on GitHub here: https://github.com/windup/windup-quickstarts. If you prefer, you can download the latest release ZIP or TAR distribution of the quickstarts.

The quickstarts provide examples of Java-based and XML-based rules you can run and test using Windup. The README instructions provide a step-by-step guide to run the quickstart example. You can also look through the code examples and use them as a starting point for creating your own rules.

2.3. Review the Report
Copy link

2.3.1. About the Report
Copy link

When you execute Windup, the report is generated in the OUTPUT_REPORT_DIRECTORY you specify for 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, for information only)
├── graph/              (binary graph database files generated during the run, for information only)
├── reports/            (generated HTML reports)
├── stats/              (performance statistics)
Copy to Clipboard Toggle word wrap

The report examples shown are a result of analyzing com.acme and org.apache packages in the test-files/jee-example-app-1.0.0.ear application, which is located in the Windup core source repository. The report was generated using the using the following command. 

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

2.3.2. Access the Reports
Copy link

Use your favorite browser to open the index.html file located in the output report directory. You should see something like the following:

Windup Report: Index Page Report Index Page

This page lists the application that was processed along with the technologies that were encountered. It also provides links to the following additional reports.

Expand
ReportHow to Access the Report

Application Report

Click on the link under the Name column to view this report.

Rule Provider Executions Report

Click on the All Rules link at the bottom of the index page.

Windup Freemarker Functions and Directives Report

Click on the Windup FreeMarker Methods link at the bottom of the index page.

Send Feedback Form

Click on the Send Feedback link at the bottom of the index page to open a form that allows you to provide feedback to the Windup team. .

2.3.2.1. Application Report
Copy link

2.3.2.1.1. Overview and Application Messages
Copy link

The first section of the application report page summarizes the entire application migration effort by technology type both graphically and in list format. This is followed by the Application Messages section, which contains useful information about general migration requirements for the application, such as the need to replace deprecated libraries or the need to resolve potential class loading issues.

In the following example, the "JEE Example App" is assigned 73 story points related to 10 different technologies. It also displays one application message "Deploying log4j.jar can result in non-deterministic ClassLoading issues. It is recommended to use the built-in JBoss EAP Log4j module configured via `jboss-deployment-structure.xml`" with a link to the rule that triggered it.

Note

The estimated Story Points change as new rules are added to Windup. The values here may not match what you see when you test this application.

Windup Report: Overview and Application Messages Report Overview and Application Messages

2.3.2.1.2. Archive Analysis Sections
Copy link

Depending on whether you run Windup against source or compiled code, the report next provides details by file, or by file within each archive. Each archive summary begins with a total of the story points assigned to its migration, followed by a table detailing the changes required for each file in the archive. The report contains the following columns.

Expand
Column NameDescription

Name

The name of the file being analyzed.

Technology

The type of file being analyzed, for example: Java Source, Decompiled Java File, Manifest, Properties, EJB XML, Spring XML, Web XML, Hibernate Cfg, Hibernate Mapping

Issues

Warnings about areas of code that need review or changes.

Estimated Story Points

Level of effort required to migrate the file.

Story Points are covered in more detail in the Windup Rules Development Guide.

The following is an example of the archive analysis summary section of a Windup Report. The following is an the analysis of the WINDUP_SOURCE/test-files/jee-example-app-1.0.0.ear/jee-example-services.jar.

Windup Report: Archive Detail Report Archive Detail

2.3.2.1.3. File Analysis Pages
Copy link

The analysis of the jee-example-services.jar lists the files in the JAR and the warnings and story points assigned to each one. Notice the com.acme.anvil.listener.AnvilWebLifecycleListener file, at the time of this test, has 20 warnings and is assigned 10 story points. Click on the file to see the detail.

  • The Information section provides a summary of the story points and notes that the file was decompiled by Windup.
  • This is followed by the file source code listing. Warnings appear in the file at the point where migration is required.

In this example, warnings appear at various import statements, declarations, and method calls. Each warning describes the issue and the action that should be taken.

Windup Report: Source Report - Part 1 File Detail - Part 1

Later in the source code, warnings appear for the creation of the InitialContext and for JNDI lookup names.

Windup Report: Source Report - Part 2 File Detail - Part 2

2.3.2.2. Rule Provider Execution Report
Copy link

As stated above,access this report by clicking on the All Rules link at the bottom of the index page. This report provides the list of rule providers that executed when running the Windup migration command against the application. The report contains the following columns.

Expand
Column NameDescription

Rule-ID

The Rule ID

Rule

The Java code for the rule

Statistics

Statistics behind the graph

Status?

Whether the rule executed or not

Result?

Whether the execution was successful or not

Failure Cause

The reason for an execution failure

Windup Report: Rule Provider Report RuleProvider Report

Access this report by clicking on the Windup FreeMarker Methods link on the initial index page. This report lists all the registered functions and directives that were used to build the report. It is useful if you plan to build your own custom report or for debugging purposes.

Windup Report: FreeMarker Functions and Directives FreeMarker Functions and Directives

2.3.2.4. Send Feedback Form
Copy link

Access the feedback form by clicking on the Send Feedback link on the initial index page. The form allows you to rate the product, talk about what you like and what needs to be improved. You can also attach a file.

Send Feedback Form Form to send feedback

Windup provides the ability to export the report data, including the Classifications and Hints, to a flat file on your local file system. The export function currently supports the CSV file format, which presents the report data as fields delimited by a comma (,) separator.

Windup follows the Common Format and MIME Type for Comma-Separated Values (CSV) Files standard for escaping special characters contained within each field in the file. The exported file has the following characteristics.

  1. The file is named with the `.csv' file extension.

  2. The first row is a header listing the names of the fields. 

    "Rule Id","Problem type","Title","Description","Links","Application","File Name","File Path","Line","Story points"
    Copy to Clipboard Toggle word wrap

  3. Each field is enclosed in double quotes ("). 

    "FindUnboundJavaReferencesRuleProvider","hint","Unresolved Class Binding","","","JEE Example EJB Services (org.windup.example:jee-example-services:1.0.0)","ProductCatalogLocalHome.java","/home/username/windup-reports/jee-example-app-1.0.0.ear-report/archives/jee-example-services.jar/com/acme/anvil/service/ProductCatalogLocalHome.java","9","5"
    Copy to Clipboard Toggle word wrap

  4. Any double quote (") appearing within a field is preceded with another double quote. 

    "MyWindupRule","hint",""Replace the ""foo"" class","Replace the ""foo"" class instances with ""bar""",,"MyApp","MyApp.java","home/username/MyApp","200","8"
    Copy to Clipboard Toggle word wrap

The CSV formatted file can be imported and manipulated by spreadsheet software such as Microsoft Excel and OpenOffice or LibreOffice Calc. Spreadsheet software provide the ability to sort, analyze, evaluate, and manage the result data from a Windup report.

2.4.1. Enable the Export Functionality
Copy link

To enable export of the report into CSV file, run Windup with --exportCSV argument. The CSV file will be created in the directory specified by the --output argument.

2.4.2. Import the CSV File into a Spreadsheet
Copy link

  1. Start the spreadsheet software (LibreOffice Calc, OpenOffice Calc, Microsoft Excel, etc.).
  2. Choose File -→ `Open'.
  3. Navigate to the CSV exported file and select it.
  4. The data is now ready to analyze in the spreadsheet software.

For more information or to resolve any issues, check the help for your spreadsheet software.

2.4.3. Overview of the CSV data structure
Copy link

The CSV formatted output file contains the following data fields:

Rule Id
The ID of the rule that generated the given item.
Problem type
"Hint" or "Classification"
Title
The title of the Classification or Hint. This field summarizes the issue for the given item.
Description
The detailed description of the issue for the given item.
Links
URLs that provide additional information about the issue. A link consists of two attributes: the link and a description of the link.
Application
The name of the application for which this item was generated.
File Name
The name of the file for the given item.
File Path
The file path of the file for the given item.
Line
The line number of the file for the given item.
Story points
The number of story points, which represent the level of effort, assigned to the given item.
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

© 2026 Red Hat