Skip to content

Installation

Jump to bottom
Frank Schüssele edited this page Dec 12, 2024 · 77 revisions

Download and Installation

This page explains how you setup a development environment for Ultimate. If you only want to produce a binary and use some of the tools, please have a look at Build and Usage.

Migration from Java 11 to Java 21

Prerequisites

  • Eclipse IDE for RCP and RAP Developers (version >= 2024.09)
  • Java JDK 21 Note: Java JRE is not sufficient.
    Note: You may also use the Java version integrated into Eclipse
  • Optional: Maven >=3.6
    Only needed if you want to build Ultimate from the command line.
  • A cloned repository of Ultimate
    Note: Parts of the repository use very long paths. Check our troubleshooting section git clone fails because paths are too long beforehand.

Create Eclipse workspace for Ultimate

  • Eclipse asks you to choose a workspace at startup.
    • Important: Use the directory <ULTIMATE>/trunk/source.
    • If the "Workspace Launcher" dialog is not shown, it can be found by selecting File -> Switch Workspace.
  • Import the predefined settings:
    • Go Window -> Preferences -> Import (icon on the bottom left) and select <ULTIMATE>/releaseScripts/eclipse_settings.epf
    • Restart Eclipse (as suggested)
  • Check Java Formatter settings (should be already imported, but fails in some cases)
    • Go Window -> Preferences -> Java -> Code Style -> Formatter
    • If the active profile is not Ultimate, click Import... and choose <ULTIMATE>/releaseScripts/coding-conventions/eclipse-java-formatter.xml
  • Go to Window -> Preferences -> Java -> Installed JREs and select a compatible JDK >= 21
  • Import all Ultimate plugins
    • Choose File -> Import -> General -> Existing Projects into Workspace.
    • In Select root directory, use the directory <ULTIMATE>/trunk/source. In Projects, a list of available projects should appear.
    • Keep everything selected.
    • Click Finish. If plugins starting with Web* have been selected, Eclipse may propose to install "jsNature". You can ignore that.
  • Load new target platform
    • Navigate to the project BA_SiteRepository
    • Open the *.target file that matches your operating system (i.e., for Windows open Ultimate_E4.32_Java21_Win32.target)
    • Select Set as Active Target Platform (its a link in the upper right corner)
    • Wait until the target platform is loaded (this might take some time)
  • Clean and rebuild Ultimate
    • Open Project -> Clean....
    • Select Clean all projects, Start a build immediately, and Build the entire workspace
    • Click Clean

Now the "Package Explorer" view should be filled with the new projects and you should have no errors in the Problems view.

If you cannot build Ultimate because some of the projects have errors (errors in projects starting with Web* are not problematic), check the Troubleshooting section.

Create run configuration

  • Open the project BA_SiteRepository.
  • Open the file Debug-E4.product.
  • In tab Overview, section Testing:
    • Click Synchronize.
    • Click Launch an Eclipse application.

As a result, Ultimate with Debug View should start and you should have an entry in your Run Configurations and Run History (accessible via the Run menu) that you can use to run Ultimate from here on.

Close Ultimate and edit the Run Configuration you just created

  • Open the tab Environment.
  • Press button Add...
  • Add a new variable name PATH and enter as value ${workspace_loc}/../../releaseScripts/default/adds (or the absolute path on your filesystem to the folder releaseScripts/default/adds).
  • Open the tab Configuration and uncheck Clear the configuration before launching (to speedup the launch)
  • Save your changes.

Different configurations (e.g., command line or CDT plugin) can be run in the same way, just select another .product file.

Custom VM arguments (e.g., more memory)

  • Open the "Run"->"Run Configurations..." dialog.
  • Open the tab "Arguments".
  • Write in field "VM Arguments": -Xmx4096M -Xms1024M.
    • The first argument sets the maximum heap size to 4096M (megabyte) and the second one the initial heap size to 1024M.
    • Never forget the M, otherwise Java uses bytes.
  • -agentlib:hprof=depth=7,cpu=samples can be used for profiling.
  • for more options see http://stas-blogspot.blogspot.de/2011/07/most-complete-list-of-xx-options-for.html or
    • use java -XX:+PrintFlagsFinal to print available -XX options.
    • More diagnostic and experimental options can be added to list with following options:
      • -XX:+UnlockDiagnosticVMOptions
      • -XX:+UnlockExperimentalVMOptions (for Sun)

Run JUnit tests in Eclipse

  • Open the desired Java test-class in Eclipse (e.g. RegressionTestSuite)
  • Go to Run and select JUnit Plug-in Test
  • Cancel the launch immediately (it would take really long and may fail)
  • Edit the Run Configuration you just created
    • Go to Arguments and add -Dequinox.resolver.revision.batch.size=1 to VM arguments
    • Open the tab Configuration and uncheck Clear the configuration before launching (to speedup the launch)
    • Go to Plug-ins and click Validate Plug-ins
    • If No problems were detected, you may just save the run configuration (Apply)
    • Otherwise chose Launch with: Plug-ins selected below and uncheck plug-ins until validation succeeds (usually plug-ins containing xmlrpc, jasper and webapp can and should be disabled), then Apply

Next steps

See Usage for working with the developer GUI.
See Eclipse-Settings for more settings recommendations of Eclipse.
See CodingConvention for our coding conventions.

Migration from Java 11 to Java 21

  • Update your Eclipse IDE for RCP and RAP Developers to version >= 2024.09
  • Update the dev branch of your Ultimate repository to the newest version
  • Import the predefined settings:
    • Go Window -> Preferences -> Import (icon on the bottom left) and select <ULTIMATE>/releaseScripts/eclipse_settings.epf
    • Restart Eclipse (as suggested)
  • Check Java Formatter settings (should be already imported, but fails in some cases)
    • Go Window -> Preferences -> Java -> Code Style -> Formatter
    • If the active profile is not Ultimate, click Import... and choose <ULTIMATE>/releaseScripts/coding-conventions/eclipse-java-formatter.xml
  • Go to Window -> Preferences -> Java -> Installed JREs and select a compatible JDK >= 21 (you may use the one integrated into Eclipse)
  • Delete obsolete Libary plugins: rm -r trunk/source/Library-JavaBDD/ trunk/source/Library-ojAlgo/
  • Load new target platform
    • Navigate to the project BA_SiteRepository
    • Open the *.target file that matches your operating system (i.e., for Windows open Ultimate_E4.32_Java21_Win32.target)
    • Select Set as Active Target Platform (its a link in the upper right corner)
    • Wait until the target platform is loaded (this might take some time)
  • Clean and rebuild Ultimate
    • Open Project -> Clean....
    • Select Clean all projects, Start a build immediately, and Build the entire workspace
    • Click Clean
  • Adapt your run configurations
    • Note In particular for JUnit and JUnit Plug-in Test run configurations, it might be easier to delete them and recreate them as needed.
    • Select a run configuration, e.g., Debug-E4.product
    • In Main (or JRE for JUnit run configurations), change Execution environment to JavaSE-21
    • In Plug-ins, click on Add Required Plug-ins
    • In Configuration, uncheck Clear the configuration before launching (to speedup the launch)
    • Repeat for all run configurations you want to keep
Clone this wiki locally