Document Designer workflows and qualify the real library example

scripts/configure-library-example.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Create ignored local launch settings for NeitzelLib's checked-in fx-example context."""
+import argparse
+import json
+import os
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument("--library", type=Path, required=True)
+parser.add_argument("--target-java-home", type=Path, required=True)
+parser.add_argument("--maven", type=Path, default=ROOT / "mvnw")
+args = parser.parse_args()
+library = args.library.resolve()
+java = args.target_java_home.resolve()
+maven = args.maven.resolve()
+if not (library / "neitzel-fx-designer.json").is_file():
+    parser.error("Library checkout has no designer configuration")
+if not all((java / "bin" / name).is_file() for name in ("java", "javac")):
+    parser.error("Supply a full application JDK installation")
+if not maven.is_file() or not os.access(maven, os.X_OK):
+    parser.error("Supply an executable Maven wrapper or Maven installation")
+tools = [ROOT / f"designer-{name}/target/designer-{name}-0.1.0-SNAPSHOT.jar"
+         for name in ("target-tools", "contracts", "preview-api")]
+if not all(file.is_file() for file in tools):
+    parser.error("Build/install the Designer Maven modules first")
+local = library / ".neitzel-fx-designer"
+settings = local / "runtimes.json"
+launch = local / "host.properties"
+if settings.exists() or launch.exists():
+    parser.error("Local settings already exist; edit them explicitly instead of overwriting them")
+local.mkdir(exist_ok=True)
+with settings.open("x") as file:
+    json.dump({"schemaVersion": "1.0", "runtimes": {
+        "java21": {"build": str(java), "target": str(java)}}}, file, indent=2)
+
+
+def prop(value):
+    """Escape Java properties values, including non-ASCII local paths."""
+    value = str(value).replace("\\", "\\\\").replace("\n", "\\n").replace("\r", "\\r")
+    escaped = []
+    for character in value:
+        if ord(character) < 128:
+            escaped.append(character)
+        else:
+            encoded = character.encode("utf-16-be")
+            escaped.extend("\\u%04x" % int.from_bytes(encoded[i:i + 2], "big")
+                           for i in range(0, len(encoded), 2))
+    return "".join(escaped)
+
+
+with launch.open("x", encoding="ascii") as file:
+    file.write("configuration=../neitzel-fx-designer.json\ncontext=person-desk\n"
+               "settings=runtimes.json\nmaven=" + prop(maven) + "\ntools="
+               + os.pathsep.join(map(prop, tools)) + "\n")
+print(settings)
+print(launch)