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_DIRECTORY ... --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_DIRECTORY ... --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_DIRECTORY --output OUTPUT_REPORT_DIRECTORY
  --source SOURCE_TECHNOLOGY --target TARGET_TECHNOLOGY --packages PACKAGE_1 PACKAGE_2 PACKAGE_N
      Copy to Clipboard Toggle word wrap

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

      bin/windup  --sourceMode --input INPUT_ARCHIVE_OR_DIRECTORY --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_DIRECTORY --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: 

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

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.

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

--output OUTPUT_REPORT_DIRECTORY

This is the fully qualified path to the directory that will contain the 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!

--sourceMode
If used, indicates the application to be evaluated contains source files rather than compiled binaries. See the the Input File Argument Description Table above for details.
--explodedApp
If used, indicates the directory contains source files for a single application or directory entries for multiple applications. See the the Input File Argument Description Table above for details.
--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, 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

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

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.

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

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

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

bin/windup --listTags
Copy to Clipboard Toggle word wrap
--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.
--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.
--exportCSV
Export the report data to a CSV formatted 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 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

Use this option to add additional JAR files or directories to the classpath so they are available for decompilation or other analysis. For example: 

--additionalClassPath MyClasses.jar com/mycompany/
Copy to Clipboard Toggle word wrap
--offline
If specified, do all processing offline and do not fetch updates or other data from the Internet.
--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. 

bin/windup --updateRulesets
Copy to Clipboard Toggle word wrap
--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.
--enableClassNotFoundAnalysis
Enables analysis of Java files that are not available on the Classpath. This should be left off if some classes will be unavailable at analysis time.
--enableTattletale
Enables Tattletale-embedded processing and Windup will generate a Tattletale report for each application.
--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.

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 directory 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 directory 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)
├── 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
Note

The incidents and 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.

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: Application List

Report Index Page

This page lists the applications that were 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. .

Click on the jee-example-app-1.0.0.ear link under the Name column to view the application report.

2.3.2.1. Application Report
Copy link

Report Index

The first section of the application report page summarizes the entire application migration effort. It summarizes the mandadory, optional, and potential issues that were found. It also breaks the findings down by type and by whether the suggested updates are informational, trivial, complex, need redesign, or require architectural changes. It also summarizes the issues by package.

This is followed by a list of reports that contain additional details about the migration of this application.

Expand
Report NameDescription

Migration Issues

The Migration Issues report provides a concise summary of all issues that require attention.

Application Details

This provides a detailed overview of all resources found within the application that may need attention during the migration.

Potential Issues

The Potential Issues report is a numerical summary of potential issues. While they may potentially require attention, there is currently no detailed migration guidance available for these items. If you see issues here that require effort, please send them to us for further assistance.

Unparsable

This report shows all files that Windup could not parse in the expected format. For instance, a file with a .xml or .wsdl suffix is assumed to be an XML file. If the XML parser fails, the issue is reported here and also where the individual file is listed.

Remote Services

This report displays all remote services references that were found within the application.

EJBs

The EJB report contains a list of EJBs found within the application.

Server Resources

This report displays all server resources (for example, JNDI resources) in the input application.

About

This describes the current version of Windup and provides helpful links for further assistance.

Windup Report - Report Index

Report Overview and Application Messages

Click on the Application Details link under Additional Reports to see the the Application Details Report.

Application Details Report

The report lists the estimated story points, the Java incidents by package, and a count of the occurrences of the technologies found in the application. Next is a display of application messages generated during the migration process. Finally, there is a breakdown of this information for each archive analyzed during the process.

Windup Report - Application Details Report

Application Details Report

Expand the jee-example-app-1.0.0.ear/jee-example-services.jar to review the estimated story points, Java incidents by package, and a count of the occurrences of the technologies found in this archive. This 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

File Analysis Pages

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 22 warnings and is assigned 16 story points. Click on the file link 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 provides 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.
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 HatBack to top