117 lines
8.4 KiB
Markdown
117 lines
8.4 KiB
Markdown
# 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:
|
||
|
||
```sh
|
||
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](https://gitea.neitzel.de/konrad/NeitzelLib/src/branch/main/fx-example/README.md) 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:
|
||
|
||
```sh
|
||
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](../runtime/neitzellib-baseline.md) 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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
"$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:
|
||
|
||
```sh
|
||
"/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](../standalone-distribution.md) for app/ZIP creation and its current release boundaries.
|
||
|
||
## 5. Build, inspect and preview
|
||
|
||
1. 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.
|
||
2. 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.
|
||
3. 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.
|
||
4. 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.
|
||
5. 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.
|
||
6. 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:
|
||
|
||
```sh
|
||
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.
|