Skip to content

Documentation: Document the coverage build a bit more #26367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+24 −0
Open

Documentation: Document the coverage build a bit more #26367

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions Documentation/AdvancedBuildInstructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ There are some optional features that can be enabled during compilation that are
- `ENABLE_KERNEL_UNDEFINED_SANITIZER`: builds in runtime checks for detecting undefined behavior in the kernel.
- `ENABLE_KERNEL_UNDEFINED_SANITIZER_ALWAYS_DEADLY`: makes the aforementioned runtime checks always deadly, as seen by the compiler.
- `ENABLE_KERNEL_COVERAGE_COLLECTION`: enables the KCOV API and kernel coverage collection instrumentation. Only useful for coverage guided kernel fuzzing.
- `ENABLE_LAGOM_COVERAGE_COLLECTION`: enables coverage collection instrumentation for lagom builds. Currently only works with a Clang build.
- `ENABLE_USERSPACE_COVERAGE_COLLECTION`: enables coverage collection instrumentation for userspace. Currently only works with a Clang build.
- `ENABLE_MEMORY_SANITIZER`: enables runtime checks for uninitialized memory accesses in Lagom test cases.
- `ENABLE_UNDEFINED_SANITIZER`: builds in runtime checks for [undefined behavior](https://en.wikipedia.org/wiki/Undefined_behavior) (like null pointer dereferences and signed integer overflows) in Lagom and the SerenityOS userland.
Expand Down Expand Up @@ -250,3 +251,26 @@ Some OS distributions don't ship bleeding-edge clang-format binaries. Below are
1. If you have a Debian-based (apt-based) distribution, use the [LLVM apt repositories](https://apt.llvm.org) to install the latest release of clang-format.
2. Compile the SerenityOS-patched LLVM from source using `Toolchain/BuildClang.sh` as described above and use the compiled `Toolchain/Local/clang/bin/clang-format` binary in your editor and terminal. The meta-lint-ci pre-commit hook will automatically pick up the Toolchain clang-format binary.
3. Compile LLVM from source as described in the LLVM documentation [here](https://llvm.org/docs/GettingStarted.html#compiling-the-llvm-suite-source-code).

## Coverage builds

For serenity builds, Meta/analyze-qemu-coverage.sh can help you.

For lagom builds, you currently have to do the same thing manually:

1. Enable `ENABLE_LAGOM_COVERAGE_COLLECTION` in BUild/lagom/CMakeCache.txt
Copy link
Member

@LucasChollet LucasChollet Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/BUild/Build/

2. Build: `Meta/serenity.sh build lagom TestImageDecoder`
3. Run tests: `(cd Tests/LibGfx; ../../Build/lagom/bin/TestImageDecoder)`
4. Generate report, requires an LLVM checkout and build:
Copy link
Member

@LucasChollet LucasChollet Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need a custom LLVM build? (That's how it sounds here)
Building with coverage already requires clang and I think it usually comes with llvm-tools which contains llvm-profdata and llvm-cov.

Copy link
Contributor Author

@nico nico Nov 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need llvm-profdata and llvm-cov from somewhere, and you need to get prepare-code-coverage-artifact.py from somewhere. I suppose you don't have to have a build. I'll tweak it a bit, thanks.


~/src/llvm-project/llvm/utils/prepare-code-coverage-artifact.py \
--unified-report \
-C Build/lagom \
~/src/llvm-project/out/gn/bin/llvm-profdata \
~/src/llvm-project/out/gn/bin/llvm-cov \
Tests/LibGfx \
report-output \
Build/lagom/bin/TestImageDecoder \
Build/lagom/lib/liblagom-gfx.dylib

5. `open report-output/TestImageDecoder/index.html`
Loading