Skip to content

docs: the PowerShell commands run as written - #506

Merged
DemchaAV merged 1 commit into
developfrom
docs/examples-readme-powershell
Aug 4, 2026
Merged

docs: the PowerShell commands run as written#506
DemchaAV merged 1 commit into
developfrom
docs/examples-readme-powershell

Conversation

@DemchaAV

@DemchaAV DemchaAV commented Aug 4, 2026

Copy link
Copy Markdown
Owner

Why

Two pages hand Windows readers a command that fails.

PowerShell splits a -D flag whose property name contains a dot. Probed directly:

python -c "import sys; print(sys.argv[1:])" -Dmdep.outputFile=x -DincludeScope=test -Dexec.mainClass=Foo
['-Dmdep', '.outputFile=x', '-DincludeScope=test', '-Dexec', '.mainClass=Foo']

Maven then rejects the fragment with Unknown lifecycle phase ".mainClass=…". A flag
without a dot before the = survives, which is why this is easy to miss.

examples/README.md also told readers "The same mvnw.cmd form works on Windows
PowerShell with backslash paths."
It does not. The bash block above it ends a line with
\, which PowerShell has no notion of — it runs ./mvnw alone and then looks for a
command named -Dexec.mainClass=…. And the backslash-paths advice pointed at a
non-problem: forward slashes work fine in -f.

docs/operations/benchmarks.md quotes the flags on its java lines and missed the one
on its mvnw line, so the page half-knew.

What

  • examples/README.md: replaces the false claim with the PowerShell command, one line,
    flag quoted, and says what goes wrong without each change.
  • docs/operations/benchmarks.md: quotes -Dmdep.outputFile=… and states the rule,
    pointing at the java lines below that already follow it.

Tests

Every command in the diff was run on this machine's PowerShell, before and after:

Command As documented Fixed
examples/README.md run-one-example BUILD FAILURE, Unknown lifecycle phase ".mainClass=…" PS_EXIT=0, wrote module-first-profile.pdf
benchmarks.md build-classpath BUILD FAILURE BUILD SUCCESS, wrote benchmarks/target/benchmark.classpath

./mvnw -B -ntp clean verifyBUILD SUCCESS.

Both pages gave Windows readers a command that fails. PowerShell splits a -D flag
whose property name contains a dot: it hands the native command -Dexec and
.mainClass=... as two arguments, and Maven rejects the second with "Unknown
lifecycle phase". Quoting the flag fixes it.

examples/README.md also claimed the bash form works unchanged on PowerShell. It
cannot: the trailing backslash is a continuation PowerShell does not have, so the
command runs as two, and the advice about backslash paths was beside the point —
forward slashes work fine in -f.

benchmarks.md already quoted the flags on its java lines and missed the one on its
mvnw line, so the page half-knew.
@DemchaAV
DemchaAV force-pushed the docs/examples-readme-powershell branch from 8decdfd to 6c8b143 Compare August 4, 2026 15:03
@DemchaAV
DemchaAV merged commit 33731d4 into develop Aug 4, 2026
10 checks passed
@DemchaAV
DemchaAV deleted the docs/examples-readme-powershell branch August 4, 2026 15:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant