17 Setting up a development environment

17.1 Only three things are needed

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

• A compiler — chapter 16′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 9), 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

17.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 17.1 — How a screen that shows one source line becoming several machine-code lines is laid out.

17.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 17.2 — Values as boxes, pointers as arrows — the picture a visualiser draws.

Visualising memory pays off most in Part VII (pointers and memory). What this book explained in pictures and words, you can move around yourself in code you wrote.

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

17.3 Warnings — leave the free review switched on

There is one habit to adopt immediately after installation: asking the compiler for generous 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.

17.4 When Korean text breaks — the chain of encodings

Here we note in advance a problem Korean-speaking readers almost always meet. 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 9). Whether the editor saved it as UTF-8 or as CP949 (the EUC-KR family, the old default on Korean Windows) makes the same “안녕” 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 (stage 5 of chapter 9; the conversion seen in the translation phases of chapter 57).
• ④ the encoding the terminal interprets — which table the window reads the program’s bytes with. 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.

17.4.1 Nailing ② and ③ down for the compiler

As chapter 9 showed, C treats the source character set and the execution character set as different things, and both are settled by the implementation. There are options that let a person state what “the implementation settles”.

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.

/* 리터럴이 실제로 어떤 바이트·값이 되는가 — 층을 갈라서 본다.
   같은 소스라도 컴파일 옵션에 따라 첫 줄이 달라진다(본문의 실측 표). */
#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 = "가";      /* 리터럴 인코딩 — 구현이 정한다 */
    const char8_t *utf8  = u8"가";    /* 언제나 UTF-8 — 표준이 못박는다 */

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

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

    puts("\n[what the implementation claims to guarantee]");
#ifdef __STDC_ISO_10646__
    printf("  __STDC_ISO_10646__ = %ldL  -> wchar_t is Unicode\n",
           (long)__STDC_ISO_10646__);
#else
    puts("  __STDC_ISO_10646__ not defined -> 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;
}

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

[code units of wide character literals]
  u"가"[0] = U+AC00   (char16_t, UTF-16)
  U"가"[0] = U+AC00   (char32_t, UTF-32)
  L"가"[0] = U+AC00   (wchar_t, 4 bytes)

[what the implementation claims to guarantee]
  __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 changes — measured, it runs like this.

Two things can be read out of it.

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, telling it wrongly 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. All four links wrong and the result looking right is the nastiest state of all, because it breaks the moment one machine or one person changes.

17.5 The debugger — stopping to look inside

When a program gives a wrong answer, the first thing most people do is plant 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 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)

Caught in the debugger it looks like this (really run with gdb 17.2).

$ gcc -std=c23 -g -O0 bug.c -o bug
$ gdb -q ./bug
(gdb) break sum_all
Breakpoint 1 at 0x1154: file bug.c, line 4.
(gdb) run
Breakpoint 1, sum_all (a=0x7fff5302c8a0, 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]
$3 = 50
(gdb) finish
Run till exit from sum_all (a=..., n=5) at bug.c:4
Value returned is $4 = 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 materials 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 the debugger’s usefulness.

17.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 exactly.
• -Og — optimises “only as much as remains good for debugging”. Faster than -O0 and far more visible than -O2. A good default for debugging.
• -g3 — includes macro definitions too. Things like print MAX_LEN become possible.
• -fno-omit-frame-pointer — leaves the thread for tracing back the call chain. It also helps profilers and crash reports.

There is one switch related to assert (chapter 51). Give -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.

17.7 The debugger’s blind spot — optimised builds

The trouble is the release build. Build the same program with -O2 -g and catch it, 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 = <optimised 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 editor’s rights, learned in chapter 13, appear here in the form of blocking the observer’s view.

The blind spots commonly met in optimised builds:

• <optimised out> — the variable lives only in a register, or not at all, and its value cannot be seen (chapter 11′s registers return here).
• line numbers jump — stepping goes 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.

17.8 “It works in debug but is wrong only in release”

The most vexing situation, and most of the causes converge on one — the program was already broken, and the debug build happened to be hiding it. Optimisation did not break sound code; code outside the contract (chapters 13 and 52) was taken as a premise, 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 sits in the overrun place differs per build. What overwrote spare space in the debug build overwrites something important in release.
• optimisation premised on the outside of the contract — signed overflow does not happen (chapter 7), strict aliasing is respected (chapter 13), 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 13: read every time at -O0, read once and frozen at -O2.
• 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 12) 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 8).

17.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 is on the aliasing side. 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 (chapter 96′s git bisect).

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.

17.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 7) or a shift at least as wide as the type (chapter 7) actually happens at run time, it says so on the spot. It is the protagonist of chapter 52.
• TSan (ThreadSanitizer) — in charge of race accidents. It catches several cores (chapter 12) fighting over the same data. Outside this book’s scope, but worth knowing by name.

Using them is one compile option:

$ 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 7′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.

17.11 Closing Part III

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

The next chapter is this part’s finish and a guide: which C compilers, other than the gcc and clang we just installed, are in active service in the world (chapter 18). What embedded developers carry beside make and git is a wide enough subject that it waits until the end of the book (chapter 97).

From the part after that, the real study of the language begins — not a list of new syntax, but the goal of Part IV: reading one piece of chapter 15′s hello world completely.