system_allow_fail ';' STRING ( ';' STRING )?

Summary

The system-allow-fail macro executes an operating system command and returns its output, but unlike ${system}, it does not fail the build if the command returns a non-zero exit code. Failed commands generate a warning instead.

Syntax

${system-allow-fail;<command>[;<input>]}

Parameters

• command - The system command to execute
• input (optional) - Text to send to the command’s standard input

Behavior

• Executes the command in the project base directory
• On Windows, automatically wraps command with cmd /c
• Captures and returns standard output (trimmed)
• If input is provided, writes it to stdin
• Returns empty string if command fails (no build error)
• Generates warning (not error) on non-zero exit codes
• Build continues even on command failure

Examples

Try to get Git info (may not be in repo):

Git-Branch: ${system-allow-fail;git branch --show-current}

Optional version check:

tool.version=${system-allow-fail;tool --version}

Check for optional tool:

${if;${system-allow-fail;which docker};docker-available;docker-not-found}

Get info with fallback:

host=${def;${system-allow-fail;hostname};unknown-host}

Use Cases

• Running commands that may not be available
• Optional build information gathering
• Checking for tool availability
• Platform-specific commands that may fail
• Best-effort information collection
• Graceful degradation in builds

Notes

• Does not fail the build on command errors
• Returns empty string on failure
• Generates warning (visible in logs) on failure
• Same execution model as ${system}
• Useful when command availability is uncertain
• See also: ${system} for failing variant
• May be disabled in restricted execution modes

TODO Needs review - AI Generated content

See test cases in MacroTestsForDocsExamples.java