doc: optimize agent build instructions for efficiency

Update AGENTS.md and subordinate guides to recommend incremental
builds via 'make check TESTS=""'. This avoids redundant autogen and
configure steps during iterative development.

With the help of AI-Agents: Google Jules

AGENTS.md

@@ -27,16 +27,20 @@ sudo apt-get update && sudo apt-get install -y \
 
 ### Step 2: Build the Project
 
-Build the project with a recommended set of `./configure` options that enables the testbench and a common set of modules suitable for most development and testing tasks.
+Build the project efficiently. The following command incrementally builds the core and all test dependencies without running the full suite.
+
+```bash
+make -j$(nproc) check TESTS=""
+```
+
+**Note:** If the `Makefile` is missing (first run) or you need to change build options, run the full bootstrap sequence first:
 
 ```bash
 ./autogen.sh
 ./configure --enable-testbench --enable-imdiag --enable-omstdout --enable-mmsnareparse --enable-omotel --enable-imhttp
-make -j$(nproc)
+make -j$(nproc) check TESTS=""
 ```
 
-**Note:** If `autogen.sh` has been run before, you only need to run it again if `configure.ac` or `Makefile.am` files have changed.
-
 ### Step 3: Run Tests
 
 Run a relevant test to verify your changes. The testbench allows test scripts to be run directly. `imtcp-basic.sh` serves as a good general-purpose smoke test.
@@ -116,30 +120,32 @@ When the user says the codeword "SETUP", do the following:
 
 When the user says the codeword "BUILD" optionally followed by configure options, do the following:
 
-1. **Generate the autotools build system** (if not already done):
+1. **Check for existing build configuration**:
+   - If a `Makefile` exists and no new configure options are provided, **SKIP** to Step 3.
+
+2. **Generate and Configure** (if Makefile is missing or options provided):
    ```bash
    ./autogen.sh
    ```
-
-2. **Configure the project**:
-   - If configure options are provided after "BUILD", use them:
+   - If configure options are provided:
      ```bash
      ./configure [user-provided-options]
      ```
-   - If no options are provided, use the default testbench configuration:
+   - If no options are provided:
      ```bash
-     ./configure --enable-testbench --enable-imdiag --enable-omstdout
+     ./configure --enable-testbench --enable-imdiag --enable-omstdout --enable-mmsnareparse --enable-omotel --enable-imhttp
      ```
 
 3. **Build the project**:
+   Use the efficient incremental build command that prepares all test binaries:
    ```bash
-   make -j$(nproc)
+   make -j$(nproc) check TESTS=""
    ```
 
 Examples:
-- `BUILD` - Uses default testbench configuration
-- `BUILD --enable-testbench --enable-mmsnareparse` - Custom configuration with mmsnareparse module
-- `BUILD --enable-testbench --enable-imdiag --enable-omstdout --enable-mmsnareparse --enable-omotel` - Multiple modules
+- `BUILD` (Makefile exists) - Runs `make -j$(nproc) check TESTS=""` directly.
+- `BUILD` (First run) - Runs autogen, default configure, then make.
+- `BUILD --enable-imkafka` - Runs autogen, custom configure, then make.
 
 ### `TEST [test-script-names]`
 

contrib/AGENTS.md

@@ -10,18 +10,13 @@ These instructions apply to everything under `contrib/`.
   available in CI.  Document any manual setup that reviewers must perform.
 
 ## Build & bootstrap reminders
-- Run `./autogen.sh` before your first build in a fresh checkout and whenever
-  you modify autotools inputs (`configure.ac`, `Makefile.am`, files under `m4/`).  Expect
-  the bootstrap step to take up to about 2 minutes; you can skip it when the
-  task does not require building (for example, documentation-only changes).
-- Configure with the switches needed to include the contrib module.  Some
-  modules are disabled unless their dependencies are detected.  Use
-  `./configure --help` and the module's `MODULE_METADATA.yaml` to identify
-  the relevant `--enable`/`--with` flags.
-- Build with `make -j$(nproc)` and execute the most relevant smoke test
-  directly (for example `./tests/imtcp-basic.sh` or a module-specific script).
-  Reserve `make check` for cases where you must mirror CI or diagnose harness
-  behavior.
+- **Efficient Build:** Use `make -j$(nproc) check TESTS=""` to incrementally build the core and all test dependencies. This is the primary build command.
+- **Bootstrap/Configure:** Only run `./autogen.sh` and `./configure` if:
+    1.  The `Makefile` is missing (first run).
+    2.  You have modified `configure.ac`, `Makefile.am`, or `m4/` files.
+    3.  You need to change build options (e.g., enabling a new contrib module).
+    4.  You need to enable a module that requires specific flags (check `MODULE_METADATA.yaml`).
+- **Run Tests:** Execute the most relevant smoke/regression test directly (e.g., `./tests/imtcp-basic.sh`). Direct invocation keeps stdout/stderr visible. Use `make check` only when mirroring CI.
 
 ## Metadata required for every module
 Each contrib module directory (for example `contrib/mmkubernetes/`) must contain

plugins/AGENTS.md

@@ -4,20 +4,13 @@ These instructions apply to everything under `plugins/` (except `plugins/externa
 which vendors third-party code; do not modify it unless specifically requested).
 
 ## Build & bootstrap reminders
-- Run `./autogen.sh` before your **first** build in a fresh checkout and
-  whenever you touch `configure.ac`, any `Makefile.am`, or files under `m4/`.
-  The bootstrap step can take up to ~2 minutes, so skip it for pure
-  documentation or metadata-only edits when no build is required.
-- Configure with the options needed for the module you are touching.  The
-  defaults build all modules whose dependencies are present.  Use
-  `./configure --help` to discover `--enable`/`--disable` switches if you need
-  to constrain the build.
-- Keep the testbench enabled with `./configure --enable-testbench` so
-  module-specific tests continue to compile.
-- Build with `make -j$(nproc)` and execute the most relevant smoke/regression
-  test directly (for example `./tests/imtcp-basic.sh` or a module-specific
-  script).  Direct invocation keeps stdout/stderr visible.  Use `make check`
-  only when mirroring CI or chasing harness-specific failures.
+- **Efficient Build:** Use `make -j$(nproc) check TESTS=""` to incrementally build the core and all test dependencies. This is the primary build command.
+- **Bootstrap/Configure:** Only run `./autogen.sh` and `./configure` if:
+    1.  The `Makefile` is missing (first run).
+    2.  You have modified `configure.ac`, `Makefile.am`, or `m4/` files.
+    3.  You need to change build options (e.g., enabling a new module).
+- **Testbench:** Keep the testbench enabled with `./configure --enable-testbench` (when configuring) so module-specific tests continue to compile.
+- **Run Tests:** Execute the most relevant smoke/regression test directly (e.g., `./tests/imtcp-basic.sh`). Direct invocation keeps stdout/stderr visible. Use `make check` only when mirroring CI.
 
 ## Module-level agent guides
 High-complexity modules benefit from their own `AGENTS.md` living directly

plugins/imkafka/AGENTS.md

@@ -6,13 +6,13 @@
 - Support status: contributor-supported. Maturity: mature.
 
 ## Build & dependencies
-- Configure with `--enable-imkafka` (pair with `--enable-omkafka` for combined pipelines).
-- `./devtools/codex-setup.sh` installs librdkafka headers inside the sandbox when available.
-- Re-run `./configure` after toggling Kafka-related flags; rerun `./autogen.sh` if you touch `configure.ac`, any `Makefile.am`, or files under `m4/`.
+- **Efficient Build:** Use `make -j$(nproc) check TESTS=""` to build the module and test dependencies.
+- **Configure:** Run `./configure --enable-imkafka` (and `--enable-omkafka` if needed).
+- **Bootstrap:** Only run `./autogen.sh` if you touch `configure.ac`, `Makefile.am`, or `m4/`.
 
 ## Local testing
 - **Skip the Kafka integration tests when working in the sandbox.** They rely on downloading and running Kafka plus ZooKeeper, which is too resource intensive for agent runs.
-- Build-only validation is acceptable: run `./configure --enable-imkafka` (optionally `--enable-omkafka`) and `make modules` to confirm the plugin links.
+- Build-only validation is acceptable. Run the efficient build command above.
 - Maintainers can enable `--enable-kafka-tests` and invoke scripts like `./tests/imkafka.sh` or `./tests/imkafka_multi_group.sh`, but should expect several minutes of setup time for the Kafka cluster.
 
 ## Diagnostics & troubleshooting

plugins/omelasticsearch/AGENTS.md

@@ -6,19 +6,15 @@
 - Support status: core-supported. Maturity: fully-mature.
 
 ## Build & dependencies
-- Configure with `--enable-elasticsearch` to compile this plugin.
-- `./devtools/codex-setup.sh` installs the required libcurl development headers
-  inside the sandbox.
-- Re-run `./configure` after toggling the flag; rerun `./autogen.sh` if you touch
-  `configure.ac`, any `Makefile.am`, or files under `m4/`.
+- **Efficient Build:** Use `make -j$(nproc) check TESTS=""` to build the module and test dependencies.
+- **Configure:** Run `./configure --enable-elasticsearch` (and other needed flags).
+- **Bootstrap:** Only run `./autogen.sh` if you touch `configure.ac`, `Makefile.am`, or `m4/`.
 
 ## Local testing
 - **Do not run the integration tests during routine agent work.** They require
   downloading and launching an Elasticsearch node, which is too heavy for the
   sandbox environment.
-- Compiling the module is sufficient validation. Rebuild the tree with
-  `./configure --enable-elasticsearch` followed by `make modules` to ensure the
-  plugin links correctly.
+- Compiling the module is sufficient validation. Run the efficient build command above.
 - Maintainers who need full coverage can enable the suite with
   `--enable-elasticsearch-tests=minimal` and run `make es-basic.log` (additional
   scenarios live beside it), but expect multi-minute startup overhead for the

plugins/omkafka/AGENTS.md

@@ -6,13 +6,13 @@
 - Support status: contributor-supported. Maturity: mature.
 
 ## Build & dependencies
-- Configure with `--enable-omkafka` (optionally pair with `--enable-imkafka` for end-to-end tests).
-- `./devtools/codex-setup.sh` installs librdkafka headers inside the sandbox when available.
-- Re-run `./configure` after toggling Kafka-related flags; rerun `./autogen.sh` if you touch `configure.ac`, any `Makefile.am`, or files under `m4/`.
+- **Efficient Build:** Use `make -j$(nproc) check TESTS=""` to build the module and test dependencies.
+- **Configure:** Run `./configure --enable-omkafka` (and `--enable-imkafka` if needed).
+- **Bootstrap:** Only run `./autogen.sh` if you touch `configure.ac`, `Makefile.am`, or `m4/`.
 
 ## Local testing
 - **Skip the Kafka integration tests for routine agent tasks.** They download and run Kafka plus ZooKeeper, which exceeds the sandbox resource budget.
-- Build validation is sufficient: run `./configure --enable-omkafka` (and `--enable-imkafka` if desired) followed by `make modules` to confirm the plugin links.
+- Build validation is sufficient. Run the efficient build command above.
 - Maintainers who must exercise the suite can enable `--enable-kafka-tests` and run scripts such as `./tests/omkafka.sh`, but expect multi-minute startup time for the embedded Kafka cluster.
 
 ## Diagnostics & troubleshooting

plugins/omotel/AGENTS.md

@@ -9,6 +9,10 @@ These instructions apply to files inside `plugins/omotel/`.
 - Refresh the concurrency note in `omotel.c` if locking expectations change.
 - Run `devtools/format-code.sh` before committing.
 
+## Build & dependencies
+- **Efficient Build:** Use `make -j$(nproc) check TESTS=""`.
+- **Configure:** Use `--enable-omotel` to enable this module.
+
 ## Testing
 - Run `tests/omotel-http-batch.sh` to exercise the HTTP batching, gzip, and
   retry path.

plugins/omruleset/AGENTS.md

@@ -8,7 +8,8 @@
 
 ## Build & dependencies
 - Built automatically when plugins are enabled; no extra configure flags or external dependencies.
-- Follow the repository-wide autotools guidance (rerun `./autogen.sh` only when autotools inputs change).
+- **Efficient Build:** Use `make -j$(nproc) check TESTS=""`.
+- **Bootstrap:** Run `./autogen.sh` only when autotools inputs change.
 
 ## Local testing
 - There is no standalone test suite for `omruleset`. Building rsyslog with `make` is sufficient validation.

runtime/AGENTS.md

@@ -21,21 +21,13 @@ collection, and process orchestration).
 - `timezones.c`, `datetime.c`: time conversion helpers.
 
 ## Build & validation
-- Bootstrap with `./autogen.sh` only when build scripts change (see root
-  instructions) and configure with `./configure --enable-testbench` so runtime
-  helpers used by the testbench stay available. Run these commands from the
-  repository root, not from within `runtime/`.
-- Build the core with `make -j$(nproc)`; this compiles the runtime and shared
-  libraries that tests dynamically load via `-M../runtime/.libs:../.libs`.
-- Prefer targeted test runs over a full `make check`:
-  - Directly invoke the most relevant shell test under `tests/` (e.g.
-    `./tests/queue-persist.sh`).
-  - Use `make check TESTS='<script>.sh'` when you need automake’s harness or
-    Valgrind variants (`*-vg.sh`).
+- **Efficient Build:** Use `make -j$(nproc) check TESTS=""` to incrementally build the core, shared libraries, and test dependencies. This ensures that tests can dynamically load the runtime via `-M../runtime/.libs`.
+- **Bootstrap/Configure:** Run `./autogen.sh` and `./configure --enable-testbench` only when build scripts change (`configure.ac`, `Makefile.am`, etc.) or if the `Makefile` is missing. Run these from the repository root.
+- **Run Tests:** Prefer targeted test runs:
+  - Directly invoke the most relevant shell test under `tests/` (e.g. `./tests/queue-persist.sh`).
+  - Use `make check TESTS='<script>.sh'` when you need automake’s harness or Valgrind variants (`*-vg.sh`).
   - For configuration validation edits, run `./tests/validation-run.sh`.
-- When changing exported symbols, update `runtime/Makefile.am` and ensure the
-  library version script (if touched) remains consistent with existing
-  SONAME policies.
+- When changing exported symbols, update `runtime/Makefile.am` and ensure the library version script (if touched) remains consistent with existing SONAME policies.
 
 ## Coding expectations
 - Follow `COMMENTING_STYLE.md` and add/update "Concurrency & Locking" blocks in

tests/AGENTS.md

@@ -33,10 +33,11 @@ agents.
   should know about the new knob.
 
 ## Running tests locally
-- Build rsyslog first (`./autogen.sh`, `./configure --enable-testbench`,
-  `make -j$(nproc)`) so the testbench can load freshly built binaries and
-  modules. The same bootstrap commands are called out in `tests/README` under
-  “Quickstart”.
+- Build rsyslog first using the efficient incremental command:
+  ```bash
+  make -j$(nproc) check TESTS=""
+  ```
+  This ensures the testbench can load freshly built binaries and modules. If the `Makefile` is missing, see "Step 2" in the top-level `AGENTS.md`.
 - Execute individual scenarios directly for quick feedback
   (`./tests/imfile-basic.sh`).
 - Use `make check TESTS='script.sh'` when you need Automake logging,

tools/AGENTS.md

@@ -13,9 +13,8 @@ core but are compiled directly into the rsyslog binary:
 ## Build & testing expectations
 - These modules are always built as part of the default configuration; no
   additional `./configure` flags are required.
-- Follow the top-level build workflow: run `./autogen.sh` only when autotools
-  inputs change, configure with the options your change requires, and rebuild via
-  `make`.
+- **Efficient Build:** Use `make -j$(nproc) check TESTS=""` to incrementally build the tools and test dependencies.
+- **Bootstrap:** Run `./autogen.sh` only when autotools inputs change.
 - There are no standalone regression scripts for these built-in modules. When
   modifying them, rely on targeted configuration tests under `tests/` (e.g.
   `./tests/omfile-basic.sh`) or add new ones as needed.