From ab8a0526b99c85df89e4a672f0390f358c6bc9ef Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sat, 5 Sep 2026 06:45:13 +0000
Subject: [PATCH 1/3] feat: fall back to -D system properties for compiler
 options (#275)

Co-Authored-By: Andreas Igel <andreas.igel@computacenter.com>
---
 docs/CONFIGURATION.md                         |  9 +++-
 docs/DEBUG_LOGGING.md                         |  4 +-
 .../processing/CompilerArgumentsReader.java   | 11 ++++-
 .../CompilerArgumentsReaderTest.java          | 41 +++++++++++++++++++
 4 files changed, 61 insertions(+), 4 deletions(-)

diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index e6f11926..f36262ff 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -12,6 +12,7 @@ Simple-builders supports fine-grained configuration through the `@SimpleBuilder.
   - [Maven Configuration](#maven-configuration)
   - [Gradle Configuration](#gradle-configuration)
   - [IntelliJ IDEA Configuration](#intellij-idea-configuration)
+  - [Command Line (Maven -D)](#command-line-maven--d)
 - [Configuration Options](#configuration-options)
   - [Field Setter Generation](#field-setter-generation)
   - [Conditional Logic](#conditional-logic)
@@ -221,6 +222,12 @@ compileJava {
    -Asimplebuilder.generateFieldSupplier=true -Asimplebuilder.builderAccess=PUBLIC
    ```
 
+### Command Line (Maven -D)
+
+Maven supports compiler options without a `pom.xml` change, for example: `mvn compile -Dsimplebuilder.generateJavaDoc=DISABLED`.
+The precedence is `@SimpleBuilder.Options` > `-A` compiler argument > `-D` system property > default.
+This relies on javac running inside the Maven JVM (the default); use the `-A` form for Gradle, IDE builds, and forked compilation.
+
 ## Configuration Options
 
 All options use `OptionState` enum with values: `ENABLED`, `DISABLED`, or `UNSET` (uses default/compiler arg).
@@ -1264,7 +1271,7 @@ Or in compiler options:
 
 ### Compiler Options Not Working
 
-1. **Check option names**: Ensure you're using the full option name (e.g., `-Asimplebuilder.generateFieldSupplier`)
+1. **Check option names**: Ensure you're using the full option name (e.g., `-Asimplebuilder.generateFieldSupplier`); Maven also supports the `-Dsimplebuilder.<option>` fallback
 2. **Verify processor is running**: Ensure annotation processor is configured correctly
 3. **Check IDE configuration**: Some IDEs need special configuration for compiler options
 4. **Clean and rebuild**: Run `mvn clean compile` to ensure fresh build
diff --git a/docs/DEBUG_LOGGING.md b/docs/DEBUG_LOGGING.md
index c4023aeb..cffaf980 100644
--- a/docs/DEBUG_LOGGING.md
+++ b/docs/DEBUG_LOGGING.md
@@ -11,7 +11,9 @@ The Simple Builders annotation processor supports conditional debug logging that
 
 ## Enabling Debug Logging
 
-Debug logging uses `Diagnostic.Kind.OTHER` but is only activated when explicitly enabled via the compiler argument `-Averbose=true`.
+Debug logging uses `Diagnostic.Kind.OTHER` but is only activated when explicitly enabled via the compiler argument `-Averbose=true` or the Maven system property `-Dsimplebuilder.verbose=true`.
+
+When Maven runs javac in-process, `mvn clean compile -Dsimplebuilder.verbose=true` works without an `-Averbose=${simplebuilder.verbose}` mapping in `pom.xml`. The `-A` mapping remains the option for Gradle, IDEs, and forked compilation.
 
 ### Option 1: Via Maven Property (Recommended)
 
diff --git a/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java b/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java
index 5edf99fa..7ce1a0fe 100644
--- a/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java
+++ b/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java
@@ -52,8 +52,10 @@ public CompilerArgumentsReader(ProcessingEnvironment processingEnv) {
   /**
    * Reads the value of a compiler argument.
    *
-   * <p>The method looks up the compiler argument using both the full compiler argument name (with
-   * prefix) and the simple option name (without prefix) for backward compatibility.
+   * <p>The method checks the prefixed compiler argument first, then the bare option name for
+   * backward compatibility, and finally the prefixed JVM system property. The system property
+   * fallback is available when Maven runs javac in-process and is not available with {@code
+   * <fork>true</fork>}.
    *
    * @param argument the compiler argument enum to read
    * @return the value of the compiler argument, or null if not set
@@ -67,6 +69,10 @@ public String readValue(CompilerArgumentsEnum argument) {
       value = processingEnv.getOptions().get(argument.getOptionName());
     }
 
+    if (value == null) {
+      value = System.getProperty(argument.getCompilerArgument());
+    }
+
     return value;
   }
 
@@ -130,6 +136,7 @@ public AccessModifier readAccessModifier(CompilerArgumentsEnum argument) {
    *
    * <ul>
    *   <li>{@code -Asimplebuilder.generateFieldSupplier=true}
+   *   <li>{@code -Dsimplebuilder.generateFieldSupplier=true} as a system-property alternative
    *   <li>{@code -Asimplebuilder.builderAccess=public}
    *   <li>etc.
    * </ul>
diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/CompilerArgumentsReaderTest.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/CompilerArgumentsReaderTest.java
index c8b4c11f..6dd0c53b 100644
--- a/processor/src/test/java/org/javahelpers/simple/builders/processor/CompilerArgumentsReaderTest.java
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/CompilerArgumentsReaderTest.java
@@ -89,6 +89,47 @@ void readValue_OnlySimpleNameSet_UsesSimpleName() {
         "Should fall back to simple option name");
   }
 
+  @Test
+  void readValue_SystemPropertySet_FallsBackToSystemProperty() {
+    System.setProperty("simplebuilder.verbose", "true");
+    try {
+      ProcessingEnvironment env = ProcessingEnvironmentStub.createEmpty();
+      CompilerArgumentsReader reader = new CompilerArgumentsReader(env);
+
+      assertEquals("true", reader.readValue(CompilerArgumentsEnum.VERBOSE));
+      assertTrue(reader.readBooleanValue(CompilerArgumentsEnum.VERBOSE));
+    } finally {
+      System.clearProperty("simplebuilder.verbose");
+    }
+  }
+
+  @Test
+  void readValue_CompilerArgAndSystemPropertySet_PrefersCompilerArg() {
+    System.setProperty("simplebuilder.verbose", "true");
+    try {
+      ProcessingEnvironment env =
+          ProcessingEnvironmentStub.builder().put("simplebuilder.verbose", "false").build();
+      CompilerArgumentsReader reader = new CompilerArgumentsReader(env);
+
+      assertEquals("false", reader.readValue(CompilerArgumentsEnum.VERBOSE));
+    } finally {
+      System.clearProperty("simplebuilder.verbose");
+    }
+  }
+
+  @Test
+  void readValue_BareNameSystemProperty_Ignored() {
+    System.setProperty("verbose", "true");
+    try {
+      ProcessingEnvironment env = ProcessingEnvironmentStub.createEmpty();
+      CompilerArgumentsReader reader = new CompilerArgumentsReader(env);
+
+      assertNull(reader.readValue(CompilerArgumentsEnum.VERBOSE));
+    } finally {
+      System.clearProperty("verbose");
+    }
+  }
+
   /** Test: readBooleanValue returns false when value is null. */
   @Test
   void readBooleanValue_NullValue_ReturnsFalse() {

From e30c85958adf07acbe340ee54e220a9f95cea041 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sat, 5 Sep 2026 15:25:44 +0000
Subject: [PATCH 2/3] fix: let -D system property override -A compiler
 arguments (#275)

Co-Authored-By: Andreas Igel <andreas.igel@computacenter.com>
---
 docs/CONFIGURATION.md                         |  9 +++++----
 docs/DEBUG_LOGGING.md                         |  2 +-
 .../processing/CompilerArgumentsReader.java   | 20 ++++++++++---------
 .../CompilerArgumentsReaderTest.java          |  4 ++--
 4 files changed, 19 insertions(+), 16 deletions(-)

diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index f36262ff..7ac8e80e 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -12,7 +12,7 @@ Simple-builders supports fine-grained configuration through the `@SimpleBuilder.
   - [Maven Configuration](#maven-configuration)
   - [Gradle Configuration](#gradle-configuration)
   - [IntelliJ IDEA Configuration](#intellij-idea-configuration)
-  - [Command Line (Maven -D)](#command-line-maven--d)
+  - [Command Line (-D)](#command-line--d)
 - [Configuration Options](#configuration-options)
   - [Field Setter Generation](#field-setter-generation)
   - [Conditional Logic](#conditional-logic)
@@ -222,11 +222,12 @@ compileJava {
    -Asimplebuilder.generateFieldSupplier=true -Asimplebuilder.builderAccess=PUBLIC
    ```
 
-### Command Line (Maven -D)
+### Command Line (-D)
 
 Maven supports compiler options without a `pom.xml` change, for example: `mvn compile -Dsimplebuilder.generateJavaDoc=DISABLED`.
-The precedence is `@SimpleBuilder.Options` > `-A` compiler argument > `-D` system property > default.
-This relies on javac running inside the Maven JVM (the default); use the `-A` form for Gradle, IDE builds, and forked compilation.
+The precedence is `@SimpleBuilder.Options` > `-D` system property > `-A` compiler argument > default.
+The system property wins so you can override options configured in the build file from the command line without editing it.
+This relies on javac running in the build tool's JVM (the default for Maven and Gradle); use the `-A` form for forked compilation (`<fork>true</fork>` / `options.fork = true`) and IDE builds. Gradle also accepts `systemProp.simplebuilder.<option>=...` in `gradle.properties`; note that Gradle does not track the property as a task input, so run `clean` or `--rerun-tasks` after changing it.
 
 ## Configuration Options
 
diff --git a/docs/DEBUG_LOGGING.md b/docs/DEBUG_LOGGING.md
index cffaf980..6ceec929 100644
--- a/docs/DEBUG_LOGGING.md
+++ b/docs/DEBUG_LOGGING.md
@@ -13,7 +13,7 @@ The Simple Builders annotation processor supports conditional debug logging that
 
 Debug logging uses `Diagnostic.Kind.OTHER` but is only activated when explicitly enabled via the compiler argument `-Averbose=true` or the Maven system property `-Dsimplebuilder.verbose=true`.
 
-When Maven runs javac in-process, `mvn clean compile -Dsimplebuilder.verbose=true` works without an `-Averbose=${simplebuilder.verbose}` mapping in `pom.xml`. The `-A` mapping remains the option for Gradle, IDEs, and forked compilation.
+When Maven runs javac in-process, `mvn clean compile -Dsimplebuilder.verbose=true` works without an `-Averbose=${simplebuilder.verbose}` mapping in `pom.xml`, and the `-D` value overrides any `-A` mapping from the build file. Gradle also supports `-Dsimplebuilder.verbose=true` (or `systemProp.simplebuilder.verbose=true` in `gradle.properties`) with in-process compilation; use the `-A` mapping for forked compilation and IDE builds. Gradle does not track the property as a task input, so run `clean` or `--rerun-tasks` after changing it.
 
 ### Option 1: Via Maven Property (Recommended)
 
diff --git a/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java b/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java
index 7ce1a0fe..5f84e4c3 100644
--- a/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java
+++ b/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java
@@ -52,25 +52,27 @@ public CompilerArgumentsReader(ProcessingEnvironment processingEnv) {
   /**
    * Reads the value of a compiler argument.
    *
-   * <p>The method checks the prefixed compiler argument first, then the bare option name for
-   * backward compatibility, and finally the prefixed JVM system property. The system property
-   * fallback is available when Maven runs javac in-process and is not available with {@code
-   * <fork>true</fork>}.
+   * <p>The method checks the prefixed JVM system property first, then the prefixed compiler
+   * argument, and finally the bare option name for backward compatibility. The system property wins
+   * so a command-line {@code -D} can override options configured in the build file. The system
+   * property is available when the build tool runs javac in-process and is not available with
+   * {@code <fork>true</fork>}.
    *
    * @param argument the compiler argument enum to read
    * @return the value of the compiler argument, or null if not set
    */
   public String readValue(CompilerArgumentsEnum argument) {
-    // Try with full compiler argument name first (e.g., "simplebuilder.verbose")
-    String value = processingEnv.getOptions().get(argument.getCompilerArgument());
+    // Try the prefixed JVM system property first (e.g., "simplebuilder.verbose")
+    String value = System.getProperty(argument.getCompilerArgument());
 
-    // Fall back to simple option name for backward compatibility (e.g., "verbose")
+    // Fall back to the full compiler argument name (e.g., "simplebuilder.verbose")
     if (value == null) {
-      value = processingEnv.getOptions().get(argument.getOptionName());
+      value = processingEnv.getOptions().get(argument.getCompilerArgument());
     }
 
+    // Finally, fall back to the simple option name for backward compatibility (e.g., "verbose")
     if (value == null) {
-      value = System.getProperty(argument.getCompilerArgument());
+      value = processingEnv.getOptions().get(argument.getOptionName());
     }
 
     return value;
diff --git a/processor/src/test/java/org/javahelpers/simple/builders/processor/CompilerArgumentsReaderTest.java b/processor/src/test/java/org/javahelpers/simple/builders/processor/CompilerArgumentsReaderTest.java
index 6dd0c53b..d96c25fa 100644
--- a/processor/src/test/java/org/javahelpers/simple/builders/processor/CompilerArgumentsReaderTest.java
+++ b/processor/src/test/java/org/javahelpers/simple/builders/processor/CompilerArgumentsReaderTest.java
@@ -104,14 +104,14 @@ void readValue_SystemPropertySet_FallsBackToSystemProperty() {
   }
 
   @Test
-  void readValue_CompilerArgAndSystemPropertySet_PrefersCompilerArg() {
+  void readValue_CompilerArgAndSystemPropertySet_PrefersSystemProperty() {
     System.setProperty("simplebuilder.verbose", "true");
     try {
       ProcessingEnvironment env =
           ProcessingEnvironmentStub.builder().put("simplebuilder.verbose", "false").build();
       CompilerArgumentsReader reader = new CompilerArgumentsReader(env);
 
-      assertEquals("false", reader.readValue(CompilerArgumentsEnum.VERBOSE));
+      assertEquals("true", reader.readValue(CompilerArgumentsEnum.VERBOSE));
     } finally {
       System.clearProperty("simplebuilder.verbose");
     }

From 9f012cd612222172540936c7f1a9cb2c4c336b52 Mon Sep 17 00:00:00 2001
From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Date: Sun, 6 Sep 2026 08:13:00 +0000
Subject: [PATCH 3/3] docs: clarify -D option wording (#275)

Co-Authored-By: Andreas Igel <andreas.igel@computacenter.com>
---
 docs/CONFIGURATION.md                            |  4 ++--
 .../processing/CompilerArgumentsReader.java      | 16 +++++++++++-----
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 7ac8e80e..cba0f1c5 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -224,7 +224,7 @@ compileJava {
 
 ### Command Line (-D)
 
-Maven supports compiler options without a `pom.xml` change, for example: `mvn compile -Dsimplebuilder.generateJavaDoc=DISABLED`.
+Maven and Gradle accept the options as JVM system properties without a build-file change, for example `mvn compile -Dsimplebuilder.generateJavaDoc=DISABLED` or `gradle compileJava -Dsimplebuilder.generateJavaDoc=DISABLED`.
 The precedence is `@SimpleBuilder.Options` > `-D` system property > `-A` compiler argument > default.
 The system property wins so you can override options configured in the build file from the command line without editing it.
 This relies on javac running in the build tool's JVM (the default for Maven and Gradle); use the `-A` form for forked compilation (`<fork>true</fork>` / `options.fork = true`) and IDE builds. Gradle also accepts `systemProp.simplebuilder.<option>=...` in `gradle.properties`; note that Gradle does not track the property as a task input, so run `clean` or `--rerun-tasks` after changing it.
@@ -1272,7 +1272,7 @@ Or in compiler options:
 
 ### Compiler Options Not Working
 
-1. **Check option names**: Ensure you're using the full option name (e.g., `-Asimplebuilder.generateFieldSupplier`); Maven also supports the `-Dsimplebuilder.<option>` fallback
+1. **Check option names**: Ensure you're using the full option name (e.g., `-Asimplebuilder.generateFieldSupplier`); the same name also works as a JVM system property (`-Dsimplebuilder.<option>`), which takes precedence over `-A`
 2. **Verify processor is running**: Ensure annotation processor is configured correctly
 3. **Check IDE configuration**: Some IDEs need special configuration for compiler options
 4. **Clean and rebuild**: Run `mvn clean compile` to ensure fresh build
diff --git a/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java b/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java
index 5f84e4c3..a34ef3cf 100644
--- a/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java
+++ b/processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java
@@ -62,15 +62,15 @@ public CompilerArgumentsReader(ProcessingEnvironment processingEnv) {
    * @return the value of the compiler argument, or null if not set
    */
   public String readValue(CompilerArgumentsEnum argument) {
-    // Try the prefixed JVM system property first (e.g., "simplebuilder.verbose")
+    // Try the -D JVM system property first (e.g., -Dsimplebuilder.verbose)
     String value = System.getProperty(argument.getCompilerArgument());
 
-    // Fall back to the full compiler argument name (e.g., "simplebuilder.verbose")
+    // Then the -A compiler argument (e.g., -Asimplebuilder.verbose)
     if (value == null) {
       value = processingEnv.getOptions().get(argument.getCompilerArgument());
     }
 
-    // Finally, fall back to the simple option name for backward compatibility (e.g., "verbose")
+    // Finally the bare option name for backward compatibility (e.g., -Averbose)
     if (value == null) {
       value = processingEnv.getOptions().get(argument.getOptionName());
     }
@@ -137,12 +137,18 @@ public AccessModifier readAccessModifier(CompilerArgumentsEnum argument) {
    * <p>This method reads all configuration options from compiler arguments like:
    *
    * <ul>
-   *   <li>{@code -Asimplebuilder.generateFieldSupplier=true}
-   *   <li>{@code -Dsimplebuilder.generateFieldSupplier=true} as a system-property alternative
+   *   <li>{@code -Dsimplebuilder.generateFieldSupplier=true} (JVM system property, highest
+   *       precedence)
+   *   <li>{@code -Asimplebuilder.generateFieldSupplier=true} (compiler argument)
+   *   <li>{@code -AgenerateFieldSupplier=true} (bare option name, backward compatibility)
    *   <li>{@code -Asimplebuilder.builderAccess=public}
    *   <li>etc.
    * </ul>
    *
+   * <p>Options set via {@code @SimpleBuilder.Options} on the annotated type are not handled here;
+   * they are read by {@link BuilderConfigurationReader} and merged on top of this global
+   * configuration.
+   *
    * <p>All values default to UNSET or DEFAULT if not specified in compiler arguments.
    *
    * <p><b>Adding a new option:</b> every option in {@link CompilerArgumentsEnum} that represents a