18 Setting up a development environment

18.1 Only three things are needed — a compiler, an editor, a terminal#

“Development environment” sounds grand, but C programming needs only three things.

• A compiler — chapter 17′s four runners in one. This book takes the gcc and clang families as its reference (both are free and exist on every major platform).
• A text editor — source code is just a text file (chapter 8), so anything that can write characters will do. Which editor you use is a matter of taste, and this book does not decide it.
• A terminal — the window in which you type commands. Every operating system has one.

The shape of the working day is simple too — edit, compile, run. That three-beat cycle is the basic rhythm of programming, and every example in this book turns on it (readers may of course simply read on the page — as chapter 1 promised, even this chapter’s installation is a demonstration, not homework).

> winget install LLVM.LLVM

> clang hello.c -o hello.exe
> .\hello.exe
Hello, world!

$ pacman -S mingw-w64-ucrt-x86_64-gcc
$ gcc --version

18.2 If installing is too much — try it straight in a browser#

Getting the three things above is the proper way, but when you want to run one line right now, a browser is enough. Several places compile and run code with no installation, and some of them show what this book could only describe on paper — the optimised machine code, and where a pointer points.

Figure 18.1 — Layout of a screen showing how one source line becomes several lines of machine code.

18.2.1 Study options — the same on the web#

Whichever tool you use, the knack is not to leave the options box empty. The warning options of the next section work here too.

-std=c23 -Wall -Wextra -Werror -g -O0
-fsanitize=address,undefined        <- only where the site supports it

• Compiler Explorer takes them in the Compiler options box next to the compiler name.
• OnlineGDB takes them under the gear icon, in Extra Compiler Flags.
• Sites often default to an old compiler. If -std=c23 is refused, the compiler is old — pick a newer one from the list (some middle-generation builds accept -std=c2x).

Figure 18.2 — Values as boxes, pointers as arrows — the picture a visualiser draws.

Visualising memory pays off most in Part VII (pointers and memory). The “points to” that this book explained in pictures and words, you can move around yourself in code you wrote.

Places to practise, material that can be read for free, and a knack for spotting out-of-date writing are collected in Appendix P. Since this book has no exercises (see the preface), hands-on practice carries on from there.

18.3 Warnings — leave the free review switched on#

There is one habit to adopt immediately after installation: asking the compiler to turn on plenty of warnings.

$ cc -Wall -Wextra hello.c -o hello

-Wall -Wextra means “tell me about anything suspicious” (despite the name, -Wall is not all of them, so the two are conventionally used together). A warning is not an error but a free code review by the compiler — it points at patterns that invite accidents even where the contract (the standard) is not violated. Every example in this book is verified with these two options on and zero warnings.

18.4 When Korean text breaks — the chain of encodings#

Here we deal in advance with a problem Korean-speaking readers almost always meet: Hangul that comes out broken on screen. It is also why this book’s examples print mostly English strings — the moment you print Hangul, it is not one program but four layers of encoding settings that must all agree for the letters to come out right.

The four links in the chain:

• ① the source file’s encoding — source is, in the end, a byte sequence (chapter 8). Whether the editor saved it as UTF-8 or as CP949 (the EUC-KR family, the old default on Korean Windows) means the same “안녕” is stored as different bytes.
• ② the encoding the compiler reads it as — the compiler guesses, or assumes a default. If the source is UTF-8 and the compiler reads CP949, the bytes of string literals are mangled right there.
• ③ the execution character set — what bytes the compiler embeds in the executable (translation phase 5 seen in chapter 8, which converts source-character-set members into the execution character set; the translation phases are treated in full in chapter 65).
• ④ the encoding the terminal uses — how the window decodes the bytes the program writes. Get this wrong and the screen shows broken characters even if the first three are perfect.

One broken link out of four produces the same symptom — “the letters are broken” — which makes the cause unusually hard for a beginner to pin down. The knack of diagnosis is narrowing down which link broke: open the source in hex (separating ① from ②), redirect the output to a file (separating ④), and the culprit appears.

18.4.1 Nailing down the source encoding (②) and the execution character set (③) for the compiler#

As chapter 8 showed, C treats the source character set and the execution character set as different things, and both are settled by the implementation. Compiler options let you state those implementation-defined choices yourself.

Knowing the defaults prevents accidents. GCC and Clang default to UTF-8 on both sides; MSVC defaults to the current system code page (CP949 on a Korean Windows). That single /utf-8 removes half the Windows-side trouble for this reason.

/* What bytes and values a literal actually becomes, layer by layer.
   The same source gives a different first line under different compile
   options (see the measured table in the text). */
#include <stdio.h>
#include <stddef.h>
#include <string.h>
#include <uchar.h>

static void dump(const char *tag, const char *p, size_t n)
{
    printf("  %-28s", tag);
    for (size_t i = 0; i < n; i++) printf(" %02X", (unsigned char)p[i]);
    puts("");
}

int main(void)
{
    const char    *plain = "\uAC00";   /* the literal encoding — implementation-defined */
    const char8_t *utf8  = u8"\uAC00"; /* always UTF-8 — the standard nails it down */

    puts("[the bytes of a string literal]");
    dump("\"\\uAC00\"   (literal encoding)", plain, strlen(plain));
    dump("u8\"\\uAC00\" (always UTF-8)", (const char *)utf8, strlen((const char *)utf8));

    puts("\n[the code units of a wide literal]");
    printf("  u\"\\uAC00\"[0] = U+%04X   (char16_t, UTF-16)\n",  (unsigned)u"\uAC00"[0]);
    printf("  U\"\\uAC00\"[0] = U+%04X   (char32_t, UTF-32)\n",  (unsigned)U"\uAC00"[0]);
    printf("  L\"\\uAC00\"[0] = U+%04X   (wchar_t, %zu bytes)\n",
           (unsigned)L"\uAC00"[0], sizeof(wchar_t));

    puts("\n[what the implementation says it guarantees]");
#ifdef __STDC_ISO_10646__
    printf("  __STDC_ISO_10646__ = %ldL  -> wchar_t is Unicode\n",
           (long)__STDC_ISO_10646__);
#else
    puts("  __STDC_ISO_10646__ undefined -> the wchar_t encoding is implementation-defined");
#endif
#ifdef __STDC_UTF_16__
    printf("  __STDC_UTF_16__    = %d      -> char16_t is UTF-16\n", __STDC_UTF_16__);
#endif
#ifdef __STDC_UTF_32__
    printf("  __STDC_UTF_32__    = %d      -> char32_t is UTF-32\n", __STDC_UTF_32__);
#endif

    puts("\n[the basic character set does not move]");
    printf("  'A' = %d, '0' = %d, sizeof \"A\" = %zu\n", 'A', '0', sizeof "A");
    return 0;
}

[the bytes of a string literal]
  "\uAC00"   (literal encoding) EA B0 80
  u8"\uAC00" (always UTF-8)    EA B0 80

[the code units of a wide literal]
  u"\uAC00"[0] = U+AC00   (char16_t, UTF-16)
  U"\uAC00"[0] = U+AC00   (char32_t, UTF-32)
  L"\uAC00"[0] = U+AC00   (wchar_t, 4 bytes)

[what the implementation says it guarantees]
  __STDC_ISO_10646__ = 201706L  -> wchar_t is Unicode
  __STDC_UTF_16__    = 1      -> char16_t is UTF-16
  __STDC_UTF_32__    = 1      -> char32_t is UTF-32

[the basic character set does not move]
  'A' = 65, '0' = 48, sizeof "A" = 2

The listing was run with the defaults. Rebuild the same source with different options and the first line of output changes. The measured results:

Two points stand out.

First, the same source file becomes a different program. Rows three and four are byte-identical files with different results. What separated them was whether the compiler was told “this file is EUC-KR”.

Second, a compiler that has the source encoding wrong usually raises no error. In row four the compiler believed the file was UTF-8, said nothing, and put the bytes into the executable as they were. The screen may even look fine by accident — if the terminal is CP949. The nastiest state of all is when all four links are wrong and the result still looks right, because it breaks the moment one machine or one person changes.

18.5 The debugger — stopping to look inside#

When a program gives a wrong answer, the first thing most people do is add a printf. That is not a bad method — it works anywhere and needs no preparation. But you have to know in advance where to print, you must recompile for each print, and what you get is only that variable at that moment.

The debugger removes those constraints. It stops the program at a point of your choosing, lets you look at every variable at that instant, walk one line at a time, and trace back the chain of calls that got you here. The standard tools are GNU’s gdb (GNU stands for “GNU’s Not Unix”) and LLVM’s lldb; only the command names differ.

The program we will use looks like this. The sum should be 150, but it comes out

#include <stdio.h>

static int sum_all(const int *a, int n) {
    int s = 0;
    for (int i = 0; i < n - 1; i++)   /* bug: stops one short */
        s += a[i];
    return s;
}

int main(void) {
    int data[5] = {10, 20, 30, 40, 50};
    printf("sum = %d (should be 150)\n", sum_all(data, 5));
    return 0;
}

sum = 100 (should be 150)

Here is what the debugger shows (captured from a run with gdb 16.3; four start-up lines — reading symbols, the program’s path, the thread-library notices — are left out).

$ gcc -std=c23 -g -O0 bug.c -o bug
$ gdb -q ./bug
(gdb) break sum_all
Breakpoint 1 at 0x1144: file bug.c, line 4.
(gdb) run
Breakpoint 1, sum_all (a=0x7ffe3018fe20, n=5) at bug.c:4
4     int s = 0;
(gdb) print n
$1 = 5
(gdb) next
5     for (int i = 0; i < n - 1; i++)   /* bug: stops one short */
(gdb) next
6         s += a[i];
(gdb) print a[4]
$2 = 50
(gdb) finish
Run till exit from #0  sum_all (a=0x7ffe3018fe20, n=5) at bug.c:6
0x00005622428f81bd in main () at bug.c:12
12      printf("sum = %d (should be 150)\n", sum_all(data, 5));
Value returned is $3 = 100

n arrived correctly as 5, the last slot of the array a[4] holds 50 intact, and yet the return value is 100. The inputs are right and the calculation is wrong, so the only place left is the boundary of the loop — i < n - 1. That process of narrowing down is what makes the debugger useful.

18.6 Debug-build options — -g and -O0 are different switches#

For the debugger to know variable names and line numbers, the compiler has to put that information into the executable. That is -g.

• -g — embeds debug info. Variable names, types, line numbers and function boundaries ride along inside the executable.
• -O0 — turns optimisation off. Source statements correspond almost one to one with machine instructions, so stepping and inspecting variables work as expected.
• -Og — optimises with debugging in mind. Faster than -O0 and far easier to inspect than -O2. A good default for debugging.
• -g3 — includes macro definitions too. Things like print MAX_LEN become possible.
• -fno-omit-frame-pointer — preserves a clue for tracing back the call chain. It also helps profilers and crash reports.

There is one switch related to assert (chapter 55). Pass -DNDEBUG and every assert disappears entirely — release builds are usually made that way. Erasing the checks means what was caught in the debug build passes silently in release, so a check that must not disappear should generally be written as an if, not an assert.

18.7 The debugger’s blind spot — optimised builds#

The trouble is the release build. Build the same program with -O2 -g and inspect it in the debugger, and this happens (again, a real capture).

$ gcc -std=c23 -g -O2 bug.c -o bug
$ gdb -q ./bug
(gdb) break sum_all
Function "sum_all" not defined.
(gdb) break main
Breakpoint 1 at 0x1040: file bug.c, line 12.
(gdb) run
Breakpoint 1, main () at bug.c:12
12      printf("sum = %d (should be 150)\n", sum_all(data, 5));
(gdb) info locals
data = <optimized out>

The function we were looking for is not there. The compiler spread sum_all out at the call site (inlining) and computed the sum of a constant array at compile time, so no such function remains in the executable. The array data likewise “was optimised out”. The compiler’s right as an editor, learned in chapter 14 — to rewrite code so long as its meaning is kept — here gets in the observer’s way.

The blind spots commonly met in optimised builds:

• <optimized out> — the variable lives only in a register, or not at all, and its value cannot be seen (the registers of chapter 12 come back into the story here).
• line numbers jump — stepping goes back and forth, as in 12 → 15 → 12. The compiler reordered the instructions, and the debugger is not lying but showing the real, shuffled order.
• the call chain is short — inlined functions and tail calls leave no frame on the stack.
• breakpoints do not hit — deleted code has nowhere to stop.

18.8 “It works in debug but is wrong only in release”#

One of the most vexing situations, and most cases come down to one cause — the program was already broken, and the debug build happened to be hiding it. Optimisation did not break sound code; the code relied on behaviour outside the contract (chapters 14 and 56), and only then did the symptom appear. The common roots:

• uninitialised local variables — under -O0 that stack slot happens to be 0 and all goes well; change the layout and garbage arrives.
• writes past a boundary — what lies beyond the boundary differs per build. A write that lands in spare space in the debug build can overwrite something important in release.
• optimisation premised on the outside of the contract — signed overflow does not happen (chapter 6), strict aliasing is respected (chapter 14), a pointer cannot be null after being dereferenced — such premises turn into real code transformations only at -O2.
• a polling loop missing volatile — exactly as in chapter 14: at -O0 it is read every time; at -O2 it is read once and then treated as unchanged.
• vanished asserts — -DNDEBUG removes the checks wholesale and bad input flows straight through.
• races revealed by changed timing — in a program running on several threads (chapter 13) faster code reorders things. Attach a debugger, it slows down and the symptom disappears: the classic Heisenbug.
• tiny differences in floating-point arithmetic — options of the -ffast-math family assume associativity and reorder, so the last digits can change (chapter 7).

18.9 Tools for when the debugger cannot be trusted#

There really are places where a debugger cannot be used or trusted — bugs that reproduce only in optimised builds, timing bugs that vanish the moment you attach, production environments where no debugger can be launched, and embedded boards with neither screen nor keyboard. The order of attack is roughly this.

1. Rebuild with -Og -g. The first attempt to regain visibility without turning optimisation fully off. If the symptom survives here, the debugger becomes usable again.
2. Turn on the sanitizers. The tools of the next section. They catch an accident at the moment it happens, so the cause of a release-only bug is usually found here. Importantly, they can be layered on the same -O2 as release.
3. Test a hypothesis with a flag. If turning on -fno-strict-aliasing makes the symptom vanish, you know the cause has to do with aliasing. But this is diagnosis, not treatment — once the cause is confirmed, fix the code.
4. Turn warnings and static analysis up to maximum. Beyond -Wall -Wextra, -fanalyzer (GCC) or clang --analyze catch things without running.
5. Leave logs and core dumps. In production these are the only window. If you built release with -g (see the misconception box above) you can open that dump in a debugger afterwards and trace the crash site back to source lines.
6. Narrow by bisection. Lower the optimisation level (-O2 → -O1 → -O0) to see where behaviour diverges, and halve the version-control history to find

when the bug entered (in git, git bisect does this; git is used in chapter 111).

1. Make a minimal reproduction. Reducing the problem to the smallest program that reproduces it often exposes the cause by itself, and turns it into something you can ask others about.

18.10 Sanitizers — a net cast while the program runs#

Modern C development has one more essential piece of equipment: a tool that catches accidents not at compile time but while running, the sanitizer.

The principle: give a special option at compile time and the compiler plants watch code throughout the program. Run that program and the watch code observes memory accesses and operations, and when something goes wrong it points at the scene at the moment it happens and stops the program. There are three main players.

• ASan (AddressSanitizer) — in charge of memory accidents. It catches, on the spot, the dangers we meet in Part VII: accesses past a boundary, touching freed storage again.
• UBSan (UndefinedBehaviorSanitizer) — in charge of contract violations. When undefined behaviour such as signed overflow (chapter 6) or a shift at least as wide as the type (chapter 6) actually happens at run time, it says so on the spot. It is the protagonist of chapter 56.
• TSan (ThreadSanitizer) — in charge of race accidents. It catches several cores (chapter 13) fighting over the same data. This book does not use TSan, but it is worth knowing by name (races themselves are the subject of chapters 94–95).

You turn them on with a single compile command:

$ cc -fsanitize=address,undefined -g hello.c -o hello
$ ./hello

(-g is the extra-information option that asks for the accident site to be reported as a source line.) A program built this way runs somewhat slower but does not pass over accidents quietly — these tools are the modern answer to chapter 6′s “overflow is silent”. Later in this book (Parts VII and IX), when we handle dangerous code, we will see the sanitizers catching accidents on the page several times.

18.11 What we have set up so far — the first program, the compilation process, the tools#

We read the first program (chapter 16), watched the relay that turns it into an executable (chapter 17), and equipped our desk with the tools and nets to run that relay (chapter 18). The preparation is done.

The next chapter closes this part with a guide: which C compilers, other than the gcc and clang we just installed, are still in active use (chapter 19). The tools embedded developers keep beside make and git are a wide enough subject that they wait until the end of the book (chapter 114). There is no need to install them all now — the aim is to know what a name refers to when you meet it some day.

From the next part on, the real study of the language begins — not a list of new syntax, but the goal of Part IV: reading chapter 16′s hello world completely, from start to finish.