Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
198f77a
refactor(compilerlib): run compile() through runCompilation
SizzleUnrlsd Nov 12, 2026
897f321
feat(compilerlib): compile to an llvm::Module in the caller's context
SizzleUnrlsd Nov 12, 2026
c5a42e3
test(compilerlib): check the modules compileToModule gives
SizzleUnrlsd Nov 12, 2026
7f065f0
docs(readme): describe compiling to a module
SizzleUnrlsd Nov 12, 2026
cad1cca
docs(changelog): note compiling to a module
SizzleUnrlsd Nov 12, 2026
e66cf7d
docs(changelog): note the tests of compileToModule
SizzleUnrlsd Nov 12, 2026
3dd3255
docs(changelog): note the README section on modules
SizzleUnrlsd Nov 12, 2026
6838164
fix(compilerlib): keep value names in an LLVM 16 context given some
SizzleUnrlsd Nov 12, 2026
35dac7f
docs(readme): note the value names an LLVM 16 context keeps
SizzleUnrlsd Nov 12, 2026
3c715b2
docs(changelog): note the value names an LLVM 16 context keeps
SizzleUnrlsd Nov 12, 2026
6f99afa
fix(compilerlib): restore a module's context after a recovered crash
SizzleUnrlsd Nov 16, 2026
4fe2efc
fix(compilerlib): give a module's context its diagnostic handler back
SizzleUnrlsd Nov 16, 2026
cdacb06
test(compilerlib): check a context's diagnostic handler after a module
SizzleUnrlsd Nov 16, 2026
694de85
test(compilerlib): check the handler after a record that cannot open
SizzleUnrlsd Nov 16, 2026
9ad087e
test(compilerlib): check the handler after an unknown record format
SizzleUnrlsd Nov 16, 2026
977a5e7
test(compilerlib): check the handler after an instrumented failure
SizzleUnrlsd Nov 16, 2026
cf37c7c
test(compilerlib): check the handler after a module that cannot link
SizzleUnrlsd Nov 16, 2026
decfc65
test(compilerlib): check a module's context after a recovered crash
SizzleUnrlsd Nov 16, 2026
741f41f
docs(compilerlib): note the diagnostic handler of a module's context
SizzleUnrlsd Nov 16, 2026
358b2e1
docs(readme): note the diagnostic handler of a module's context
SizzleUnrlsd Nov 16, 2026
9c69841
docs(changelog): note the diagnostic handler of a module's context
SizzleUnrlsd Nov 16, 2026
9ebd2dd
docs(changelog): note the tests of a module's context after a failure
SizzleUnrlsd Nov 16, 2026
be9bd28
Merge branch 'main' into feat/compile-to-module
SizzleUnrlsd Nov 16, 2026
00e9537
test(compilerlib): check modules compiled from several threads at once
SizzleUnrlsd Nov 16, 2026
f43dc01
docs(compilerlib): note the working directory of a module's compilation
SizzleUnrlsd Nov 16, 2026
9b80ced
docs(readme): note the working directory of a module's compilation
SizzleUnrlsd Nov 16, 2026
729f963
docs(changelog): note modules compiled from several threads
SizzleUnrlsd Nov 16, 2026
6eb4646
docs(changelog): note the test of modules compiled from several threads
SizzleUnrlsd Nov 16, 2026
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
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,16 @@ pull request.
under a lock. A compilation with a job that runs as a program, such as a link, and one that
passes `-mllvm`, `-mdebug-pass`, `-mlimit-float-precision` or `-ftime-report` must not run
while another one does (#262, #261).
- **Compiling to a module.** `compilerlib::compileToModule`, from
`compilerlib/compile_module.hpp`, gives the module that `compilerlib::compile` writes as text
or bitcode, created in an `llvm::LLVMContext` of the host, instead of writing it for the host
to read it back. Its arguments are those of an LLVM IR compilation; the output file is not
written, and the other files the arguments ask for, such as a dependency file, are. The
context keeps its own setting of value names, except with LLVM 16, where a context that
discards them keeps them after a compilation that names values. It keeps its diagnostic
handler too, which the compilation does not call, whether the compilation succeeded, failed,
or crashed and was recovered. With `-working-directory`, it compiles from several threads
at once as `compile` does, each with a context of its own (#265, #263).

### Behaviour changes

Expand Down Expand Up @@ -207,6 +217,14 @@ pull request.
- When `sbrk()` fails in the sbrk test of the full allocation table, the test reports `errno`,
the program break and the mapping above it, `RLIMIT_DATA`, and the memory of the process and
of the system (#239, #233).
- Unit tests check that `compileToModule` gives the module that `compile` writes as text, at -O0
and -O2, instrumented or not, and the module of a bitcode compilation, whose dependency file is
written and output file is not; that it fails on a compilation to an object and on a broken
source; that the context keeps its setting of value names; and that it keeps its diagnostic
handler, reports to it and takes another compilation after one that Clang's backend ends
early, on an optimization record it cannot set up or a module it cannot link in, and after a
crash that the host recovers; and that eight threads, each with a context and a working
directory of its own, each get the module of their own sources (#265, #263).
- The Docker tests build and test the image in a job per architecture, each on a runner of its
own architecture: arm64 on `ubuntu-24.04-arm` instead of under QEMU on an amd64 runner. Under
QEMU's user-mode emulation, `sbrk()` failed now and then in the sbrk test of the full
Expand Down Expand Up @@ -238,6 +256,7 @@ pull request.

### Documentation

- The README describes compiling to a module with `compileToModule` (#265, #263).
- `NOTICE` dates the copyright from 2025, when the code began, credits the CoreTrace
contributors alongside Hugo Payet and links the repository. It keeps only these
attribution notices, without the license header meant for source files (#248).
Expand Down
29 changes: 29 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -517,3 +517,32 @@ Two kinds of compilations must not run while another one does:
leaves it there.
- **Options of LLVM's own.** Clang applies `-mllvm`, `-mdebug-pass`, `-mlimit-float-precision`
and `-ftime-report` to LLVM's state, which the whole process shares.

### Compiling to a module

`compilerlib::compileToModule`, from `compilerlib/compile_module.hpp`, gives the module that
`compilerlib::compile` writes as text or bitcode, created in an `llvm::LLVMContext` of the host,
instead of writing it for the host to read it back:

```cpp
#include <compilerlib/compile_module.hpp>

llvm::LLVMContext context;
compilerlib::ModuleResult result =
compilerlib::compileToModule({"-g", "-c", "-emit-llvm", "unit.cpp"}, context);
if (result.success)
analyze(*result.module);
```

Its arguments are those of an LLVM IR compilation, `-S -emit-llvm` or `-c -emit-llvm`. The output
file is not written; the other files the arguments ask for, such as a dependency file, are. With
`instrument`, the module is the instrumented one. Code generation sets options of the context, as
it does with clang, except whether value names are discarded: the context keeps its own setting,
which applies to the modules read into it later. With LLVM 16, a context that discards names keeps
them after a compilation that names values, since LLVM 16 cannot destroy those values in a context
that discards names. The context's diagnostic handler is set aside for the compilation, which does
not call it, and is the context's again once `compileToModule` returns, whether the compilation
succeeded, failed, or crashed and was recovered.

`-working-directory` and compilations from several threads at once are as for
`compilerlib::compile`, each compilation with a context of its own.
48 changes: 48 additions & 0 deletions include/compilerlib/compile_module.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
// SPDX-License-Identifier: Apache-2.0
#ifndef COMPILERLIB_COMPILE_MODULE_HPP
#define COMPILERLIB_COMPILE_MODULE_HPP

#include "compilerlib/attributes.hpp"

#include <llvm/IR/LLVMContext.h>
#include <llvm/IR/Module.h>

#include <memory>
#include <string>
#include <vector>

namespace compilerlib
{

struct ModuleResult
{
bool success = false;
std::string diagnostics;
/// The module, in the context compileToModule was given; null when the compilation
/// failed.
std::unique_ptr<llvm::Module> module;
};

/// Compiles one source to the module that compile() writes, created in `context`, for a
/// host that works on the module itself: it is neither written as text or bitcode nor read
/// back. `args` are those of an LLVM IR compilation, `-S -emit-llvm` or `-c -emit-llvm`;
/// the output file is not written, and the other files the arguments ask for, such as a
/// dependency file, are. With `instrument`, the module is the instrumented one.
///
/// Code generation sets options of `context` as it does with clang, except whether value
/// names are discarded, which is restored: modules read into `context` later keep theirs.
/// With LLVM 16, a context that discards names keeps them after a compilation that names
/// values, which LLVM 16 could not destroy in a context that discards names.
/// The diagnostic handler of `context` is set aside for the compilation, which does not
/// call it, and is the context's again once compileToModule returns: whether the
/// compilation succeeded, failed, or crashed and was recovered.
/// No other thread may use `context` during the compilation.
///
/// `-working-directory` and compilations from several threads at once are as for
/// compile(), each compilation with a context of its own.
CT_NODISCARD ModuleResult compileToModule(const std::vector<std::string>& args,
llvm::LLVMContext& context, bool instrument = false);

} // namespace compilerlib

#endif // COMPILERLIB_COMPILE_MODULE_HPP
13 changes: 13 additions & 0 deletions src/compilerlib/clang_compat.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,19 @@ namespace compilerlib::clang_compat
return file;
}

// Removes from `context` the record that Clang's frontend action set up on it, for
// -fsave-optimization-record: before LLVM 22, the action closes the file and leaves the
// streamer, which would write into it; LLVM 22's handle removes the streamer itself.
inline void releaseFrontendOptimizationRecord(llvm::LLVMContext& context)
{
#if LLVM_VERSION_MAJOR >= 22
(void)context;
#else
context.setLLVMRemarkStreamer(nullptr);
context.setMainRemarkStreamer(nullptr);
#endif
}

// Removes the record's streamer from `context`, which must not write into `file` once
// it is released.
inline void releaseOptimizationRecord(llvm::LLVMContext& context, RemarkFile& file)
Expand Down
Loading
Loading