Quick start: the Person desk

This walkthrough uses NeitzelLib's fx-example, package de.neitzel.fx.example. Keep two separate checkouts: NeitzelLib contains the runtime and application; NeitzelFXDesigner contains the editor and project-side tools. The example runs without the Designer.

1. Run the JavaFX application first

Use a full JDK 21 and Maven. From the NeitzelLib checkout:

export JAVA_HOME=/absolute/path/to/jdk-21
mvn -B -ntp -pl fx-example -am -Dmaven.test.failure.ignore=false install
mvn -pl fx-example javafx:run

Check test reports: NeitzelLib’s parent POM currently hardcodes testFailureIgnore=true; the command-line flag alone does not override it. Inspect the nonempty target/surefire-reports/TEST-*.xml files in core, injection, fx and fx-example and require zero failures/errors before trusting either normal or preview-profile builds. A Maven BUILD SUCCESS alone is insufficient.

The first command builds/installs the required reactor modules. The second launches only the application module; do not add -am to javafx:run, because the parent and library modules have no application entry point. The Main launcher calls Application.launch(DeskApp.class, args). DeskApp creates the sample Person and injection context, then loads view/Desk.fxml through NeitzelLib's ViewLoader.

Edit the name and home address, add a visit or tag, and select a visit. The same visit list feeds both the Table and repeated forms. Close the application before continuing. The library's fx-example README explains the individual controls and binding behavior.

Artifact identity: a fresh Maven install can produce different JAR bytes even for the same source revision. This is a normal developer build, not proof that it matches the Designer maintainer's recorded binary baseline. Do not replace the hashes in docs/runtime/neitzellib-baseline.json merely to make a packaging check pass. See the source-build route and qualification distinction below.

2. Build the project-side tools and development host

Use JDK 25 in the Designer checkout:

export JAVA_HOME=/absolute/path/to/jdk-25
./mvnw -B -ntp install
./mvnw -B -ntp -pl designer-standalone \
  org.apache.maven.plugins:maven-dependency-plugin:3.6.1:build-classpath \
  -DincludeScope=runtime -Dmdep.outputFile=target/runtime-classpath.txt

This installs the Java 21 preview API, Model processor and Maven capture plugin, as well as building the shared host and worker tools. It does not build/install an IntelliJ plugin or publish artifacts remotely. The host requires JDK 25; the project-side tools and reference application use JDK 21.

check-bootstrap.py and package-standalone.py are maintainer qualification commands with an exact local runtime-artifact hash gate. After rebuilding/installing NeitzelLib, use the development launcher below unless that new runtime has been explicitly requalified and its provenance recorded. The runtime baseline record explains the gate. Do not describe an unqualified source build as the recorded packaged release.

3. Enable the example's optional preview profile

The current NeitzelLib checkout contains:

neitzel-fx-designer.json: checked-in person-desk context selecting fx-example and Maven profile designer-preview;
fx-example/src/designer/java/.../preview: typed preview providers and their tests;
fx-example/src/designer/resources/META-INF/neitzel-fx-designer/examples.properties: non-executing sample descriptors;
the optional profile in fx-example/pom.xml: test-scoped preview API, profile-only test sources/resources and generated Model metadata.

From NeitzelLib with JDK 21, validate that optional profile:

mvn -B -ntp -pl fx-example -am -Pdesigner-preview \
  -Dmaven.test.failure.ignore=false verify

The profile generates Model metadata for Person, Address and Note. It does not replace the hand-written PersonViewModel with a generated default. Without the profile, the normal application has no Designer preview dependency. Use a clean build when switching profiles if you need to prove that profile-only test output and generated metadata have been removed.

4. Create local runtime and launch settings

From the Designer checkout:

python3 scripts/configure-library-example.py \
  --library /absolute/path/to/NeitzelLib \
  --target-java-home /absolute/path/to/jdk-21

The helper writes ignored .neitzel-fx-designer/runtimes.json and host.properties under NeitzelLib. It uses the Designer Maven wrapper as the explicit fallback and current built worker-tool JARs. It refuses to overwrite existing settings; edit existing files explicitly. Machine paths belong here, not in the shared project configuration.

Launch the development host from the Designer checkout with JDK 25:

"$JAVA_HOME/bin/java" --enable-native-access=ALL-UNNAMED \
  -cp "designer-standalone/target/classes:$(cat designer-standalone/target/runtime-classpath.txt)" \
  de.neitzel.fxdesigner.standalone.Launcher \
  /absolute/path/to/NeitzelLib/.neitzel-fx-designer/host.properties \
  /absolute/path/to/NeitzelLib/fx-example/src/main/resources/de/neitzel/fx/example/view/Desk.fxml

The classpath separator above is : for the qualified macOS setup. It is not a Windows command.

If you have an already qualified development app bundle, use its bundled JVM instead:

"/path/to/NeitzelFXDesigner.app/Contents/MacOS/NeitzelFXDesigner" \
  --configuration /absolute/path/to/NeitzelLib/neitzel-fx-designer.json \
  --settings /absolute/path/to/NeitzelLib/.neitzel-fx-designer/runtimes.json \
  --maven /absolute/path/to/NeitzelFXDesigner/mvnw \
  /absolute/path/to/NeitzelLib/fx-example/src/main/resources/de/neitzel/fx/example/view/Desk.fxml

The bundle obtains worker tooling from inside the app. Its JVM does not replace the configured application JDK. See distribution instructions for app/ZIP creation and its current release boundaries.

5. Build, inspect and preview

Select Build and Refresh. The Designer builds an isolated copy of the selected reactor closure and publishes a successful snapshot. The original reactor's target directories are not the preview runtime.
The Desk example is selected for Desk.fxml. homeForm, the repeated visits and Table render through the target runtime. The enum ChoiceBox's runtime values are supplied in DeskController.initialize; the host does not instantiate application enum constants.
Inspect Bindings → Direct bindings. The nameField.text binding addresses name; the age binding uses AgeConverter. Unannotated Converters can be valid runtime code while carrying an unverified capability warning.
Open Interactive preview. This creates a fresh Person graph in another target process. Editing its controls changes only the preview Model, not a persistent application record or your FXML.
Select the home Component and Open Component. AddressForm.fxml opens in another editor. Repeating the action selects that existing editor. Its own address sample is available; opening NoteForm.fxml offers the independent note sample. Open Row Component opens VisitRow.fxml with its independent row sample.
Make an FXML edit, use Undo/Redo, save and reopen. Source is authoritative; the original imports, comments and unrelated formatting remain intact for supported edits.

Examples are filtered by the opened View. The parent selector does not list all five descriptors indiscriminately. Desk has desk; AddressForm has address; VisitForm has visit; VisitRow has row; NoteForm has note.

Verify this reference integration automatically

After building the tools and obtaining the packaged app, run:

python3 scripts/check-library-example.py \
  --library /absolute/path/to/NeitzelLib \
  --app /path/to/NeitzelFXDesigner.app \
  --java-home /absolute/path/to/jdk-25 \
  --target-java-home /absolute/path/to/jdk-21

The script copies the actual NeitzelLib checkout into a temporary directory. It builds that reactor through the real Designer, checks generated Model discovery, canvas pixels, source history/save, Component navigation and all five View-specific interactive samples. The external test agent is not shipped with the app or sample. It does not install rebuilt NeitzelLib JARs into your local Maven repository.

8.4 KiB Raw Blame History Unescape Escape