Headless CSS compiler: no display, no browser, no designer jar

.github/workflows/_build-mac-port.yml

@@ -98,11 +98,12 @@ jobs:
           # triggers on, and scripts-macos.yml triggers on maven/** -- so naming
           # codenameone-maven-plugin and svg-transcoder left every other module
           # able to start this job and then hit an exact cache. build-mac-port.sh
-          # runs `-pl designer -am` and `-pl mac -am`, so the modules it actually
+          # runs `-pl css-cli -am` and `-pl mac -am`, so the modules it actually
           # rebuilds are the transitive dependencies of those two: core,
-          # css-compiler, javase, factory and the rest. A CSS compiler change is
-          # the concrete case -- the script rebuilds designer precisely so it
-          # reaches the test app, and the cache key was cancelling that rebuild.
+          # css-compiler, project-model, factory and the rest. A CSS compiler
+          # change is the concrete case -- the script reinstalls css-cli precisely
+          # so it reaches the test app, and the cache key was cancelling that
+          # rebuild.
           # Listing them would be the same mistake one module later, so the
           # subtree is hashed and the list is gone.
           #
@@ -120,9 +121,9 @@ jobs:
           # null-aware sort.
           # CodenameOneDesigner/src is here because maven/designer is a pom and
           # nothing else -- it sets <sourceDirectory>../../CodenameOneDesigner/src,
-          # so the module the build script rebuilds by name compiles a tree that
-          # lives outside maven/ entirely. Hashing maven/ alone would have looked
-          # complete and still missed it.
+          # so a module setup-workspace.sh installs into the cached repository
+          # compiles a tree that lives outside maven/ entirely. Hashing maven/
+          # alone would have looked complete and still missed it.
           SRC_HASH=$(find CodenameOne/src Ports/MacPort Ports/iOSPort vm/JavaAPI vm/ByteCodeTranslator Themes native-themes \
               CodenameOneDesigner/src \
               maven \

.github/workflows/archetype-smoke.yml

@@ -1,7 +1,7 @@
 name: Archetype simulator smoke
 
 # Smoke-tests that an archetype-generated project can run `cn1:css` (the
-# CN1CSSCLI subprocess that boots JavaSEPort) with `cn1.autoDefaultResourceBundle`
+# CN1CSSCLI subprocess, which runs headless) with `cn1.autoDefaultResourceBundle`
 # forced on. This reproduces the user-side preference state that masked
 # issue #4850 in CI for six months: the bug was deterministic on the user
 # code path but invisible to CI runners with the default-false preference.
@@ -17,6 +17,8 @@ on:
       - 'CodenameOneDesigner/**'
       - 'CodenameOne/src/com/codename1/ui/plaf/UIManager.java'
       - 'maven/codenameone-maven-plugin/**'
+      - 'maven/css-compiler/**'
+      - 'maven/css-cli/**'
       - 'maven/build-engine/**'
       - 'maven/project-model/**'
       - 'maven/cn1app-archetype/**'
@@ -42,6 +44,8 @@ on:
       - 'CodenameOneDesigner/**'
       - 'CodenameOne/src/com/codename1/ui/plaf/UIManager.java'
       - 'maven/codenameone-maven-plugin/**'
+      - 'maven/css-compiler/**'
+      - 'maven/css-cli/**'
       - 'maven/build-engine/**'
       - 'maven/project-model/**'
       - 'maven/cn1app-archetype/**'
@@ -96,6 +100,11 @@ jobs:
       # them need those headers to compile at all: without them this failed on
       # "'curl/curl.h' file not found" after translating perfectly well. The same
       # four packages, for the same reason, are in parparvm-tests.yml.
+      #
+      # xvfb is for the minimal-layout step, which runs cn1:test in the
+      # simulator's runner, and is left around the archetype smoke as it was.
+      # Compiling a project's CSS needs no display: the framework build and
+      # the staged-jar step run without one, and the latter is the guard.
       - name: Install xvfb and the native backend toolchain
         run: |
           bash scripts/ci/apt-get-install.sh xvfb clang \
@@ -116,12 +125,12 @@ jobs:
           # -Darchetype.test.skip=true keeps the smoke fast — the per-tag
           # ITs already run in the release workflow.
           cd maven
-          bash ../scripts/ci/retry.sh xvfb-run -a mvn install -Plocal-dev-javase -DskipTests -Darchetype.test.skip=true -Dmaven.javadoc.skip=true
+          bash ../scripts/ci/retry.sh mvn install -Plocal-dev-javase -DskipTests -Darchetype.test.skip=true -Dmaven.javadoc.skip=true
       - name: Refresh archetype catalog
         run: |
           cd maven
-          xvfb-run -a mvn archetype:update-local-catalog -Plocal-dev-javase
-          xvfb-run -a mvn archetype:crawl -Plocal-dev-javase
+          mvn archetype:update-local-catalog -Plocal-dev-javase
+          mvn archetype:crawl -Plocal-dev-javase
       - name: Run archetype simulator smoke (auto-bundle pref forced on)
         env:
           # The packaging check must not be skipped on a runner that has clang.
@@ -135,8 +144,13 @@ jobs:
       - name: Check the staged upload jar of every build target
         run: |
           cd maven/integration-tests
-          # The project's CSS compile opens an AWT frame, so it needs a display.
-          xvfb-run -a bash cn1app-staged-jar-test.sh
+          # DISPLAY and WAYLAND_DISPLAY are cleared on purpose, and this must
+          # never be wrapped in xvfb-run: the script generates a project and
+          # builds every target, which compiles the project's theme.css each
+          # time, so passing here proves the CSS compile needs no display. A
+          # compiler change that reaches for a window fails this step instead
+          # of the first developer who builds over ssh or in a container.
+          env -u DISPLAY -u WAYLAND_DISPLAY bash cn1app-staged-jar-test.sh
       # The archetype's default layouts: an app with no platform modules, whose
       # common module builds, tests and stages every platform, and a backend-only
       # project. Nothing is submitted and the simulator is never launched.

.github/workflows/designer.yml

@@ -47,7 +47,7 @@ jobs:
           cache: 'maven'
 
       - name: Install build dependencies
-        run: bash scripts/ci/apt-get-install.sh xvfb unzip
+        run: bash scripts/ci/apt-get-install.sh unzip
 
       - name: Cache cn1-binaries
         uses: actions/cache@v5
@@ -69,7 +69,7 @@ jobs:
           rm -rf maven/target/cn1-binaries
           cp -R ../cn1-binaries maven/target/cn1-binaries
 
-      - name: Build Designer (pulls in codenameone-css-compiler as dep)
+      - name: Build Designer (pulls in codenameone-css-compiler and codenameone-css-cli as deps)
         env:
           CN1_BINARIES: ${{ github.workspace }}/maven/target/cn1-binaries
         run: |
@@ -97,7 +97,8 @@ jobs:
           # CN1CSSCLI lives in the thin codenameone-css-cli module and is launched
           # on a resolved classpath (see AbstractCN1Mojo.getCssCliClasspath and the
           # simulator's CSSWatcher), not as a shaded `java -jar`. Exercise it the
-          # same way here.
+          # same way here, with java.awt.headless set and DISPLAY cleared: the
+          # compiler opens no window and must keep working where there is none.
           cd maven
           bash $GITHUB_WORKSPACE/scripts/ci/retry.sh mvn -B -q -pl css-cli -Plocal-dev-javase \
               -Dmdep.outputFile="$PWD/css-cli-cp.txt" dependency:build-classpath
@@ -116,14 +117,14 @@ jobs:
           cat <<'EOF' > "$l10n_dir/Strings.properties"
           greeting=Hello from CLI
           EOF
-          xvfb-run -a java -Dcli=true -cp "$cp" com.codename1.designer.css.CN1CSSCLI \
-            -css -stateless -input "$css_file" -output "$output_file" -localization "$l10n_dir"
+          env -u DISPLAY -u WAYLAND_DISPLAY java -Djava.awt.headless=true -cp "$cp" com.codename1.designer.css.CN1CSSCLI \
+            -input "$css_file" -output "$output_file" -localization "$l10n_dir"
           test -s "$output_file"
 
-      - name: Verify native-themes CEF-free build
+      - name: Verify native-themes build
         run: |
           cd maven
-          bash $GITHUB_WORKSPACE/scripts/ci/retry.sh mvn -B -pl css-compiler -am install -DskipTests -Dmaven.javadoc.skip=true -Plocal-dev-javase
+          bash $GITHUB_WORKSPACE/scripts/ci/retry.sh mvn -B -pl css-cli -am install -DskipTests -Dmaven.javadoc.skip=true -Plocal-dev-javase
           cd ..
           ./scripts/build-native-themes.sh
           test -f Themes/iOSModernTheme.res || { echo "missing Themes/iOSModernTheme.res"; exit 1; }

.github/workflows/developer-guide-docs.yml

@@ -36,12 +36,13 @@ on:
       # The themed figures are rendered against the compiled native themes, so
       # what those themes look like is an input to this guide exactly the way the
       # build hint sources above are. build-native-themes.sh compiles
-      # native-themes/<name>/theme.css with maven/css-compiler, so a change to
-      # any of the three changes the pictures without touching docs/ at all --
-      # and the committed figures would then go stale silently until some later
-      # run failed against them.
+      # native-themes/<name>/theme.css with maven/css-compiler through its
+      # command line in maven/css-cli, so a change to any of them changes the
+      # pictures without touching docs/ at all -- and the committed figures
+      # would then go stale silently until some later run failed against them.
       - 'native-themes/**'
       - 'maven/css-compiler/**'
+      - 'maven/css-cli/**'
       - 'scripts/build-native-themes.sh'
       # The figures are rendered by the framework itself, so a change to how a
       # component paints, how a layout measures, or how the JavaSE port
@@ -109,6 +110,7 @@ jobs:
               # comparison step is gated on this filter too.
               - 'native-themes/**'
               - 'maven/css-compiler/**'
+              - 'maven/css-cli/**'
               - 'scripts/build-native-themes.sh'
               # Same reason, and the same two-lists rule: the figure comparison
               # step is gated on this filter as well as on the trigger.
@@ -167,7 +169,9 @@ jobs:
           mkdir -p "$HOME/.codenameone"
           touch "$HOME/.codenameone/guibuilder.jar"
           cp maven/CodeNameOneBuildClient.jar "$HOME/.codenameone/CodeNameOneBuildClient.jar"
-          xvfb-run -a mvn -B -ntp -Dgenerate-gui-sources-done=true -Dcodename1.platform=javase -f docs/demos/pom.xml process-classes
+          # No virtual display: process-classes compiles each demo's CSS, which
+          # is headless. The screenshot generator below is the step that needs one.
+          mvn -B -ntp -Dgenerate-gui-sources-done=true -Dcodename1.platform=javase -f docs/demos/pom.xml process-classes
 
       - name: Install demo common module for screenshot generation
         if: github.event_name != 'pull_request' || steps.changes.outputs.docs == 'true' || steps.changes.outputs.demos == 'true' || steps.changes.outputs.workflow == 'true'

.github/workflows/gradle-smoke.yml

@@ -31,6 +31,8 @@ on:
       - 'maven/codenameone-gradle-plugin/**'
       - 'maven/codenameone-gradle-plugin-marker/**'
       - 'maven/codenameone-maven-plugin/**'
+      - 'maven/css-compiler/**'
+      - 'maven/css-cli/**'
       - 'maven/build-engine/**'
       - 'maven/project-model/**'
       - 'maven/cn1app-archetype/**'
@@ -53,6 +55,8 @@ on:
       - 'maven/codenameone-gradle-plugin/**'
       - 'maven/codenameone-gradle-plugin-marker/**'
       - 'maven/codenameone-maven-plugin/**'
+      - 'maven/css-compiler/**'
+      - 'maven/css-cli/**'
       - 'maven/build-engine/**'
       - 'maven/project-model/**'
       - 'maven/cn1app-archetype/**'
@@ -108,9 +112,12 @@ jobs:
           java-version: '8'
           distribution: 'temurin'
           cache: 'maven'
-      # xvfb for the CSS compiler, which opens an AWT frame. clang and the
-      # libraries the generated backend links (see archetype-smoke.yml) for
-      # backendPackage, which the backend-only test otherwise skips.
+      # xvfb for the steps that run cn1Test in the simulator's runner or open
+      # a desktop tool. Building a project, compiling its CSS included, needs
+      # no display, so no build-only step below is wrapped in xvfb-run and
+      # none should be. clang and the libraries the generated backend links
+      # (see archetype-smoke.yml) for backendPackage, which the backend-only
+      # test otherwise skips.
       - name: Install xvfb and the native backend toolchain
         run: |
           bash scripts/ci/apt-get-install.sh xvfb clang \
@@ -122,21 +129,26 @@ jobs:
           RETRY_DELAY_SECONDS: '60'
         run: |
           cd maven
-          bash ../scripts/ci/retry.sh xvfb-run -a mvn install -Plocal-dev-javase -DskipTests -Darchetype.test.skip=true -Dmaven.javadoc.skip=true
+          bash ../scripts/ci/retry.sh mvn install -Plocal-dev-javase -DskipTests -Darchetype.test.skip=true -Dmaven.javadoc.skip=true
       - name: Refresh archetype catalog
         run: |
           cd maven
-          xvfb-run -a mvn archetype:update-local-catalog -Plocal-dev-javase
-          xvfb-run -a mvn archetype:crawl -Plocal-dev-javase
+          mvn archetype:update-local-catalog -Plocal-dev-javase
+          mvn archetype:crawl -Plocal-dev-javase
       - name: Gradle application
         working-directory: maven/integration-tests
         run: xvfb-run -a bash gradle-app-test.sh
       - name: Maven and Gradle upload parity
         working-directory: maven/integration-tests
-        run: xvfb-run -a bash gradle-maven-parity-test.sh
+        run: bash gradle-maven-parity-test.sh
       - name: Gradle cn1lib, consumed by Gradle and Maven
         working-directory: maven/integration-tests
-        run: xvfb-run -a bash gradle-cn1lib-test.sh
+        # DISPLAY and WAYLAND_DISPLAY are cleared on purpose, and this must
+        # never be wrapped in xvfb-run: the script runs cn1Css and stages
+        # Android and iOS builds for several Gradle apps without starting the
+        # simulator, so passing here proves the Gradle CSS compile needs no
+        # display. archetype-smoke.yml holds the same guard for Maven.
+        run: env -u DISPLAY -u WAYLAND_DISPLAY bash gradle-cn1lib-test.sh
       - name: Migration to Gradle
         working-directory: maven/integration-tests
         run: xvfb-run -a bash gradle-migrate-test.sh
@@ -145,13 +157,13 @@ jobs:
         env:
           # A skip reads like a pass; this runner has clang.
           CN1_BACKEND_PACKAGE_REQUIRED: '1'
-        run: xvfb-run -a bash gradle-initializr-test.sh
+        run: bash gradle-initializr-test.sh
       # The desktop tools are separate Maven projects under scripts/; Settings
       # stands in for all four, which start through the same launcher.
       - name: Build Codename One Settings
         working-directory: scripts/settings
-        # Its own CSS compile opens an AWT frame, so it needs a display too.
-        run: JAVA_HOME="$GRADLE_JAVA_HOME" xvfb-run -a mvn -B -ntp install -DskipTests -Pexecutable-jar -Dcodename1.platform=javase
+        # Build only, tests skipped: nothing here opens a window.
+        run: JAVA_HOME="$GRADLE_JAVA_HOME" mvn -B -ntp install -DskipTests -Pexecutable-jar -Dcodename1.platform=javase
       - name: Desktop tools launch from Maven and Gradle
         working-directory: maven/integration-tests
         env:

.github/workflows/guibuilder.yml

@@ -23,6 +23,7 @@ on:
       - 'CodenameOne/src/**'
       - 'Ports/JavaSE/src/**'
       - 'maven/css-compiler/**'
+      - 'maven/css-cli/**'
       - 'maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/**'
       - 'maven/build-engine/src/main/java/com/codename1/maven/**'
   push:
@@ -40,6 +41,7 @@ on:
       - 'CodenameOne/src/**'
       - 'Ports/JavaSE/src/**'
       - 'maven/css-compiler/**'
+      - 'maven/css-cli/**'
       - 'maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/**'
       - 'maven/build-engine/src/main/java/com/codename1/maven/**'
 

.github/workflows/linux-build-run.yml

@@ -100,13 +100,9 @@ jobs:
       - name: Check out repository
         uses: actions/checkout@v6
 
-      - name: Install Xvfb
-        run: |
-          set -e
-          # The CN1 CSS compiler renders via CEF/AWT and throws HeadlessException
-          # without a display, so the common build runs under a virtual X server.
-          bash scripts/ci/apt-get-install.sh xvfb
-
+      # No virtual display in this job: it only builds, and the css goal the
+      # common build runs compiles theme.css headless. The jobs that run the
+      # app start their own Xvfb.
       - name: Set up JDK 8
         uses: actions/setup-java@v5
         with: { distribution: 'temurin', java-version: '8' }
@@ -134,9 +130,6 @@ jobs:
         run: |
           set -e
           export JAVA_HOME="$JDK_17_HOME"
-          Xvfb :99 -screen 0 1600x1200x24 >/tmp/xvfb-build.log 2>&1 &
-          export DISPLAY=:99
-          sleep 2
           mkdir -p "$HOME/.codenameone"
           [ -f "$HOME/.codenameone/guibuilder.jar" ] || : > "$HOME/.codenameone/guibuilder.jar"
           bash scripts/ci/retry.sh \

.github/workflows/native-themes-sync.yml

@@ -19,6 +19,7 @@ on:
       - 'scripts/ci/retry.sh'
       - 'native-themes/**'
       - 'maven/css-compiler/**'
+      - 'maven/css-cli/**'
       - 'scripts/build-native-themes.sh'
       - '.github/workflows/native-themes-sync.yml'
 
@@ -60,10 +61,10 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-m2
 
-      - name: Build css-compiler
+      - name: Build the CSS compiler CLI
         run: |
           cd maven
-          bash $GITHUB_WORKSPACE/scripts/ci/retry.sh mvn -B -pl css-compiler -am install -DskipTests -Dmaven.javadoc.skip=true -Plocal-dev-javase
+          bash $GITHUB_WORKSPACE/scripts/ci/retry.sh mvn -B -pl css-cli -am install -DskipTests -Dmaven.javadoc.skip=true -Plocal-dev-javase
 
       - name: Rebuild native themes
         env:

.github/workflows/port-status-nightly.yml

@@ -49,12 +49,10 @@ jobs:
           distribution: temurin
           java-version: '17'
           cache: maven
-      - name: Install Xvfb
-        run: bash scripts/ci/apt-get-install.sh xvfb
       - name: Set up workspace
-        run: xvfb-run ./scripts/setup-workspace.sh -q -DskipTests
+        run: ./scripts/setup-workspace.sh -q -DskipTests
       - name: Build compliance application for JavaScript
-        run: SKIP_PARPARVM_BUILD=1 xvfb-run ./scripts/build-javascript-port-hellocodenameone.sh "${GITHUB_WORKSPACE}/hellocodenameone-javascript-port.zip"
+        run: SKIP_PARPARVM_BUILD=1 ./scripts/build-javascript-port-hellocodenameone.sh "${GITHUB_WORKSPACE}/hellocodenameone-javascript-port.zip"
       - uses: actions/upload-artifact@v4
         with:
           name: nightly-javascript-app