# Compiling your own C, C++ and Fortran code in Eugo

Building your own native code with the compilers in the Eugo image: the errors you may meet and how to fix them, GMP and MPFR, the sanitizers and the static analyzers.

Source: https://docs.eugo.io/docs/guides/compiling-your-own-code/

---

> **Audience:** people who compile their own native code inside the Eugo container, by hand, through
> `make`/`cmake`/`meson`, or indirectly through a Python package that builds an extension at install time.
>
> **The one thing to take away:** if a compile stops with
> `clang: error: invalid argument '-fwhole-program-vtables' only allowed with '-flto'`, something added `-fno-lto`.
> **Add `-fno-whole-program-vtables` next to it** and the compile runs (sections 2 and 3).
>
> **How this guide was written:** the error text and behaviour below were measured on 2026-08-21 in Eugo's
> published Graviton2 extended image (clang and flang `24.0.0git`), and re-verified command by command on
> 2026-08-30 against a newer published extended image (built 2026-08-28): nothing changed, and both error messages
> in sections 2 and 3 reproduce verbatim. Sections 7 to 9 were measured later and say when. Paths and version
> strings on your image may differ; the behaviour is what matters.

---

## 1. The compilers in the image

`clang`, `clang++` and `flang` are in the image, and a bare compile just works:

```text
$ clang -O2 -c hello.c        # rc 0
$ clang -O2    hello.c        # rc 0
```

To see exactly what your driver is really running, ask it:

```text
$ clang -### -O2 -c hello.c   # prints the full command line it runs
```

`clang` compiles C as `-std=gnu23` and `clang++` compiles C++ as `-std=gnu++23`. **If you see
`invalid argument '-std=gnu++23' not allowed with 'C'`**, a tool ran `clang++` on *C* input: compile C with `clang`.
Meson older than 1.3 does this when it checks the C compiler, so use Meson 1.3 or newer.

## 2. The error you see when `-fno-lto` is added

**If a compile stops at once with this error, something added `-fno-lto`:**

```text
$ clang -O2 -fno-lto -c hello.c
clang: error: invalid argument '-fwhole-program-vtables' only allowed with '-flto'
```

The driver stops before compiling anything. The fix is to add `-fno-whole-program-vtables` next to `-fno-lto`
(section 3). This is the whole failure. It is not a broken image, a missing header, or your code.

### 2.1. You may never have typed `-fno-lto` yourself

This is the part that costs people an afternoon. **Build systems add `-fno-lto` on your behalf**, and then the
error surfaces from somewhere you were not looking:

- CMake and Autoconf **probes** that compile a throwaway snippet with `-fno-lto`: the probe fails, and the build
  system silently concludes your compiler is broken, or that some unrelated feature is unavailable.
- Rust's `cc` crate (`cc-rs`) compiling C helper files for a crate you depend on.
- Any upstream `Makefile` or `meson.build` that hard-codes `-fno-lto` for one target.

If you see the error above and you did not write `-fno-lto`, search the generated build files and the configure log
for it before suspecting anything else.

## 3. The fix: never write a bare `-fno-lto`, always pair it

Whenever you pass `-fno-lto` to `clang` or `clang++`, pass `-fno-whole-program-vtables` with it. Appending both to
your flags works:

```bash
export CFLAGS+=" -fno-lto -fno-whole-program-vtables"
export CXXFLAGS+=" -fno-lto -fno-whole-program-vtables"
```

Or on a single command line:

```text
$ clang -O2 -fno-lto -fno-whole-program-vtables -c hello.c   # rc 0
```

Adding `-fno-whole-program-vtables` costs nothing in performance once `-fno-lto` is set.

### 3.1. Fortran is the exception and needs only one flag

**If `flang` stops with this error and produces no object file**, `-fno-whole-program-vtables` reached it:

```text
$ flang -fno-whole-program-vtables ...
flang-24: error: unknown argument: '-fno-whole-program-vtables'
```

`flang` does not accept that flag at all, so remove it from `FFLAGS`. Fortran needs only the one flag:

```bash
export FFLAGS+=" -fno-lto"
```

### 3.2. Use the pair on the whole project, never on one file

If you add `-fno-lto`, add it (with its pair) to **every** file in that project. Building one file with `-fno-lto`
while its siblings are built without it is not a smaller version of the same choice: the two kinds of file end up
disagreeing about vtable layout and inline-function identity. Nothing diagnoses this: no error, no warning. The
program links, runs, and misbehaves somewhere else entirely.

So: whole project, both flags, or neither.

## 4. Quick reference

| If you see | Do this |
|---|---|
| `clang: error: invalid argument '-fwhole-program-vtables' only allowed with '-flto'` | something added `-fno-lto`; add `-fno-whole-program-vtables` next to it, for C and C++ |
| `flang-24: error: unknown argument: '-fno-whole-program-vtables'` | remove that flag from `FFLAGS`; for Fortran, `-fno-lto` alone is enough |
| `invalid argument '-std=gnu++23' not allowed with 'C'` | compile C with `clang`, not `clang++` (Meson 1.3 or newer) |

## 5. Status

**Pairing the two flags is the supported fix, not a temporary workaround.** A bare `-fno-lto` keeps giving the
error in section 2.

## 6. Changing a vectorisation flag? Clear the link cache first

The link step keeps a cache that all of Eugo's compilers share. It speeds up repeated builds, and its lookup key
does **not** notice `-fveclib`. If you change that flag between two builds of the same code in the same container
session, the second build can silently reuse the first build's answer. This happens whether you compile and link in
one command (the `clang myprog.c -o myprog -lm` shape) or as separate steps (`clang -c`, then link the objects).

It shows up in both directions, and one of them is silent:

| What you did | What you get |
|---|---|
| Built normally, then rebuilt with `-fveclib=none` | Link fails: `undefined symbol: armpl_vexpq_f64` (and friends) |
| Built with `-fveclib=none`, then rebuilt normally | Builds fine, exit code 0, **but your binary has silently lost ArmPL vectorisation** |

The fix is one line. Clear the cache, then rebuild:

```bash
rm -rf /tmp/eugo/usetime/packages/native/llvm_toolchain/cache/thinlto
```

Pointing the link at another cache folder with `-Wl,--thinlto-cache-dir=...` does **not** help: the link keeps
using the folder above.

**When this cannot affect you.** The cache is empty when a container starts and lives under `/tmp`, so it never
carries anything between `docker run` invocations: you need two differing builds inside one session.

**Separate compile and link steps do not avoid it.** Built with `clang -c` and then a link of the objects, both rows
of the table above reproduce. With separate steps, `-fveclib` also only takes effect when it is on the link command,
because the vector library is chosen when the program is linked: a `-fveclib=none` on the compile command alone is
ignored. Put the flag on both commands, and clear the cache as above when you change it. (Measured on 2026-11-13 on a
gb10 extended image built 2026-09-17.)

## 7. GMP and MPFR: ours is the default, and gnutls's FIPS mode refuses it

> **How this section was measured:** on 2026-10-23, on extended, standard and nano images built from that day's
> source: the commands below, the missing-function failure (a
> program linked against Fedora's `/usr/lib64/libmpfr.so.6` that calls `mpfr_set_float128`), and the FIPS refusal
> with `GNUTLS_FORCE_FIPS_MODE=1`.

Eugo's images ship their own GMP and MPFR, and those copies are the ones every program in the image loads, Fedora's
own programs included (gawk, coreutils' `factor`, gnutls, ...). They are also the ones every build finds by default:
the headers (`gmp.h`, `mpfr.h`) sit in `/usr/local/include`, which the compiler searches by itself, and the
libraries in `/usr/local/lib64`, which the linker searches. So naming the libraries is enough, and pkg-config works
too:

```bash
clang app.c -lmpfr -lgmp                            # MPFR (it needs GMP as well)
clang app.c -lgmp                                   # GMP only
clang app.c $(pkg-config --cflags --libs mpfr)      # the same through pkg-config
clang rsa.c $(pkg-config --cflags --libs hogweed nettle)   # nettle's RSA/ECDSA code, which calls GMP too
```

Your program needs no run path: the system loader finds Eugo's copies before Fedora's. This works in the extended
tier, which ships the compilers, headers and pkg-config files; a program you build there also runs in standard and
nano.

**Six MPFR functions are missing.** Eugo's MPFR has no `mpfr_get_decimal64`, `mpfr_set_decimal64`,
`mpfr_get_decimal128`, `mpfr_set_decimal128`, `mpfr_get_float128` or `mpfr_set_float128`, which Fedora's MPFR has:
they need decimal floating-point types and `_Float128`, which clang does not provide on this processor. Nothing in
the image calls them. But a program built elsewhere against Fedora's MPFR that calls one of them fails in these
images with `symbol lookup error: ... undefined symbol: mpfr_set_float128` (or the function it called): at the first
call when it was linked the usual way, at start-up when it was linked with `-Wl,-z,now`.

**FIPS mode.** gnutls, in FIPS mode, checks the fingerprint of the GMP library it has loaded against Fedora's, and
Eugo's GMP does not match. So in FIPS mode every program that uses gnutls stops with `Error while performing self
checks` (for example `dirmngr: Fatal: gnutls_global_init failed`). gnutls turns FIPS mode on by itself when the
host's kernel was booted with `fips=1`, and when `GNUTLS_FORCE_FIPS_MODE=1` is set. This is a known limitation of
Eugo's images, accepted on purpose; nothing in the image works around it. If you need gnutls's FIPS mode, do not use
these images on a FIPS host.

## 8. valgrind cannot run programs in our gb10 images: use the sanitizers instead

> **How this section was measured:** the valgrind results come from tests on 2026-10-05 with valgrind 3.27.1,
> brought in from outside because our images do not ship it. The sanitizer commands below were run on 2026-10-23 on
> a gb10 extended image built 2026-09-17.

**Our images do not include valgrind.** There is no `valgrind` command and no `valgrind/memcheck.h` header.

**If you install valgrind yourself, it cannot run anything on our gb10 images.** Every program, even `/bin/true`, is
stopped with `SIGILL` ("illegal instruction") before its `main` runs. This was measured on all three gb10 images:
nano, standard and extended.

Why, in plain words. valgrind works by translating each machine instruction of your program before running it. Our
gb10 images are built for the GB10's processor, so the programs in them use that processor's wide vector
instructions (Arm calls them SVE) to speed loops up. valgrind's translator for Arm processors does not know those
instructions (neither version 3.27.1, the one tried, nor valgrind's current development code), so it stops the
program at the first one it meets. Our C++ standard library (libc++) and Python's own library (libpython) each carry
more than two thousand of them, and Ray's raylet several hundred or more. And every program in the image loads that
C++ library when it starts, because `/etc/ld.so.preload` lists it, so even a plain C program meets one before its
`main` runs.

- Emptying `/etc/ld.so.preload`, in a throwaway container used only for the valgrind run, lets programs that do not
  use our C++ library run under valgrind. Python and Ray link
  that library themselves, so they still stop. Only a build of them without SVE would help.
- The graviton5 and Grace images were not tried. Their processors also have SVE.
- torch's `Timer.collect_callgrind()` does not work in our images either (our torch is built without its valgrind
  support), nor do Ray's valgrind switches such as `RAY_RAYLET_VALGRIND` (no valgrind ships, and the limits on this page apply).

**On a graviton2-based image** the processor has no SVE, and valgrind did run `/bin/true` and `python3 -c pass`
(measured on an image built on our graviton2 extended image). A second limit shows up there, and it was measured on
every image tried (on the gb10 ones with `/etc/ld.so.preload` emptied): valgrind stops with
`Max number of guard pages is too low` when a program starts many threads. A small C program with 64 threads
stopped, and so did one with 256; with 16 threads it ran. The C library in our images (glibc 2.43) protects each
thread's stack with guard pages in a way valgrind has to track, on Linux 6.13 and later, and valgrind 3.27.1 tracks
at most 500 of them unless told otherwise. Raise the limit on valgrind's own command line:

```bash
valgrind --max-guard-pages=1000000 ./myprog
```

Putting `--max-guard-pages` in the `VALGRIND_OPTS` environment variable does not help: valgrind accepts it there but
reads it too late. This was measured on a Linux 6.17 host; the kernel that AWS Fargate tasks run on was not
measured.

**Use the sanitizers instead.** They are part of Eugo's compilers, so they are available wherever the compilers are
(the extended images), need nothing installed, and work without any change to your other flags. AddressSanitizer
(`-fsanitize=address`) catches memory errors such as writing past the end of a buffer or using memory after it was
freed. UndefinedBehaviorSanitizer (`-fsanitize=undefined`) catches mistakes such as a signed integer overflowing.

```text
$ clang++ -g -O1 -fsanitize=address heap_overflow.cpp -o heap_overflow   # rc 0, with warnings (below)
$ ./heap_overflow
==179==ERROR: AddressSanitizer: heap-buffer-overflow on address 0xfbd8355e0020 at pc 0xab277a2a0714 bp 0xffffe1194530 sp 0xffffe1194528
WRITE of size 4 at 0xfbd8355e0020 thread T0
    #0 0xab277a2a0710 in main /tmp/work/heap_overflow.cpp:6:20
...
SUMMARY: AddressSanitizer: heap-buffer-overflow /tmp/work/heap_overflow.cpp:6:20 in main
...
==179==ABORTING                      # exit code 1

$ clang -g -O1 -fsanitize=undefined signed_overflow.c -o signed_overflow   # rc 0, with warnings (below)
$ ./signed_overflow
signed_overflow.c:5:11: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int'
SUMMARY: UndefinedBehaviorSanitizer: undefined-behavior signed_overflow.c:5:11
-2147483648                          # exit code 0: it reports and carries on
```

Three things worth knowing:

- UndefinedBehaviorSanitizer reports and lets the program continue. Add `-fno-sanitize-recover=undefined` to make it
  stop at the first error with exit code 1.
- If the link prints about twenty lines that begin
  `--lto-validate-all-vtables-have-type-infos: RTTI missing for vtable _ZTVN11__sanitizer…`, do nothing: they come
  from the sanitizer's own runtime. The build still succeeds and the checks work.
- If a tiny test program reports nothing, check that the optimizer did not remove the bad access. A C test that
  wrote one element past a `malloc`'d buffer and read it straight back reported nothing at `-O1` (the optimizer
  worked out the answer and deleted the access), and reported the overflow at
  `-O0`. When the bad index came from input the compiler could not see, as it does in real code, the overflow was
  caught at `-O1` and at `-O2`.

---

## 9. The static analyzers: name `clang` when you call scan-build or intercept-build

> **How this section was measured:** on 2026-11-01, on a gb10 extended image built 2026-09-17, with every command
> below run both from a bash shell and with `CC`/`CXX` removed from the environment, and re-checked on 2026-11-13 on
> a gb10 extended image built 2026-09-17. The analyzers are part of the extended images only.

The extended images ship clang's analyzers: `clang-tidy`, `clangd` (the language server editors and JupyterLab use),
`clang-include-cleaner`, `scan-build` (the clang static analyzer run over a whole build) and `intercept-build` (which
writes the `compile_commands.json` that clang-tidy and clangd read). **Our images have no `cc` or `c++` command**,
and two of these tools fall back to exactly those names unless you tell them otherwise. A bash shell in the image
sets `CC=clang` and `CXX=clang++` for you, so `make` itself finds clang there; the tools' own fallbacks ignore that.

**scan-build**: always pass the compilers:

```bash
scan-build --use-cc=clang --use-c++=clang++ make     # rc 0 and "scan-build: 1 bug found." on a planted null dereference
```

Without `--use-cc`/`--use-c++` the build itself fails (`make: *** [...] Error 255`) and scan-build reports
`No bugs found.`, because its compiler wrapper tried to run `cc`. Add `--status-bugs` to get exit code 1 when it
finds a bug. On an older extended image that does not yet include Eugo's own Perl (`/usr/local/bin/perl`),
scan-build stops at once with `Can't locate FindBin.pm in @INC`: three Perl modules it needs are missing from the
system Perl. Install them with `dnf install -y perl-FindBin perl-Hash-Util perl-Sys-Hostname` (measured: with the
three installed, the planted bug is reported).

**intercept-build**: name clang twice, for the tool and for the build:

```bash
intercept-build --use-cc clang --use-c++ clang++ make CC=clang CXX=clang++
sed -i -e 's/"command": "cc /"command": "clang /' -e 's/"command": "c++ /"command": "clang++ /' compile_commands.json
clang-tidy -p . -checks='clang-analyzer-*' my_file.cpp
```

- `--use-cc clang --use-c++ clang++` is for intercept-build itself: it builds a small interception library with that
  compiler, and with the default `cc` that build fails and nothing is recorded.
- `make CC=clang CXX=clang++` is for the build: make's own default is `cc` too. In a bash shell it already has
  `CC=clang`, but naming it makes the command work everywhere. Measured with `CC`/`CXX` removed: both together record
  the build; `make CC=clang` alone records nothing; `--use-cc clang` alone stops with
  `make: cc: No such file or directory`.
- The `sed` line is needed because intercept-build writes every command as `cc …` or `c++ …`, whatever compiler ran.
  clang-tidy and clangd then pick their settings by that name and cannot find the C++ standard library headers
  (`'memory' file not found`). With the names rewritten to `clang`/`clang++`, clang-tidy reads the database and
  reports as it should.
- Name the checks you want. With no `-checks` option and no `.clang-tidy` file, clang-tidy stops with
  `Error: no checks enabled.` (exit code 1). Pass them on the command line, as above, or put
  `Checks: "clang-analyzer-*"` in a `.clang-tidy` file in your project (measured: both report the planted null
  dereference).
- A CMake project needs none of this: configure it with `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` and CMake writes the
  database with the real compiler names.

**scan-build-py** (the Python version of scan-build, also shipped) does not work in our images yet: it stops with
`scan-build-py: Internal error` because `clang -v`, which it runs to identify the compiler, fails under our compiler
configuration. Use the Perl `scan-build` above.

## See also

- The guide to installing Python packages, in this Guides section: a `pip install` that builds a native extension
  goes through these same compilers, so the `-fno-lto` error in section 2 can surface from pip.
