What do #cgo CFLAGS and #cgo LDFLAGS lines in a cgo preamble do?

## A directive, not C code The preamble is compiled as C, but lines beginning with `#cgo` never reach the C compiler as source. cgo strips them out and interprets them as instructions about **how** to invoke the toolchain: ```go /* #cgo CFLAGS: -I${SRCDIR}/vendor/codec/include #cgo LDFLAGS: -L${SRCDIR}/vendor/codec/lib -lcodec #include <codec.h> */ import "C" ``` Without the first line, `#include <codec.h>` fails because the compiler cannot find the header. Without the second, compilation succeeds and the **link** fails with undefined references to the library's symbols. Learning to read which of the two failed is most of the debugging skill here: a missing header is a compile error naming the file; a missing library is a linker error naming symbols. ## The families - **CFLAGS** — options for the C compiler: `-I` include directories, `-D` macro definitions, `-std=c11`, warning switches. - **CPPFLAGS** — preprocessor options, applied to C, C++ and Objective-C alike; `-I` and `-D` are commonly put here when the package mixes languages. - **CXXFLAGS**, **FFLAGS** — the same idea for C++ and Fortran sources compiled into the package. - **LDFLAGS** — options for the link step: `-L` library search directories, `-l` library names, `-Wl,...` pass-throughs, and platform link options. ## Build-constraint prefixes A directive may carry the same constraint syntax used by build tags, sitting between `#cgo` and the flag family: ``` #cgo linux LDFLAGS: -ldl #cgo darwin LDFLAGS: -framework CoreFoundation #cgo linux,amd64 CFLAGS: -DCODEC_SIMD=1 ``` A comma means AND; a space between separate terms means OR. This is how one package links different system libraries per platform without duplicating the file. ## ${SRCDIR} Because a build can be invoked from any working directory, relative paths in flags are unreliable. cgo expands `${SRCDIR}` to the absolute path of the directory containing the file, which is what makes a vendored C library referenceable: ``` #cgo LDFLAGS: -L${SRCDIR}/third_party/lib -lcodec ``` ## Accumulation across the package Directives are not file-local. cgo concatenates every matching directive from **every** file in the package, in the order the files are processed. Two consequences follow. First, splitting flags across several files is legal but makes the effective command line hard to reconstruct when something goes wrong — keeping them in one place is a maintenance choice worth defending in review. Second, a duplicate `-l` or a conflicting `-D` from another file in the same package will silently join the command line. Environment variables layer on top: values in `CGO_CFLAGS` and `CGO_LDFLAGS` are appended to what the directives supply, which is how a build environment injects a system-specific path without editing source. ## pkg-config Hardcoding `-I` and `-L` paths is fragile across distributions. When the library ships a `.pc` file, cgo can ask `pkg-config` instead: ``` #cgo pkg-config: libcodec ``` At build time cgo runs `pkg-config --cflags libcodec` and `pkg-config --libs libcodec` and splices the results in. This is more portable, at the cost of requiring `pkg-config` and a correctly installed `.pc` file on every build machine — including CI images, which is where it usually breaks first. ## Why flags are restricted Because these directives live in source, a downloaded dependency could otherwise instruct your compiler and linker to do arbitrary things during an ordinary build. The go command therefore permits only a vetted set of flag patterns by default and rejects the rest; the `CGO_CFLAGS_ALLOW`, `CGO_CFLAGS_DISALLOW` and their LDFLAGS counterparts are the escape hatches, expressed as regular expressions. Encountering that rejection is a prompt to ask why a dependency needs an unusual flag, not simply to widen the allow-list. ## Debugging what was actually run When the header or library is not found, the fastest move is to see the real command lines. `go build -x` prints every compiler and linker invocation the build performs, including the expanded `#cgo` flags, so you can confirm whether your `-I` survived, whether `${SRCDIR}` expanded to what you expected, and whether a directive in another file added something you did not want. ## What an interviewer is listening for A clear split between compile-time and link-time flags, awareness that the directives are package-wide rather than file-local, and knowledge that `pkg-config` exists as the portable alternative to hardcoded paths. Mentioning `${SRCDIR}` or the constrained form shows real use rather than a memorised definition.