Support -D system properties for compiler options (#275)

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 (-D)](#command-line--d)
 - [Configuration Options](#configuration-options)
   - [Field Setter Generation](#field-setter-generation)
   - [Conditional Logic](#conditional-logic)
@@ -221,6 +222,13 @@ compileJava {
    -Asimplebuilder.generateFieldSupplier=true -Asimplebuilder.builderAccess=PUBLIC
    ```
 
+### Command Line (-D)
+
+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.
+
 ## Configuration Options
 
 All options use `OptionState` enum with values: `ENABLED`, `DISABLED`, or `UNSET` (uses default/compiler arg).
@@ -1264,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`)
+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

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`, 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)
 

processor/src/main/java/org/javahelpers/simple/builders/processor/processing/CompilerArgumentsReader.java

@@ -52,17 +52,25 @@ 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 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 -D JVM system property first (e.g., -Dsimplebuilder.verbose)
+    String value = System.getProperty(argument.getCompilerArgument());
 
-    // Fall back to simple option name for backward compatibility (e.g., "verbose")
+    // Then the -A compiler argument (e.g., -Asimplebuilder.verbose)
+    if (value == null) {
+      value = processingEnv.getOptions().get(argument.getCompilerArgument());
+    }
+
+    // Finally the bare option name for backward compatibility (e.g., -Averbose)
     if (value == null) {
       value = processingEnv.getOptions().get(argument.getOptionName());
     }
@@ -129,11 +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} (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

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_PrefersSystemProperty() {
+    System.setProperty("simplebuilder.verbose", "true");
+    try {
+      ProcessingEnvironment env =
+          ProcessingEnvironmentStub.builder().put("simplebuilder.verbose", "false").build();
+      CompilerArgumentsReader reader = new CompilerArgumentsReader(env);
+
+      assertEquals("true", 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() {