Forem: Valerius Petrini

How to Build a Compiler: A Step-by-Step Outline for Creating a custom compiler in C from scratch

Valerius Petrini — Wed, 20 Aug 2025 03:20:53 +0000

This article was originally published on Valerius Petrini's Programming Blog on 06/10/2025

Over the past year I've been working on my own programming language, Jakarta, a compiled language that I needed to build a compiler for. If you're unfamiliar with compilers, think of them as the thing that converts your programming language's code (in this case .jak files) into machine code that your computer can then run.

Building a compiler is a huge undertaking, and needs a lot of time and effort, especially if you are starting from scratch and not using something like LLVM to speed things up. Because of that, it's a good idea to have a step-by-step outline at the beginning to know what exactly you're doing. For something like Jakarta and many other compilers, the process is split into four basic parts: the lexer, the parser, the intermediate representation, and the assembler.

The Lexer

Think of the lexer as a tokenizer: it splits up your code into tokens to make it easier for the compiler to understand things.

Take this line:

function factorial(int n)

The tokens would fall into these categories:

Keywords: function
Identifiers: factorial, int, n
Symbols: (, )

Since Jakarta is written in C, our first step is to put everything into an array, splitting code into one of three token types:

Identifiers: things like variable, function, and type names
Symbols: punctuation and operators
Literals: values like numbers or strings

We can use a C enum to represent the type of each token, such as:

enum TokenType {
    TOKEN_KEYWORD_FUNCTION,
    TOKEN_SYMBOL_IDENTIFIER,
    TOKEN_STRING_LITERAL,
    TOKEN_NUMBER,
    TOKEN_OPEN_PAREN,
    TOKEN_CLOSE_PAREN,
    // etc.
};

To make debugging easier, we also store the line and column numbers of each token. This helps us report errors with helpful messages like “unexpected token on line 4, column 12.”

Here's an example of the line from earlier and what the outputted tokens look like (with line and columns omitted):

function factorial(int n)

Token: "function", Type: KEYWORD_FUNCTION  
Token: "factorial", Type: SYMBOL_IDENTIFIER  
Token: "(", Type: SYMBOL_OPEN_PARENTHESIS  
Token: "int", Type: SYMBOL_IDENTIFIER  
Token: "n", Type: SYMBOL_IDENTIFIER  
Token: ")", Type: SYMBOL_CLOSING_PARENTHESIS

We can take all this data and move to the parser, which makes sure that these tokens are in the right order.

The Parser

The parser is the section of the compiler that checks if all of the tokens are in the right order, and stores metadata about functions and variables.

The best part about our previous approach is it's really easy to check if our tokens are in the right order.

Take our highly used factorial function:

function factorial(int n)

If we find a KEYWORD_FUNCTION token, then we must expect a SYMBOL_IDENTIFIER (which is the name of the function), then an opening parentheses, then parameters (which includes the type and the name, and commas if there are multiple), and the closing parenthesis.

To do this, we can have two basic functions, peek and consume:

Token* consume(Tokenizer* tokenizer) {
    Token* content = get_from_array(tokenizer->tokens, 0);
    remove_from_array(tokenizer->tokens, 0);
    return content;
}

bool peek(Tokenizer* tokenizer, TokenType symbol) {
    Token* token = get_from_array(tokenizer->tokens, 0);
    return token->symbol == symbol;
}

peek checks if the next token is the correct type, and consume removes the token. We also have a peekConsume function that consumes the token if the peek function returns true.

Here are some other parts of the parser that help make sure everything is in order:

The Abstract Syntax Tree (AST)

The Abstract Syntax Tree is perhaps the largest part of the parser, as it handles converting the tokens from our lexer into a tree format. This tree structure filters out syntactic noise (like punctuation), leaving only the essential structure of the code.

The logic for creating the AST can be split into two parts: keywords and expressions. Keywords are exactly what they sound like, keywords like if and function that have predefined structures.

Take function as an example, we can have an AST setup like this:

Function Node
├ Name Node: factorial
├ Return Type Node: int
├ Parameters Node
│ └ Parameter Node: int n
└ Body Node: Contains All Child Nodes

All of the nodes within our function go into the Body Node into sequential order, so when we are doing our next step, we can read them in one by one and convert them into our Intermediate Representation.

On the other hand, expressions are the things that vary a lot. Expressions can be mathematical equations that you assign to variables, boolean expressions that you use in if statements, and things that you return from functions. Here are some examples:

10 + 20 * 4
n % 2 == 0 ? "Even" : "Odd"
"%s: %d".format(name, age)"

As you can see, expressions take on many different forms and can vary in how big or small they are. To handle these expressions, we use the shunting yard algorithm, which converts infix expressions (like a + b * c) into postfix (Reverse Polish Notation), making it easier to build a structured tree.

Here an example of 10 + 20 * 4 in our AST:

Binary Expression Node: +
├ Left: 10
└ Right: 
   Binary Expression Node: *
   ├ Left: 20
   └ Right: 4

We start from the bottom by doing 20 * 4 first, ensuring we can handle precedence.

Error Checking

Most error handling happens in the parser, as we are passing through the tokens to make sure they are in the right order. An example of this would be throwing an error if a variable name is declared multiple times, or if we use a keyword as an identifier. We can use the line and column number from the lexer here to make it easier for the developer to see what is happening.

Symbol Tables

Symbol tables are used to store all variables, function, and type data (Jakarta allows developers to create custom types). These are stored in a hashmap with the key being the name, and the value being a struct or object containing metadata of that variable/function/type.

We only need one hashmap for function and types as they can only be made in the top level scopes, but we need to take into account scopes for variables to implement shadowing and making sure we handle duplicates correctly. To do this, we can create a stack of hashmaps: when you enter a new scope, push a new hashmap to the stack, and add all variables there. When a scope is exited, pop the most recent scope.

For function parameters, we can add those to the same scope as the content of that function.

Type Checking

During the parser, we also go ahead and check if all of our types are correct. This includes things like checking to see if we assign the correct types to variables, and that any expressions within if statements resolve to a boolean.

By building the AST, we make it easier to move into the next portion of the compiler: the intermediate representation.

Intermediate Representation (IR)

The reason we have an Intermediate Representation (IR) is because each type of computer chip runs a different type of assembly language. For example, Intel x86 CPUs use a different instruction set than ARM chips used in smartphones. Instead of writing a completely separate code generator for each chip, we first translate our source code into an IR, and then convert that IR into the appropriate assembly based on the target architecture.

Think of the Intermediate Representation as a "global" assembly language (yes, we are making another language alongside our programming language). The goal is to get as close to assembly as possible without depending on any specific hardware.

To illustrate this, take the example of adding two and two in two different architectures:

; x86 Assembly
mov eax, 2     ; Move 2 into register eax
add eax, 2     ; Add 2 to eax

; ARM Assembly
mov r0, #2     ; Move 2 into register r0
add r0, r0, #2 ; Add 2 to r0, store result in r0

Although they’re different syntactically, the logic is similar — move 2 into a register, then add 2. So our IR could look something like this:

MOV REGISTER1 2
ADD REGISTER1 2

Each node in the Abstract Syntax Tree (AST) can be translated into these IR instructions. Once the IR is built and saved (often into a .ir or .jakir file), the next stage, the assembler, can detect the current architecture and generate the appropriate native machine code.

The Assembler

The assembler is one of the easiest parts of the compiler to explain. It takes the Intermediate Representation (IR) and generates assembly code based on the target architecture (like x86_64 or ARM). After that, the assembly is assembled into an .obj/.o (object) file, which contains the machine code instructions.

Depending on the compiler and build system, a separate tool called the linker may then be used to combine multiple .obj files and libraries into a single executable file (like an .exe on Windows). This final file is what you can run on your computer.

Conclusion

Although each compiler is built in a different way, these four steps cover the basics of compiler design, alongside all of the sub-steps.

Thanks for reading!

Building a Shell in C using fork and Process Management

Valerius Petrini — Wed, 20 Aug 2025 03:18:21 +0000

This article was originally published on Valerius Petrini's Programming Blog on 06/29/2025

If you've ever wanted to build your own shell (the program that lets you interact with your operating system using commands like git, ls, or node) in Linux using C, you'll quickly come across the function fork(). In Linux, fork() is what allows a shell to create new processes for the commands you run. It's how shells can execute programs without freezing or crashing themselves, and it's the foundation of multitasking in Unix systems.

What are Processes?

If you run ps in your Linux command line (or tasklist on Windows), you'll see a list of all the processes running on your computer, including the process ID (PID) for all of them. Each entry represents something actively running on your computer, like your web browser, games, or system processes. On Unix systems, every process except the very first one is created by fork() from a parent process. If you were to trace the process tree all the way up, you'd eventually reach a single initial process started directly by the kernel.

How fork works

fork() works by essentially duplicating the currently running process. For example, say you run the ls command, your shell would:

Duplicate itself using fork(), creating a parent and a child process.
The child gets a copy of the environment and a different PID (though fork() returns 0 in the child, and the child’s PID in the parent).
The child replaces its memory with the ls program using execvp().
The parent waits for the child to finish using waitpid().

This design is useful because if something goes wrong with ls, only the child is affected.

This is how that process would work in C:

pid_t pid = fork();
if (pid == 0) { // Child process
    execvp(args[0], args); // Run the given command (e.g., "ls")
    perror("exec failed"); // Only reached if exec fails
    exit(1);
} else if (pid > 0) { // Parent process
    // You'll want to track your jobs using an array
    add_job(pid)

    int status;
    waitpid(pid, &status, 0); // Wait for the child to finish
    printf(WIFEXITED(status) ? "Success\n" : "Failure\n");
} else {
    perror("fork failed"); // Handle fork error
}

Even though it looks like the code runs twice, it’s actually two separate processes executing the same code: one (the parent) receives the child’s PID from fork(), and the other (the child) receives 0.

Background Processes and Signals

Background processes run independently of the shell, allowing the shell to continue accepting new commands without waiting for those processes to finish. If we modify our previous C code and remove the waitpid call, the parent process continues immediately, while the child runs in the background. This is useful for long-running tasks like servers or background jobs.

However, if the parent never calls wait() or waitpid() on a child process, that child can become a zombie process once it finishes. A zombie process is a process that has completed execution but still has an entry in the process table because the parent hasn’t read its exit status. To avoid this, most shells handle the SIGCHLD signal, which is sent to the parent when a child process exits. The shell can then clean up by calling wait() inside a signal handler.

If we were to handle the signal ourselves in our custom shell, we would need to use the sigaction function provided by signal.h:

// This function is called automatically when a SIGCHLD signal is received.
// It reaps any child processes that have exited to prevent zombies.
void handleSigChild(int signum) {
    int status;
    pid_t pid;

    // Use a loop in case multiple children exited before the handler ran.
    while ((pid = waitpid(-1, &status, WNOHANG)) > 0) {
        // WIFEXITED: child exited normally
        // WIFSIGNALED: child was terminated by a signal
        if (WIFEXITED(status) || WIFSIGNALED(status))
            // Update your job status here if you track background jobs.
            // You should store jobs in an array and keep track of the PID and the state (foreground, stopped, background, etc.)
            jobData->status = DONE; // Replace this with your job-tracking logic
    }
}

struct sigaction sa_chld;

// Set the handler function for SIGCHLD
sa_chld.sa_handler = handleSigChild;
// SA_RESTART: restart interrupted system calls
// SA_NOCLDSTOP: don’t call handler when children are stopped (only when they exit)
sa_chld.sa_flags = SA_RESTART | SA_NOCLDSTOP;
// Clear the signal mask so no signals are blocked during handler execution
sigemptyset(&sa_chld.sa_mask);
// Install the signal handler
if (sigaction(SIGCHLD, &sa_chld, NULL) == -1) {
    perror("sigaction SIGCHLD");
    exit(1);
}

Shells use signals for a wide range of tasks, such as:

SIGINT (sent by pressing Ctrl+C) to interrupt a foreground process
SIGTSTP (sent by Ctrl+Z) to stop a foreground process
SIGCONT to resume a stopped process

You can find a full list of Unix signals and their meanings here.

Prompting the user

In order for our shell to actually be usable, we need to combine the previous two code segments and add a loop to prompt the user. Here's a basic structure that also implements background process handling:

void handleSigChild(int signum) { ... }

int main() {
    // setup sa_chld

    while (true) {
        printf(">>> "); 
        // Get input

        // You can implement a check to see if the input ends with &
        bool bg = input.endsWith("&");

        pid_t pid = fork();
        if (pid == 0) {
            // Parse input
            char* args[64];
            size_t arg_count = 0;
            char* token = strtok(input, " ");
            while (token != NULL && arg_count < 63) {
                args[arg_count++] = token;
                token = strtok(NULL, " ");
            }
            args[arg_count] = NULL;

            execvp(args[0], args); 
            perror("exec failed");
            exit(1);
        } else if (pid > 0) {
            int status;
            if (!bg) {
                waitpid(pid, &status, 0);
                printf(WIFEXITED(status) ? "Success\n" : "Failure\n");
            } else {
                printf("Child started in background");
            }
        } else {
            perror("fork failed"); // Handle fork error
        }
    }
}

With this code, we have a basic working shell that can run foreground processes. Of course, if you're making your own shell, make sure to make this memory safe by checking for NULL and by freeing memory when necessary to avoid memory leaks.

Next Steps

If you want to continue building out your shell, you'll want to do a few more things before it's ready:

Try experimenting with different exec variants like execlp.
Handle builtin commands, like cd, exit, and jobs. These can't be run by execvp so you'll need to handle them yourself
Handle Ctrl-Z, which stops a foreground process.
Implement piping with |, where the output of one command is the input for another. To implement piping, you'll need to use pipe() and dup2() to redirect output from one command to the input of another.

Gist

If you'd like a minimum working shell to test yours against or to follow along, you can visit my Github page where I have a gist that implements an entire shell with job control.

Happy coding!

CMake Made Simple: A Reusable Template for Your First C++ Project

Valerius Petrini — Wed, 20 Aug 2025 03:13:17 +0000

This article was originally published on Valerius Petrini's Programming Blog on 08/05/2025

When starting up a new C++ project, you might run a command using your compiler like g++ main.cpp -o main to compile your program into an executable. However, as your project grows and includes more source files, libraries, and dependencies, managing compilation from the command line can become tedious and prone to errors.

This is where CMake comes in. CMake is a cross-platform build system generator that helps automate and organize the compilation of your C++ projects. Instead of writing shell commands by hand, you can write a CMakeLists.txt file, and CMake will generate build scripts for you. After that, you can use a tool like Ninja or Make to run the generated build scripts and produce your executable.

Here are some reasons why CMake is a great tool for working with C++:

Incremental Builds - Only changed files are recompiled, saving development time.
Dependency Management - Easily include external libraries using find_package or FetchContent.
Out-of-Source Builds - Keeps the source directory clean by placing build files in a separate directory.
IDE Support - Editors like VSCode and IDEs like Visual Studio support CMake and offer features like IntelliSense, code navigation, and integrated debugging
Multi-Language Support Although this article will go over C++, CMake supports multiple different languages, like C, C#, and CUDA

Note: This guide assumes you're already familiar with basic C++ syntax (e.g., headers, main(), and compilation with g++). If you're completely new to C++, I recommend starting with a beginner course like Learncpp.com (Chapters 0 through 2 should teach you the fundamentals you need to follow along with this guide).

Once you're comfortable with the basics, learning CMake is a great next step to save time and avoid frustration down the road. It’s also an excellent way to get started on your first large-scale C++ project.

Creating a CMakeLists.txt template

To start with your project, you'll need to do a few things:

Install cmake and Ninja.
- On Windows, download the binaries from the cmake and Ninja websites. After that, add the executables to your PATH.
- On Linux, install them by running the corresponding command through your distro's package manager. For example, on Ubuntu-based distribution the command is sudo apt install cmake ninja-build
Create a new project directory and set up the following structure:
- You should have a main.cpp file in src, along with a test.cpp file in test.
- Add an include directory that will hold all hpp files.
- Add two more files, a CMakeLists.txt and a Makefile.
- You'll include a simple Makefile that wraps Ninja commands (e.g., make build runs ninja). This is optional and not a traditional build Makefile, but just a convenience wrapper.

Once you're done with those steps, your directory tree should look like this:

your_project/
├── CMakeLists.txt
├── include/
│   └── your_headers.hpp
├── src/
│   └── main.cpp
├── test/
│   └── test.cpp
└── build/      <-- created when you run cmake to configure your project

If everything looks good, we can begin creating our CMakeLists.txt file.

Basic CMakeLists.txt header

Open your CMakeLists.txt and start with these few lines:

cmake_minimum_required(VERSION 3.10)
project(MyProject VERSION 0.1 LANGUAGES CXX)

set(EXEC_NAME "EXECUTABLE")
set(EXEC_NAME_TEST "EXECUTABLE_TEST")

In your project, rename MyProject and EXECUTABLE to your project name
Additionally, C++ is written as CXX in CMake

The first two lines are metadata on the project. The first sets what version of CMake we need, and the second gives info about our project, like the name, version, and languages it uses.

The next two variables define the names for the main and test executables.

After that, we have a few more variable assignments:

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)

CMAKE_BINARY_DIR corresponds to build in this case, as that is where all the build files go. Alongside that, CMAKE_CURRENT_SOURCE_DIR is the absolute path of the directory that the CMakeLists.txt file is in.

The first two lines have to deal with the C++ version we are using, specifically forcing C++ 17 be used. After that, we make it so that all of our executables are put inside build/bin by overriding CMAKE_RUNTIME_OUTPUT_DIRECTORY, to keep them separate from the other build files.

Next, the final two lines of our setup are:

file(GLOB_RECURSE SOURCES CONFIGURE_DEPENDS "src/*.cpp")
file(GLOB_RECURSE SOURCES_TEST CONFIGURE_DEPENDS "src/*.cpp" "test/*.cpp")

GLOB will take all of the files provided and put them all into one variable, here named SOURCES and SOURCES_TEST. This is helpful as instead of having to declare all of our files individually, we group the all together using the * wildcard.

Additionally, since we use CONFIGURE_DEPENDS, every time we recompile our project, it will detect new files added.

You might also be wondering why we are including all of our source files in our test sources. That's because our test files depend on the compiled implementations of our main code defined in src/.

Creating the executable

The next section is where we actually create the executable.

For simplicity’s sake, I will be excluding all code relating to the test directory, although it is identical to the main executable, except with all the names changed.

Here’s the short snippet:

add_executable(${EXEC_NAME} ${SOURCES})
target_include_directories(${EXEC_NAME} PRIVATE include/)
target_compile_options(${EXEC_NAME} PRIVATE -Wall -Wextra -fdiagnostics-color=always -g)

The first line adds all of the source files into our executable, while the second tells the compiler where to find all the header files. target_include_directories will tell our compiler that all the hpp files in our project are located in the include/ directory.

The last line is more of a configuration line. target_compile_options allows us to specify what special things we want the compiler to do, and in this case we do 4 things:

-Wall and -Wextra: These enable more warnings, making sure our codebase is clean and organized.
-fdiagnostics-color=always: Ensures our errors and warnings have colors assigned to them (red for errors and purple for warnings) so they are easy to differentiate at a glance.
-g: This adds debug information to our code, like memory addresses of variables, so that we can use debuggers like gdb.

After that last line, we have a functional CMakeLists.txt, but we can still do some more optimizations.

Optimizing target_compile_options

When we actually finish our program and plan to publish it, all of the compiler options we specified are unnecessary. Warnings and colorized output are helpful during development, but unnecessary in the final executable. Additionally, using -g will bloat our executable with data the end user will never see.

On top of that, certain compiler options should be added if we are building to publish, like the -O3 flag. This enables more compiler optimizations, so our executable will run much faster, but we don't want to add that flag while debugging because it would slow down our development process.

To counter this, we can use CMake conditional statements:

target_compile_options(${EXEC_NAME} PRIVATE
    $<$<CONFIG:Debug>:-Wall -Wextra -fdiagnostics-color=always -g>
    $<$<CONFIG:Release>:-O3>)

This makes it so that if we are in debug mode, we activate all the debugging options, but if we are in release mode, we enable the compiler's highest optimization level to improve performance. Later on, we'll go over how to switch between the two.

Cutting out repetition

If you've been following along, you should have executable code that looks something like this:

add_executable(${EXEC_NAME} ${SOURCES})
target_include_directories(${EXEC_NAME} PRIVATE include/)
target_compile_options(${EXEC_NAME} PRIVATE
    $<$<CONFIG:Debug>:-Wall -Wextra -fdiagnostics-color=always -g>
    $<$<CONFIG:Release>:-O3>)

add_executable(${EXEC_NAME_TEST} ${SOURCES})
target_include_directories(${EXEC_NAME_TEST} PRIVATE include/)
target_compile_options(${EXEC_NAME_TEST} PRIVATE
    $<$<CONFIG:Debug>:-Wall -Wextra -fdiagnostics-color=always -g>
    $<$<CONFIG:Release>:-O3>)

As you can probably tell, our target_compile_options takes up a large amount of space, for what amounts to the same exact code.

Thankfully, CMake gives us a way to deal with this by extracting that code into its own library.

Insert this code after defining your source files (e.g., after file globbing), but before the executables:

add_library(common_flags INTERFACE)
target_compile_options(common_flags INTERFACE
    $<$<CONFIG:Debug>:-Wall -Wextra -fdiagnostics-color=always -g>
    $<$<CONFIG:Release>:-O3>)

This defines a new library, common_flags, which contains all of the flags. With this, we can replace the target_compile_options in our executable generation code with this:

target_link_libraries(${EXEC_NAME} PRIVATE common_flags)
target_link_libraries(${EXEC_NAME_TEST} PRIVATE common_flags)

Importing Libraries

This topic is a bit more advanced and totally optional, but if you ever want to use other libraries, CMake can do this too. If you're not interested in this or just want to see how to actually run your file, you can skip to the Makefile chapter.

Boost is a popular library that defines a lot of helper functions alongside helpful tools for users. For this example, let's say we need to check if a file exists, so we decide to use Boost Filesystem module.

The first step is to download Boost. On Linux, you can install the package libboost-all-dev using your package manager. On Windows (assuming you are using MSYS2), you will need to follow these steps:

Launch MSYS2 MinGW UCRT64 which comes with MSYS2.
Run pacman -S mingw-w64-ucrt-x86_64-boost in the terminal.

Once that is done, you'll need to add this code somewhere in the setup section:

find_package(Boost REQUIRED COMPONENTS filesystem)

This will find the package from MSYS2 and register it in CMake.

At this point, all we need to do is link against the library:

target_link_libraries(${EXEC_NAME} PRIVATE common_flags Boost::filesystem)
target_link_libraries(${EXEC_NAME_TEST} PRIVATE common_flags Boost::filesystem)

The find_package() and target_link_libraries() works for many other libraries, not just Boost.

Here's a small snippet showing what a main.cpp file would look like:

#include <boost/filesystem.hpp>
#include <iostream>

int main() {
    boost::filesystem::path p("example.txt");
    if (boost::filesystem::exists(p))
        std::cout << p << " exists.\n";
    else
        std::cout << p << " does not exist.\n";
    return 0;
}

After that, the filesystem code should be ready for you to use.

Makefile

With our CMakeLists.txt file finished, its finally time to run our code.

For those unfamiliar, with Makefile, we can use it to simplify commands. Take this basic Makefile:

.ONESHELL:

ifeq ($(OS),Windows_NT)
    EXE := .exe
    SEP := \\
    EXEC_PREFIX :=
else
    EXE :=
    SEP := /
    EXEC_PREFIX := ./
endif

setup:
    cmake -S . -B build -GNinja -DCMAKE_BUILD_TYPE=Debug

build:
    cmake --build build --config Debug -- -j4

run: build
    @echo Running main executable...
    "${EXEC_PREFIX}build$(SEP)bin$(SEP)EXECUTABLE$(EXE)"

Be sure to change EXECUTABLE to the name of your executable file

The first line, .ONESHELL: is to make sure all the commands run in one confined shell instead of each command in it's own. This is a Make feature that prevents issues with environment changes (like the current working directory) between lines. The ifeq statement is then used to define some of the differences between Linux and Windows, like file separators and whether or not executable files end in .exe.

After that, we have three commands, setup, build, and run.

setup creates all of the build files. It should be run once when CMake is first initialized. Additionally, we can change Debug to Release to change the flags we defined earlier.
build will compile our code into the executable. The -j at the very end specifies to split the command into 4 separate jobs, so that it can execute the build faster. The number can be changed depending on how many cores your CPU has.
run will compile the code by first running build, then running the executable found in build/bin

In order to actually run these commands, you would write these commands, depending on your platform:

Linux:
make setup
make run

Windows:
mingw32-make setup
mingw32-make run

Note that mingw32-make should come with MSYS2, but if it's not preinstalled you'll need to install it, preferably by running pacman -S mingw-w64-x86_64-make

Once you run make run, your program's output should appear in the terminal.

Final thoughts and Gist

By now, you should have a general understanding of CMakeLists.txt and Makefile. Now that you've done all the setup, you're free to code as much as you want without having to worry anymore about configuration.

Additionally, you can find a GitHub Gist with a CMakeLists.txt template alongside a much more complete Makefile here.

OpenGL Meets Calculus: The Math Behind Normal Maps

Valerius Petrini — Wed, 20 Aug 2025 03:11:28 +0000

This article was originally published on Valerius Petrini's Programming Blog on 08/18/2025

In OpenGL, you're bound to come across normals, which are vectors that define how light reflects off of an object. Normals are usually defined per-vertex or per-face in 3D models, but normal maps are used to simulate small details on surfaces by giving each pixel a normal vector. While normal maps are commonly used in graphics applications like OpenGL, the details behind how it works is often hidden behind shader logic that transforms the normal vectors from texture space to the coordinate space for lighting calculations. This article aims to explain what normals are, how they are calculated, and how normal maps are generated.

What is a normal vector?

Normal vectors are essentially vectors that are perpendicular to the surface of an object at a specific point. If you had a flat plane resting on the xy plane, the normal vector would be pointing up in the positive z direction.

Although $y$ is considered "up" in OpenGL, for simplicity’s sake we will use $z$ as up.

Normals in OpenGL are used to define how light reflects off of an object. The direction of the normal is used to calculate direction that the light travels after bouncing off a surface. Normals are useful in OpenGL because they allow us to create a sort of fake depth to objects without changing their geometry by adding new vertices. Take a brick wall for example; instead of extruding the mortar sections of the brick wall, we can just define the normal values for each pixel.

Calculating a 2D Normal

Normal vectors in 2D space are incredibly easy to find. Let's take this function and its derivative:

f(x)=4x^3 - 3x^2

f'(x)=12x^2 - 6x

If you recall from calculus, the derivative allows us to get the line tangent to a function. In order to get the normal slope ( $m$ ), we can get the negative reciprocal of our derivative.

\frac{-1}{f'(x)}

After we have the slope for our point, we can write the normal vector as

\vec{n} = \langle 1, m \rangle

The $1$ is just a simple way to represent the $x$ -component, while $m$ gives the corresponding $y$ -component based on the slope. We then normalize the vector to make it a unit normal. The direction of the vector encodes the orientation of the surface at that point, while its length doesn’t matter once it’s normalized.

Alternatively, you can also write the vector as

\vec{n} = \langle -f'(x), 1 \rangle

(rotating by 90°).

In Graphics Programming, "Normalizing" a vector means making its magnitude 1. You can do that by finding the magnitude of the vector $∣∣n⃗∣∣||\vec{n}||$ ( $x2+y2\sqrt{x^2 + y^2}$ for 2D, $x2+y2+z2\sqrt{x^2 + y^2 + z^2}$ for 3D) and dividing each component of the vector by that magnitude.

For example, the normalized vector of $n⃗=⟨x,y,z⟩\vec{n} = \langle x, y, z \rangle$ would be

n^=⟨x/∣∣n⃗∣∣,y/∣∣n⃗∣∣,z/∣∣n⃗∣∣⟩ \hat{n} = \langle x / ||\vec{n}||, y / ||\vec{n}||, z / ||\vec{n}|| \rangle

For example, at $x = 1$ :

f'(1) = 12(1)^2 - 6(1) = 6

-\frac{1}{6}

\vec{n} = \langle 1, -\frac{1}{6} \rangle

And then normalizing it:

||\vec{n}|| = \sqrt{1^2 + (-\frac{1}{6})^2} = \sqrt{\frac{37}{36}} \approx 1.014

n^=⟨11.014,−1/61.014⟩ \hat{n} = \langle \frac{1}{1.014}, \frac{-1/6}{1.014} \rangle

Calculating a 3D Normal

When we go into three dimensions, calculating the normal gets a bit more challenging, as now we have two separate variables, $x$ and $y$ . Because of this, the slope isn't going in one direction per point, so we need to use partial derivatives to solve for them. Like a vector, we need to split the slope into the $x$ and $y$ direction.

f(x,y) = 3x^2 + 4y^4

\frac{\partial f}{\partial x} = 6x

\frac{\partial f}{\partial y} = 16y^3

Now we have two tangent lines representing the slopes of both the $x$ and $y$ directions. To find the normal, we can convert these two tangent lines into vectors and find the cross product of those two values.

\vec{T}_x = \langle 1, 0, \frac{\partial f}{\partial x} \rangle = \langle 1, 0, 6x \rangle

\vec{T}_y = \langle 0, 1, \frac{\partial f}{\partial y} \rangle = \langle 0, 1, 16y^3 \rangle

\vec{n} = \vec{T}_x \times \vec{T}_y = \langle -6x,-16y^3,1 \rangle

Additionally, recall that there are two possible vectors that can be perpendicular to $T⃗x\vec{T}_x$ and $T⃗y\vec{T}_y$ : $⟨−6x,−16y3,1⟩\langle -6x,-16y^3,1 \rangle$ and $⟨6x,16y3,−1⟩\langle 6x,16y^3,-1 \rangle$ . For this example we will use the first one as it points upward (positive $z$ ), but the second can also be used based on use case. The reason we use 1 in the vectors is just to provide a reference in the $x$ or $y$ direction so the tangent vector has a defined direction.

In fact, we can use this fact by using another method. Instead of calculating the cross product, we can instead calculate the gradient. We can first rewrite $z = f (x, y)$ as an implicit function.

F (x, y, z) = f (x, y) - z = 0

\nabla F = \langle \frac{\partial F}{\partial x}, \frac{\partial F}{\partial y}, \frac{\partial F}{\partial z} \rangle = \langle 6x, 16y^3, -1 \rangle

The reason we can use gradients for this is that we convert our function into an implicit function that is a level surface. The surface is only made up of $(x, y, z)$ points that satisfy $F (x, y, z) = 0$ . Moving along the surface does not change $F$ , so any vector tangent to the surface produces zero change in $F$ . By definition, the gradient of $F$ points in the direction of the greatest change, which is perpendicular to all the tangent vectors, making it the normal vector.

That normal vector points downwards, so to make it go up we can multiply by negative one.

\vec{n} = -1 \times \langle 6x, 16y^3, -1 \rangle = \langle -6x,-16y^3,1 \rangle

In that case, when we have two partial derivatives for $x$ and $y$ , we can write an equivalence:

-\nabla F = \langle 1, 0, \frac{\partial f}{\partial x} \rangle \times \langle 0, 1, \frac{\partial f}{\partial y} \rangle

After that, you should normalize the vector as usual to get the unit vector.

Creating Normal Maps

When creating normal maps for textures in video games, it usually begins with a heightmap, a grayscale image where white (#FFF) corresponds to the highest point of that texture, and black (#000) corresponds to the lowest point. Take this brick wall found from freepbr.com:

The heightmap of this texture would be this:

Here, the mortar sections of the wall appear more inset than the bricks themselves.

We need the heightmap so we can find the normal using the gradient at each point, we can convert those into RGB values and create a normal map.

In spite of this, we run into an issue very quickly. In our examples, we always had continuous functions like $3x^2 + 4y^4$ and $4x^3 - 3x^2$ , but our heightmap doesn't have a specific function we can use.

To circumvent this, we can get the "local" derivative by using our definition of a derivative:

\lim_{h \to 0} \frac{f(x + h) - f(x)}{h}

\lim_{h \to 0} \frac{f(y + h) - f(y)}{h}

Since we can't have $h$ be 0 in our code, we need to use a small number for $h$ and approximate the derivative using the central difference approximation:

h = 1

\approx \frac{f(x + h) - f(x - h)}{2h}

\approx \frac{f(y + h) - f(y - h)}{2h}

We use 1 for $h$ as we are using the next and previous pixel value for our calculations.

In GLSL, that would look something like this:

// Assume 'heightMap' is a sampler2D containing the grayscale heightmap
// 'texCoords' are the texture coordinates for the current fragment
// 'texelSize' is vec2(1.0/width, 1.0/height) of the texture

vec3 computeNormal(vec2 texCoords) {
    // This won't work for pixels on the edge of the screen.
    // In that case, you'll want to use forward and backward difference approximations.
    // Additionally, as our texture is grayscale, r, g, and b 
    // have the same value, so we can get any one of them
    float hL = texture(heightMap, texCoords - vec2(texelSize.x, 0.0)).r;
    float hR = texture(heightMap, texCoords + vec2(texelSize.x, 0.0)).r;
    float hD = texture(heightMap, texCoords - vec2(0.0, texelSize.y)).r;
    float hU = texture(heightMap, texCoords + vec2(0.0, texelSize.y)).r;

    // Central differences
    // You can multiply these by a height scale factor to exaggerate the bumps
    float dX = (hR - hL) * 0.5;
    float dY = (hU - hD) * 0.5;

    // Construct normal vector
    vec3 normal = normalize(vec3(-dX, -dY, 1.0));

    // Map from [-1, 1] to [0, 1] for RGB
    // GLSL expects a value from 0 to 1 for RGB values,
    // but if you're exporting to an image, you need to
    // multiply by 255 in order to get RGB values from 0 to 255
    return normal * 0.5 + 0.5;
}

If we did write to an image, it would look something like this:

Final Thoughts

When our normal map is done, we can finally use it in our code. If you want to experiment more, try implementing forward and backward difference approximations in the GLSL code.

Happy Coding!