FlexDoc/XML - DiagramKit - FAQ

How To Run DiagramKit

Since DiagramKit is a part of FlexDoc/XML software, it will be pre-installed together with FlexDoc/XML.
Unfortunately, you won't be able to run DiagramKit immediately with any your Java setup. If you try, you will get an error like this:
Error occurred during initialization of boot layer
java.lang.module.FindException: Module javafx.base not found, required by flexdoc.xml.diagramkit
That's because DiagramKit requires JavaFX – the newest Java graphics/GUI platform, which is not included any longer in the standard Java SE. So, the installation of DiagramKit comes down to the installation of JavaFX and specifying its location in the script/build files running FlexDoc/XML+DiagramKit.

Where to get JavaFX?

In order to run DiagramKit, all JavaFX dependencies must be resolved. That can be achieved either:
Before Java 11, JavaFX was a part of the standard Java SE. So, no problem existed with those JavaFX dependencies, and FlexDoc/XML+DiagramKit could be run immediately with any new Java version.

But since Java 11, Oracle has moved JavaFX into a separate project found on openjfx.io. Now, those who need JavaFX should download JavaFX SDK separately from there, install it and specify all JavaFX dependencies in their Java application according to that installation. That, of course, is too complicated for many ordinary users, and breaks down the whole idea of using some generic JRE pre-installed on user's computer (independently on FlexDoc/XML).

However, as a compensation for all that perturbation (and actually as its goal), since Java 11, anyone could build their own custom JRE (called «runtime image») that would include in itself any 3rd party modules necessary to run a given application on a particular computer platform.

Now, we took that new opportunity and prepared our own FlexDoc JRE (OpenJDK+JavaFX images) to run FlexDoc/XML+DiagramKit on Windows, Linux and macOS immediately. Just download this Java from our website and don't bother with anything else!

Both possibilities are described below:

Using FlexDoc JRE

We offer a custom JRE (called «FlexDoc JRE»), which is a set of {OpenJDK+JavaFX} images prepared to run FlexDoc/XML+DiagramKit immediately. Here is the step-by-step instruction according to your OS:

Using FlexDoc JRE on Windows

  1. Go to the downloads page once again and download from there:

    “FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit | Windows/x64 (zip)”

    You should get this archive: flexdoc-jre-24_windows.zip
  2. Unpack it into {flexdoc-xml}. You will have a folder:

    {flexdoc-xml}\jre_windows

    That will be your Java to run FlexDoc/XML. You don't need to install anything else!
  3. Then, go correspondingly to either: Now, you can immediately start generator.bat and designer.bat found there to run Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

Using FlexDoc JRE on Linux

  1. Go to the downloads page once again and download from there:

    “FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit | Linux/64 (tar.gz)”

    You should get this archive: flexdoc-jre-24_linux.tar.gz
  2. Unpack it into {flexdoc-xml}. You will have a folder:

    {flexdoc-xml}/jre_linux

    That will be your Java to run FlexDoc/XML. You don't need to install anything else!
  3. Then, go correspondingly to either: You will find generator.sh and designer.sh prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.
  4. Set a permission to allow executing generator.sh / designer.sh as a program.
  5. Now, everything must be ready to run generator.sh / designer.sh!

Using FlexDoc JRE on macOS

As of macOS version 11 (Big Sur), Apple has tightened the «security control» so much that in order to install and run any macOS executables, they must come either from Apple Store or «signed» with an Apple Developer Account, which is quite expensive to maintain. Since, we are not a true macOS developer and the number of potential FlexDoc/XML users, who work on macOS, is too small, we do not see it reasonable to overcome that hurdle directly.

However, we take advantage of that Apple still allows the macOS users to install and run on their computer the executables built by those users themselves. So, instead of preparing a ready to install & run FlexDoc JRE, we offer you an easy way to build it by yourself (which differs from the former mostly by the size of the downloaded archive file).

  1. Go to the downloads page once again and download from there:

    “FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit | macOS/64 (zip)”

    You should get this archive: flexdoc-jre-24_macOS.zip
  2. Unpack it into {flexdoc-xml}. You will have a folder:

    {flexdoc-xml}/build_jre

    It does not contain a ready to use JRE. However, it contains all files necessary to build it, namely: Although, these archives do include the macOS executables, they are properly signed by their creators. So, macOS won't have security problems with them.
  3. Now, in order to build the real JRE, you only need to execute the following script found in the same folder:

    {flexdoc-xml}/build_jre/build_jre.command

    Although, macOS won't allow you to run 'build_jre.command' straight, that is easy to overcome:
    • First, open 'build_jre.command' with TextEdit (confirm in the warning box that it is OK to open it). Then, simply resave that file via File | Save menu. With that procedure, you will sign 'build_jre.command' as its owner/creator, which is a precondition to be able running it.
    • On top of that, you will need also to assign 'build_jre.command' with the executable privilege. Run the Terminal and type in it 'chmod u+x' followed by a space and the full pathname of the script file (instead of typing it, just drag 'build_jre.command' from the Finder into the Terminal window). Then, press Enter.
    Now at last, you can run 'build_jre.command' from the Finder just by clicking twice on it.
  4. After executing 'build_jre.command', a new directory will be created:

    {flexdoc-xml}/jre_macos

    That will be your Java to run FlexDoc/XML! (The 'build_jre' folder can be deleted then.)
  5. Then, go correspondingly to either: You will find generator.command and designer.command prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.
    But again, to be able to run any of those script files, first you need to
    • Resave the script file using TextEdit.
    • Assign it with the executable privilege (by running the Terminal, typing in it 'chmod u+x' followed by a space, dragging script.command into the Terminal window and pressing Enter).

Using standard Java + JavaFX SDK

If for some reasons you cannot use our FlexDoc JRE (for instance, in case of Maven), you may use any other (standard) Java installed on your system.

Then, you will need:

Using standard Java + JavaFX SDK on Windows

  1. Go to openjfx.io (or directly to https://gluonhq.com/products/javafx/) and download “JavaFX Windows SDK”, e.g.:

    openjfx-24_windows-x64_bin-sdk.zip

    Do not download “JavaFX Windows jmods” archive also available there! That is not a proper JavaFX SDK. Although, JMOD files contain some compiled images of Java modules, they can be processed only by jlink command, used to build a custom JRE.

    Unpack the downloaded archive somewhere. You will get a folder like this:

    C:\javafx-sdk-24

  2. Then, go correspondingly to either: Edit generator.bat / designer.bat found in that directory, in these lines:

    ::----------------------------------------------------------------------
    :: Specify the location of Java 11 (or later) here. The default setting:
    ::
    :: set JAVA_HOME=%FDH%\jre
    ::
    :: assumes the installation of FlexDoc JRE (OpenJDK+JavaFX),
    :: which you can download from http://www.flexdoc.xyz/downloads/
    ::----------------------------------------------------------------------
     set JAVA_HOME=C:\Program Files\Java\jdk-24

    ::----------------------------------------------------------------------
    :: Specify the location of JavaFX SDK 'lib' directory, e.g.:
    :: C:\javafx-sdk-24\lib
    ::
    :: Note: When you use FlexDoc JRE, leave this setting empty
    ::----------------------------------------------------------------------
     set PATH_TO_FX=C:\javafx-sdk-24\lib
  3. Now, you can start generator.bat / designer.bat to run Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

Using standard Java + JavaFX SDK on Linux

  1. Go to openjfx.io (or directly to https://gluonhq.com/products/javafx/) and download “JavaFX Linux SDK” archive, e.g.:

    openjfx-24_linux-x64_bin-sdk.zip

    Do not download “JavaFX Linux jmods” archive also available there! That is not a proper JavaFX SDK. Although, JMOD files contain some compiled images of Java modules, they can be processed only by jlink command, used to build a custom JRE.

    Unpack the downloaded archive somewhere. You will get a folder like this:

    /home/user/javafx-sdk-24

  2. Then, go correspondingly to either: You will find generator.sh and designer.sh prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

    Edit generator.sh / designer.sh in these lines:

    #----------------------------------------------------------------------
    # Specify the location of Java 11 (or later) here. The default setting:
    #
    # JAVA_HOME="$FDH/jre"
    #
    # assumes the installation of FlexDoc JRE (OpenJDK+JavaFX),
    # which you can download from http://www.flexdoc.xyz/downloads/
    #----------------------------------------------------------------------
     JAVA_HOME="/home/user/jdk-24"

    #----------------------------------------------------------------------
    # Specify the location of JavaFX SDK 'lib' directory, e.g.:
    # /home/user/javafx-sdk-24/lib
    #
    # Note: When you use FlexDoc JRE, leave this setting empty
    #----------------------------------------------------------------------
     PATH_TO_FX="/home/user/javafx-sdk-24/lib"
  3. Set a permission to allow executing generator.sh / designer.sh as a program.
  4. Now, everything must be ready to run generator.sh / designer.sh.

Using standard Java + JavaFX SDK on macOS

  1. Go to openjfx.io (or directly to https://gluonhq.com/products/javafx/) and download “JavaFX macOS SDK” archive, e.g.:

    openjfx-24_osx-x64_bin-sdk.zip

    Do not download “JavaFX Mac OS X jmods” archive also available there! That is not a proper JavaFX SDK. Although, JMOD files contain some compiled images of Java modules, they can be processed only by jlink command, used to build a custom JRE.

    Unpack the downloaded archive somewhere. You will get a folder like this:

    /Users/Shared/javafx-sdk-24

  2. Then, go correspondingly to either: You will find generator.command and designer.command prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

    Edit generator.command / designer.command in these lines:

    #----------------------------------------------------------------------
    # Specify the command used to invoke JVM (Java 11 or later) here.
    # The default setting:
    #
    # JAVA_COMMAND="$FDH/jre/bin/java"
    #
    # assumes the installation of FlexDoc JRE (OpenJDK+JavaFX),
    # which you can download from http://www.flexdoc.xyz/downloads/
    #----------------------------------------------------------------------
     JAVA_COMMAND="java"

    #----------------------------------------------------------------------
    # Specify the location of JavaFX SDK 'lib' directory, e.g.:
    # /Users/Shared/javafx-sdk-24/lib
    #
    # Note: When you use FlexDoc JRE, leave this setting empty
    #----------------------------------------------------------------------
     PATH_TO_FX="/Users/Shared/javafx-sdk-24/lib"
  3. To be able to run generator.command, first, open it with TextEdit (confirm in the warning box that it is OK to open it). Then, simply resave that file via File | Save menu. By doing that you will sign generator.command as its owner/creator, which is a precondition to be able running it.

    Then, you need to assign generator.command with the executable privilege. Run the Terminal and type in it 'chmod u+x' followed by a space and the full pathname of the script file (instead of typing it, just drag generator.command from the Finder into the Terminal window). Then, press Enter.

    Now, you can run generator.command from the Finder just by clicking twice on it.

  4. Equally with designer.command.

Integration with Ant/Maven/Docker

A demo about that you can find in your FlexDoc/XML installation:
{flexdoc-xml}/XSDDoc/run_with_DiagramKit/ant/
{flexdoc-xml}/XSDDoc/run_with_DiagramKit/maven/
{flexdoc-xml}/XSDDoc/run_with_DiagramKit/docker/

{flexdoc-xml}/WSDLDoc/run_with_DiagramKit/ant/
{flexdoc-xml}/WSDLDoc/run_with_DiagramKit/maven/
{flexdoc-xml}/WSDLDoc/run_with_DiagramKit/docker/

{flexdoc-xml}/plugins/DiagramKit/README.html
See Also:
FlexDoc/XML | DiagramKit | FAQ | Generator Setups |