Antora documentation build fails on Windows; arguments not properly passed to `gradlew`

[Marcono1234]

Describe the bug Building the documentation using Antora with ./gradlew :spring-security-docs:antora fails on Windows:

./gradlew :spring-security-docs:antora

> Task :spring-security-docs:antora FAILED
[02:11:39.247] FATAL (antora): (@antora/collector-extension): Command failed with exit code 1: C:\WINDOWS\system32\cmd.exe /d /s /c "gradlew.bat -q -PbuildSrc.skipTests=true -Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError :spring-security-docs:generateAntoraYml" in <redacted>\spring-security (branch: main <worktree> | start path: docs)

Unknown command-line option '-X'.

USAGE: gradlew [option...] [task...]

-?, -h, --help                     Shows this help message.
-a, --no-rebuild                   Do not rebuild project dependencies.
[... Gradle help output ...]


    Cause: Error
        at ChildProcess.<anonymous> (<redacted>\spring-security\docs\node_modules\@antora\collector-extension\lib\util\run-command.js:112:16)
        at ChildProcess.emit (node:events:519:28)
        at maybeClose (node:internal/child_process:1105:16)
        at ChildProcess._handle.onexit (node:internal/child_process:305:5)

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':spring-security-docs:antora'.
> Process 'command '<redacted>\spring-security\docs\.gradle\nodejs\node-v20.15.0-win-x64\npx.cmd'' finished with non-zero exit value 1

Setup:

• Windows 10
• PowerShell 7.4.2

To Reproduce On Windows:

1. Clone the main branch of this repository
2. Run

   ./gradlew :spring-security-docs:antora
   

Expected behavior The build should succeed

Potential cause and workaround This error seems to be related to the command value in the docs/antora.yml file. Based on the error message printed to console, it seems " around the JVM args got lost, and therefore Gradle considered -XX:+HeapDumpOnOutOfMemoryError to be an argument to Gradle itself and not the JVM.

Workaround: Edit the docs/antora.yml file and remove "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError".

[Marcono1234]

Note that this is not blocking for me, since there exists a workaround as described above, and I only needed it for testing the documentation changes in #15325.

Though maybe if possible it would be good nonetheless to solve this, to avoid issues for new contributors.

[jzheaux]

Thanks, @Marcono1234, for the report. I don't have a WIndows machine to test, though I agree that we want contributors that use Windows to be able to update the documentation. Could you do me a favor to get a quick theory out of the way?

Change

command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-security-docs:generateAntoraYml

to

command: gradlew -q -PbuildSrc.skipTests=true -Dorg.gradle.jvmargs="-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-security-docs:generateAntoraYml

and then try again.

Otherwise, given that this file uses standard Antora properties, it seems more likely that this is a bug in Antora. It may be best to reach out to the Antora community and file a ticket there.

[Marcono1234]

Thanks for the suggestion! Unfortunately it looks like your proposed change did not help. I have created an issue in the Antora project: https://gitlab.com/antora/antora-collector-extension/-/issues/18

Do you want to keep this issue here open until this is resolved in some way and the documentation build for this Spring project works on Windows?

[Marcono1234]

The maintainer has closed the Antora issue saying that they cannot fix this / don't want to spend more time on this at the moment.

Do you think it would be possible to change the command here in this Spring project in some way to work on Windows too? The Antora maintainer also suggested https://chat.antora.org/ for help.

Or if not, maybe it would at least be useful to mention in the README here that the command might not work on Windows. What do you think?