Setup

JDK

To get started, you will need a JDK with version 25+. The JDK bin path has to be added to the PATH, so you will be able to run java -version in your terminal. For Linux and macOS, it is recommended to use SDKMAN to easily install any JDK.

The distribution of the JDK does not really matter, KickstartFX can adapt based on the individual JDK. For example, if you are using the Liberica JDK with bundled JavaFX, the build will use the included JavaFX dependencies. If you are using another JDK without JavaFX, then the build will use separate JavaFX dependencies.

The only thing to take care of is to not use a JDK which uses JEP493 where the JDK does not contain any jmods. The jlink/jpackage plugin does not support these JDKs yet, hopefully in the future it will.

Tools

Depending on what system you are developing on, you will need some additional tools to be installed to generate production artifacts.

Windows

On Windows, to build the msi installers, you need to have Visual Studio 2022 installed. It doesn't matter which edition, KickstartFX will automatically choose any available version.

You don't need to install WiX as this can be done automatically nowadays with the latest Visual Studio WiX projects.

Linux

Nothing

macOS

On macOS, you need to have Xcode installed, including the command-line tools for Xcode.

In addition to that, to create the dmg file, the create-dmg homebrew package needs to be present.

IDE

All XPipe components target Java 25 and make full use of the Java Module System (JPMS). All components are modularized, including all their dependencies. As this is a pretty complicated Java project that fully utilizes modularity and the latest versions, many IDEs still have problems building this project properly.

For example, you can't build this project in eclipse or vscode as it will complain about missing modules or other issues. The tested and recommended IDE is IntelliJ. When setting up the project in IntelliJ, make sure that the correct JDK (Java 25) is selected both for the project and for gradle itself.

How to read the docs

Once these steps are completed, you can now start looking through the documentation. Each page contains explanations, documentation, and more for certain features. Some of these might be relevant to your application, so you can just ignore those.

To properly follow the docs, you will need your Find file ... functionality in your IDE on hand as throughout the documentation, file names will be shown in bold. For example, the class file Main will be referenced with the bold name, not the full package name or link, as that becomes quite convoluted.

Variable names will be shown in italic, e.g. the variable productName in the root build.gradle file. For locating these individual variables within the file, just using the Find ... functionality should be enough.

Name customization

Once the project is up and running in your IDE, the next step is to configure the base template for your own purposes. This includes stuff like renaming packages and other application names to your own names.

The first step is to go to the root build.gradle file and change all properties under the naming section to use your application name, package names, etc. These variables contain the naming scheme of your application in various different contexts and should be consistent:

// Names of your app
productName = 'Kickstart FX'
kebapProductName = 'kickstart-fx'
snakeProductName = 'kickstart_fx'
// The names of your packages
groupName = 'io.abc_def'
artifactName = 'kickstart_fx'
// The base name of the generated packages
distName = "kickstartfx"

The next step is to also tell the application itself the same naming scheme in the AppNames class. There, you can configure the same information as in the build script.

Finally, you can rename the packages itself in your IDE to match your specified group name and artifact name. Once this is done, the app should build with your naming configuration.

Other basic information

The next step would be to use the Find in files ... functionality in your IDE and search for TODO. All additional items that require changing like the vendor name for your application installer, the links to your project page, and more are marked with a TODO comment. Note that you should not use the integrated ability of your IDE to look for TODO entries as some TODO entries are also placed in non-Java files. IDEs usually skip those, so it's best to just use the Find in files ... functionality.

Next steps

Now, the next step is to look at the gradle build and how to properly run it. See the build page page for that.