Various documentation updates

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index c1f7f39b973b292b08746c2856330f69ecfc8fa5..193935f3e6b10000677b2a8dec235b9fe067ef44 100644 (file)
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -14,6 +14,20 @@ Always include the following files in the context:
 
 Include any other files from the [documentation](../docs) in the context as needed based on whether you think it might be helpful to solve your current task or help to review the current PR.
 
+## Build + Test instructions
+
+**CRITICAL: Read and follow these instructions exactly.**
+
+- **NEVER** compile individual files or targets. **ALWAYS** run `mkosi -f box meson compile -C build` to build the entire project. Meson handles incremental compilation automatically.
+- **NEVER** run `meson compile` followed by `meson test` as separate steps. **ALWAYS** run `mkosi -f box meson test -C build -v <TEST-NAME>` directly. Meson will automatically rebuild any required targets before running tests.
+- **NEVER** invent your own build commands or try to optimize the build process.
+- **NEVER** use `head`, `tail`, or pipe (`|`) the output of build or test commands. Always let the full output display. This is critical for diagnosing build and test failures.
+- When asked to build and test code changes:
+  - **CORRECT**: Run `mkosi -f box -- meson test -C build -v <TEST-NAME>` (this builds and runs tests in one command)
+  - **WRONG**: Run `mkosi -f box -- meson compile -C build` followed by `mkosi -f box -- meson test -C build -v <TEST-NAME>`
+  - **WRONG**: Run `mkosi -f box -- meson compile -C build src/core/systemd` or similar individual target compilation
+  - **WRONG**: Run `mkosi -f box -- meson test -C build -v <TEST-NAME> 2>&1 | tail -100` or similar piped commands
+
 ## Pull Request review instructions
 
 - Focus on making sure the coding style is followed as documented in `docs/CODING_STYLE.md`

diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md
index ccbe415acdcd01773ff4a91ddfd77d5218d0e65f..18fefb484668a1024129241b814aa3be177518e2 100644 (file)
--- a/docs/CODING_STYLE.md
+++ b/docs/CODING_STYLE.md
@@ -583,8 +583,8 @@ SPDX-License-Identifier: LGPL-2.1-or-later
   code. (With one exception: it is OK to log with DEBUG level from any code,
   with the exception of maybe inner loops).
 
-- In public API calls, you **must** validate all your input arguments for
-  programming error with `assert_return()` and return a sensible return
+- In libsystemd public API calls, you **must** validate all your input arguments
+  for programming error with `assert_return()` and return a sensible return
   code. In all other calls, it is recommended to check for programming errors
   with a more brutal `assert()`. We are more forgiving to public users than for
   ourselves! Note that `assert()` and `assert_return()` really only should be
@@ -982,5 +982,8 @@ SPDX-License-Identifier: LGPL-2.1-or-later
   macro exists for your specific use case, please add a new assertion macro in a
   separate commit.
 
+- Use `ASSERT_OK_ERRNO()` and similar macros instead of `ASSERT_OK()` when
+  calling glibc APIs that return the error in `errno`.
+
 - When modifying existing tests, please convert the test to use the new assertion
   macros from `tests.h` if it is not already using those.

diff --git a/docs/HACKING.md b/docs/HACKING.md
index 37f1148b54bc4a86d652c09b1b64d994c66bc02b..2825a4e3f098122cfc01586cd09f6e34413d2297 100644 (file)
--- a/docs/HACKING.md
+++ b/docs/HACKING.md
@@ -39,11 +39,11 @@ chance that your distribution's packaged version of mkosi will be too old.
 Then, you can build, run and test systemd executables as follows:
 
 ```sh
-$ mkosi -f genkey                                  # Generate signing keys once.
+$ mkosi -f genkey                                            # Generate signing keys once.
 $ mkosi -f box -- meson setup -Dbpf-framework=disabled build # bpftool detection inside mkosi box is broken on Ubuntu Noble and older
 $ mkosi -f box -- meson compile -C build
 $ mkosi -f box -- build/systemctl --version
-$ mkosi -f box -- meson test -C build          # Run the unit tests
+$ mkosi -f box -- meson test -C build --print-errorlogs      # Run the unit tests
 ```
 
 To build and boot an OS image with the latest systemd installed: