DEV Community: Richard

Generating random floats

Richard — Fri, 09 Oct 2026 12:41:29 +0000

We've already hand-rolled our own RNG in a previous article, to improve on what the C standard library rand() gives us.

We also talked about how floats work.

In this article, I want to combine the two. I want to find out how we can generate random floating-point numbers between 0 and 1, and improve our rng.c library.

The naive way

We already created an rng_f() function when we set up the rng.c library. But it generates random floats by dividing a random int by the max:

float rng_f(void) {
  return pcg32_random_r(&pcg32_global) / (UINT32_MAX + 1.0f);
}

This approach has a small bug. We want to generate in the range of [0.0, 1.0) so we want to get arbitrarily close to 1.0, but never hit it.

Because of rounding, there is actually a chance that we hit 1.0.

About 1 in 33.5 million. Any random integer of 2^32 - 128 or above rounds up to 2^32 when it's converted to a float, and 2^32 / 2^32 is exactly 1.0. This seems insignificant, but we were already generating millions of random numbers. The chance of it happening is quite high in that situation.

Looking at float bits

Let's reflect back on how floats work in memory.

The mantissa (23 bits) can get you from a base number all the way up to (but not including) double that base number.

This means that the smallest "step" we can take from a certain float depends on the size or exponent of the float. Floats close to zero have very tiny granular steps. Large floats have a larger step size:

For example, the number 1.0 has the exponent 01111111 (127) with the mantissa set to all zeros:

00111111 10000000 00000000 00000000

The closest float before hitting 2.0 has the same exponent as 1.0, but with the mantissa fully maxed out (all 1s):

00111111 11111111 11111111 11111111

So when we randomise the mantissa bits, we can get a random float. As long as we keep the exponent bits constant, we know we have a consistent step size.

Randomising the 23 mantissa bits

In the article on how floats work, we explored what the bits of a float mean, and how we can flip them.

If we have an RNG that gives us some random bits, we can use them to randomise our float bits.

So if we want to randomise the 23 mantissa bits of the float, this is how we can do that:

typedef union {
  float f;
  uint32_t u;
} Bits;

Bits bits = {0};

bits.u |= rng_u() >> (32 - 23);

Here, we use the union trick to be able to access float memory as if it's an integer. This allows for bitwise operations. Then we take a random 32-bit integer from rng_u(), and shift it 9 places to the right (32 - 23). This shift zeroes out the top 9 bits, so the OR only sets mantissa bits and leaves the sign and exponent bits of the float alone.

If you start at the number 0, and you randomise the mantissa bits, you get a random range between 0.0 and about 1.18 × 10⁻³⁸. That's 37 zeros after the decimal point! These tiny values are called subnormal numbers.

Not very practical for our target range of [0, 1) I reckon. This is because of that variable resolution that we get in floats.

If we start with the number 0.5 though, and randomise the mantissa, we achieve a range of [0.5, 1.0). That's starting to look more like it.

But starting at 0.5 gives us a total "range length" of 0.5 (1 - 0.5 = 0.5). The target range of 0 to 1 has a length of 1. So what if we start from 1?

Then the range becomes [1, 2). So we get the desired length of the range; it's only shifted up by 1. If we then subtract 1, we land exactly in range [0, 1). This is what that looks like in C:

Bits bits = {.f = 1.0f};
bits.u |= rng_u() >> (32 - 23);
bits.f -= 1.0f;

We start from a base of 1.0f. Then randomise the lowest 23 bits (mantissa bits) to vary our range between 1 and 2 (not including 2). Finally we subtract 1. That subtraction is exact: no rounding happens, so every value lands precisely in [0, 1).

Now we have a very efficient way to turn a random 32-bit int into a random 32-bit float between 0 and 1.

But we can do better.

Doubling the resolution

Let's take a closer look at the structure of a float.

We want equally spaced out floats in the range of 0 to 1. This is not trivial, because if you consider ALL floats between 0 and 1, you get a large variety of step sizes, as we saw in the drawing above.

The steps close to 0.0 are a lot more fine-grained than the steps close to 1. So which step size do we choose? We choose the smallest one that works everywhere between 0 and 1. That means we should choose the step size of the range [0.5, 1).

Because if you go down the exponent, closer to zero, you keep dividing by 2. So the step size between [0.25, 0.5) is half the step size of [0.5, 1). This is fine; we just have to pick every other step between [0.25, 0.5) to stick to a constant step size. Same for the range below that, [0.125, 0.25), we pick every 4th step, and so on.

So what does this mean? The step size we can take is the smallest increment within the [0.5, 1) range. We can calculate that by manipulating bits:

Bits bits = {.f = 0.5f};
bits.u += 1;
float step_size = bits.f - 0.5f;
printf("step size: %.10f (%a)", step_size, step_size);

This gives us an ideal step size of around 0.0000000596, or more exactly 0x1p-24, so 1 * 2 ^ -24.

What is the step size we're currently using when we generate floats using the random mantissa and subtract 1 method?

That step size is twice as big, because we're generating a float between [1, 2), which is the next level up from [0.5, 1).

So although that method works, we're throwing away half of our possible floating-point numbers between 0 and 1 that we could have had.

Instead of 23 bits of randomness, we could add a 24th bit and double our resolution.

How can we do this? We could go back to starting from 0.5, randomising the mantissa to get the range [0.5, 1). And then with 50% chance, subtract 0.5f from that. That could definitely work, but there is a much simpler and more boring solution that we'll explore next.

Back to basics

We looked at the ideal step size for the range of random numbers to pick from between 0 and 1. This turned out to be the number 2^-24 or 1 / 2^24.

We've also seen how we can generate 32 random bits, and take 23 of them to randomise bits in a float.

What if we took an extra random bit, 24 in total? This gives us an integer range of [0, 2^24). The 2^24 is not included, because if you have 24 bits maxed out (all 1s), it equals 2^24 - 1.

We can recognise that 2^24 / 2^24 = 1, obviously. And since we don't quite reach 2^24, we get (2^24 - 1) / 2^24 which is almost 1 (one step below 1). You might also realise that if we divide the integer value of our 24 random bits by 2^24, we end up in our desired range of [0, 1).

Dividing by 2^24 is the same as multiplying by 2^-24 (our step size). Your compiler turns either one into the same multiplication, but writing it as a multiplication makes the step size explicit. So now it all comes together. Since the step size of our integer range is 1, if we multiply by 2^-24, this is the new step size.

So the improved method for converting a 32-bit integer to a 32-bit float in range [0, 1) becomes:

// Generate 24 random bits
uint32_t bits = rng_u() >> (32 - 24);

// Multiply by the smallest step size to generate a float between 0-1
float f = bits * 0x1.0p-24f;

That's all. And it fixes the bug from earlier: every 24-bit integer fits in a float exactly, so the conversion never rounds, and the result can never reach 1.0.

This magical-looking 0x1.0p-24f is hexadecimal float notation (added in C99). It allows us to specify an exact float value.

The start 0x means we're about to write a hexadecimal number. The 1.0 is the mantissa in hex format (but in decimal format 1.0 is the same). And finally p-24 means "times 2 to the power of -24" (p instead of e, because e is a hexadecimal digit). The exponent is written in decimal, and it's always a power of 2. It ends with an f to make sure it's a 32-bit float and not a 64-bit double.

Tucking it into the library

With this method of converting 32 random bits to a clean float in [0, 1), let's integrate it into our rng.c library.

This is what our random integer function looks like:

static inline uint32_t rng_u(void) {
  return pcg32_random_r(&pcg32_global);
}

Let's create an rng_f() function in the same vein:

static inline float rng_f(void) {
  return (pcg32_random_r(&pcg32_global) >> 8) * 0x1.0p-24f;
}

Instead of calling rng_u() we call pcg32_random_r directly. The compiler would inline rng_u() anyway, but this keeps the two functions symmetrical.

And we shift 8 bits. That's like saying "discard the 8 lowest bits", so we're left with 24 bits.

And that's it! You can check out the code in the rng.c repo. If it looks a bit different by the time you read this, that might be because I've improved some things :)

Originally published at vanderoost.com.

Related

Hacking floats to learn how they work

Richard — Fri, 02 Oct 2026 12:00:20 +0000

In this article I want to explore floating-point numbers (floats). Floats are a bit more complicated than integers. It's quite easy to convert a bunch of bits to an (unsigned) integer, but for floats this is not trivial.

Writing C

I don't always write C, but when I do, I tend to find myself learning how things work.

In other languages, it's a lot more common to just import modules for everything. In C, it's more conventional to "write it yourself". Write your own string library, write your own data structures, etc.

It might not be the fastest way to get things done, but if your goal is to learn, coding in C is very effective.

So what I want to do is try to reverse engineer floats in C: Create some floats, look at what their bits in memory look like, and figure out what does what.

How many bits?

If we want to know what the bits of a float look like in memory, we first need to know some very basic information: how many bits make a float?

The way to get the number of bytes is by using sizeof:

size_t float_bytes = sizeof(float);

printf("a float has %zu bytes\n", float_bytes);

This prints a float has 4 bytes on my system (and it will on most systems). There are 8 bits per byte, so a float has 4 * 8 = 32 bits.

Accessing bits of integers

In C you can do bitwise operations to access individual bits. But this only works with integers.

This is how you can access the first (lowest) bit of an unsigned integer called u:

uint32_t u = 123;
uint32_t bit = u & 1u;

printf("bit: %u\n", bit);

I'm using the type uint32_t here. This is an unsigned 32-bit integer. Unsigned integers are the easiest to convert from binary to decimal as we don't have to worry about the sign. And it's 32 bits, the same size as a float. This will become relevant later.

We're using the bitwise operator & (AND), which compares two integers bit by bit, and returns a third integer bit by bit (or bitwise).

So if you do a & b and b is the number 1, which corresponds to 00000000 00000000 00000000 00000001 in binary, you're basically only focusing in on the first (smallest, rightmost) bit, masking out the rest. If the smallest bit of a is a 0, the result is 0; if it's a 1, the result is 1.

Ok, so how do you access the other bits?

If you do a bitwise AND with the second bit:

00000000 00000000 00000000 00000010

You will focus on the second bit, but you will get back either a 0, or the value of that bit (2).

This second bit corresponds to 2 in decimal, so you can do an & 2 on it:

uint32_t u = 3;
uint32_t bit = u & 2;

printf("bit: %u\n", bit);

But this returns a 2.

If we just want to get back a 0 or a 1, we can instead shift the number to move the bit we want to see to the lowest place, and then AND it with a 1.

So if we want to get the second bit, we do this:

uint32_t u = 3;
uint32_t bit = (u >> 1) & 1;

printf("bit: %u\n", bit);

This now returns a 1 instead of a 2.

We can generalize this and provide a bit index bit_ix that can range from 0 to 31 for 32-bit numbers.

uint32_t u = 3;
size_t bit_ix = 1;
uint32_t bit = (u >> bit_ix) & 1;

printf("bit: %u\n", bit);

I'm using a size_t type here for the bit index. This is just something I usually do for sizes, indices, etc.

Now we have a good way to access every individual bit of an int.

Let's print all of them to the screen:

uint32_t u = 3;

for (size_t i = 0; i < 32; ++i) {
  size_t bit_ix = 31 - i;
  uint32_t bit = (u >> bit_ix) & 1;

  printf("%u", bit);
}
printf("\n");

00000000000000000000000000000011

This prints out a bunch of bits: that's what the memory looks like for 3.

We have to sort of invert the bit_ix. We start at 31 and walk back to 0, so that we print the highest bits first and go down to the lowest bits. Just like how we treat decimal numbers as well.

Accessing float memory like it's an int

These bitwise operations won't work on floats:

float f = 3.0f;
uint32_t bit = f & 1u;

printf("bit: %u\n", bit);

error: invalid operands to binary expression ('float' and 'unsigned int')

So we have to figure out a way to convert the float into an int.

If we do this:

float f = 1.0f;
uint32_t u = f;

The code compiles, but the float is converted to a uint32_t, which means the bits in memory are all changed. A 1.0f float becomes a 1 int because that makes the most sense.

But what we want is to look at the bits of a float as if the memory belongs to an int, such that we can access the bits.

There are two approaches to do this:

Pointers
Unions

Let's try both.

The pointer method

If we convert a float to an int, we're interpreting the float as an int, and we set the memory that belongs to the int to whatever the float represents "numerically".

Instead, what we want is to create a float, and access its memory as if those 32 bits belong to a uint32_t.

In order to do that, we first create a float:

float f = 1.0f;

Then we create a pointer to that float's address:

float *fp = &f;

Then we can create a uint32_t pointer, which also just points to a place in memory. We can cast the float pointer to be a uint32_t pointer and point to the same thing:

uint32_t *up = (uint32_t *) fp;

And then we can create a uint32_t and set it equal to whatever the uint32_t pointer is pointing to (the float memory).

uint32_t u = *up;

Now we have created a uint32_t from a float, but without converting the value. We only cast the pointer types, which doesn't mess with the memory.

So all together, we can now print out the individual bits of a float:

float f = 1.0f;
float *fp = &f;
uint32_t *up = (uint32_t *) fp;
uint32_t u = *up;

for (size_t i = 0; i < 32; ++i) {
  if (i % 8 == 0) {
    printf(" ");
  }

  size_t bit_ix = 31 - i;
  uint32_t bit = (u >> bit_ix) & 1;

  printf("%u", bit);
}
printf("\n");

As you can see, I'm printing out a space every 8th bit, to group the bits as bytes:

00111111 10000000 00000000 00000000

And that's what the float 1.0f looks like in memory!

There is a catch though. Technically, this breaks C's strict aliasing rule: you're not supposed to read an object through a pointer of a different type. We're being sneaky hackers here. Officially, it's undefined behavior, and with optimizations turned on, the compiler might change the behaviour. In practice it usually works, but that's one more reason to prefer the next method.

The union method

This is, in my opinion, the easier method to understand, provided you know what a union is.

The syntax for a union looks just like the syntax for a struct in C:

typedef union {
  float f;
  uint32_t u;
} Bits;

The difference between a struct and a union is that a struct places all its members sequentially in memory:

Unions on the other hand place the members "on top of" each other, using the same memory:

So unions allow us to access the same memory bits as different types. This is exactly what we want, and unlike the pointer method, it's allowed by the C standard (but not in C++, by the way).

Accessing a float's bits can now be simplified using our Bits union:

float f = 1.0f;

Bits bits = {.f = f};

for (size_t i = 0; i < 32; ++i) {
  if (i % 8 == 0) {
    printf(" ");
  }

  size_t bit_ix = 31 - i;
  uint32_t bit = (bits.u >> bit_ix) & 1;

  printf("%u", bit);
}
printf("\n");

And this is the way I like to do it.

So let's put this into a reusable function print_float_bits where we pass in a float and get it to print the 32 bits to the console.

void print_float_bits(float f) {
  printf("%f ->", f);
  Bits bits = {.f = f};
  for (size_t i = 0; i < 32; ++i) {
    if (i % 8 == 0) {
      printf(" ");
    }

    size_t bit_ix = 31 - i;
    uint32_t bit = (bits.u >> bit_ix) & 1u;
    printf("%u", bit);
  }
  printf("\n");
}

This function prints out the float first, then the 32 bits (4 bytes) that make up this float:

1.000000 -> 00111111 10000000 00000000 00000000

Experiments

Before doing any experimentation, the one thing I know about floating-point numbers is that they use sort of a binary version of scientific notation. Scientific notation is some coefficient c, multiplied by 10 to the power of some exponent e: c × 10^e.

The binary version is simply c × 2^e.

This means that if you increase the exponent by 1, the final number is doubled.

So let's see what happens if we print 0.5, 1.0, and keep doubling a few more times:

float floats[] = {0.5f, 1.0f, 2.0f, 4.0f, 8.0f};

for (size_t i = 0; i < sizeof floats / sizeof *floats; ++i) {
  print_float_bits(floats[i]);
}

0.500000 -> 00111111 00000000 00000000 00000000
1.000000 -> 00111111 10000000 00000000 00000000
2.000000 -> 01000000 00000000 00000000 00000000
4.000000 -> 01000000 10000000 00000000 00000000
8.000000 -> 01000001 00000000 00000000 00000000

If you look closely at the bits, you can see there is a certain sequence of bits that keeps incrementing as we're doubling the float (the first 9 bits). The 9th bit has this 0-1-0-1 even/odd flipping pattern.

These might be the exponent bits we're seeing.

Another interesting thing we can do is look at 1.0, then double it to 2.0, then take the bits of 2.0 as an integer and subtract one. This should give us the highest possible float below 2.0.

To see this better, I'm increasing the number of decimal places to 8 like so:

...
printf("% .8f ->", f);
...

Note that I'm also adding a space in the format (% .8f). This reserves a space for the - sign, even if we have a positive number, which keeps all the numbers aligned.

 1.00000000 -> 00111111 10000000 00000000 00000000
 1.99999988 -> 00111111 11111111 11111111 11111111
 2.00000000 -> 01000000 00000000 00000000 00000000

When you look at the bits, the 1.0 and the 1.999... float both seem to have the same exponent bits, but in the 1.999... version, all the trailing zeros have flipped to ones.

Looking at this, it would make sense that all these bits that were flipped between 1.0 and 1.999... are the coefficient bits, or "mantissa" bits.

How about negative numbers? We can easily test a bunch of negative numbers, and see what happens:

 1.00000000 -> 00111111 10000000 00000000 00000000
-1.00000000 -> 10111111 10000000 00000000 00000000
 1.50000000 -> 00111111 11000000 00000000 00000000
-1.50000000 -> 10111111 11000000 00000000 00000000
 2.00000000 -> 01000000 00000000 00000000 00000000
-2.00000000 -> 11000000 00000000 00000000 00000000

Seems like it's the first bit. If it's 0, the number is positive; if it's a 1, the number is negative.

This rule even holds true for the number 0.0:

 0.00000000 -> 00000000 00000000 00000000 00000000
-0.00000000 -> 10000000 00000000 00000000 00000000

You might have seen negative zero (-0.0) floating around in terminal outputs. This is where it comes from: there is a literal negative zero float, distinct from the normal zero.

If we check for equality, the program says they are equal, which makes sense. But I wouldn't have been surprised if it had said false. It's generally not a good idea to compare floats for equality.

So, what we've found is:

The highest (leftmost) bit is the sign
The next 8 highest bits are the exponent
The last (lowest) 23 bits are the coefficient (a.k.a. mantissa)

Fancy terminal colors

Now that we know each bit's role, we can give them different colors.

In C, these are some macros I use to be able to print a few terminal colors:

#define ESC "\033"
#define RESET ESC "[0m"
#define FG_GRN ESC "[32m"
#define FG_YEL ESC "[33m"
#define FG_CYA ESC "[36m"

And in the print_float_bits function, I'm using them like this:

void print_float_bits(float f) {
  printf("% .8f ->", f);
  Bits bits = {.f = f};
  for (size_t i = 0; i < 32; ++i) {
    if (i % 8 == 0) {
      printf(" ");
    }

    if (i == 0) {
      printf(FG_YEL);
    } else if (i == 1) {
      printf(FG_GRN);
    } else if (i == 9) {
      printf(FG_CYA);
    }

    size_t bit_ix = 31 - i;
    uint32_t bit = (bits.u >> bit_ix) & 1u;
    printf("%u", bit);
  }
  printf(RESET "\n");
}

This prints out floats like this:

Yellow is the sign bit, the exponent bits are green, and the mantissa is blue.

Decoding the bits

We now know which bits do what, but how do they combine into the actual number? There are two small tricks:

The exponent is stored with a bias of 127. So the real exponent is the stored value minus 127. For 1.0, the exponent bits are 01111111 = 127, and 127 - 127 = 0.
The coefficient always starts with an invisible 1. in front of it, because in binary scientific notation, the leading digit is always 1 anyway. So there's no point in storing it.

Put together:

value = (-1)^sign × 1.mantissa × 2^(exponent - 127)

Let's check 1.5: the sign is 0, the exponent bits are 127 (so 2^0 = 1), and the mantissa bits are 1000..., which makes the coefficient 1.1 in binary. That's 1 + 1/2 = 1.5. So we get 1 × 1.5 × 1 = 1.5.

Special floats

We've been defining floats, and then looking at their binary representation.

How about we flip it: define some bits, and look at which float we get? We can define integers in binary format using the 0b... syntax. This is officially part of C since C23, but GCC and Clang have supported it as an extension for much longer.

Bits bits;
bits.u = 0b00000000000000000000000000000000;
print_float_bits(bits.f);

 0.00000000 -> 00000000 00000000 00000000 00000000

If we set all bits to 0, we get a float of 0.0. We already knew this.

How about we flip all bits to 1s?

bits.u = 0b11111111111111111111111111111111;
print_float_bits(bits.f);

nan -> 11111111 11111111 11111111 11111111

We get nan! (On Linux you might see -nan, because the sign bit is set.)

Let's see what we get if we only set the exponent bits to 1:

bits.u = 0b01111111100000000000000000000000;
print_float_bits(bits.f);

 inf -> 01111111 10000000 00000000 00000000

We get inf!

Can we flip the sign of inf? Let's try setting the highest bit to 1:

bits.u = 0b11111111100000000000000000000000;
print_float_bits(bits.f);

-inf -> 11111111 10000000 00000000 00000000

Yes, we can :) So as you can see, all those strange flavors of numbers like nan and inf are nothing more than specific bit patterns.

That's where I'll leave it for now. I hope that was helpful. I much prefer this method of exploration by hacking away at them, instead of reading the documentation.

Originally published at vanderoost.com.

Stop using rand()

Richard — Fri, 25 Sep 2026 12:34:11 +0000

In this article I will try to convince you to stop using rand() in your C projects, and write a better alternative from scratch.

Before I entered the RNG rabbit hole, I was definitely guilty of grabbing rand(), and maybe some srand(time(NULL)) when I needed it to be "unpredictable".

"But I'm not using it for cryptography"

In the back of my mind I always knew that rand() was not a "safe" random number generator, but when you just need some randomness for statistics or machine learning, who cares?

After digging a bit deeper though, I found out stronger reasons for ditching rand() and using something better.

Why not?

The three main reasons I don't use rand() anymore:

It's platform dependent
It's slow
It's low quality

Platform dependent

This means that rand() behaves differently depending on the platform you compile it for. What might be different? The maximum random number you can get (RAND_MAX) might be different, also the sequence of random numbers after a given seed set with srand() can be different. So that can be pretty annoying.

Slow

The rand function is not doing any complex math, but it relies on a global state and needs to acquire a lock to be able to mutate it (at least my implementation on MacOS). This happens every time you call rand(). So when you're calling it in a hot loop, it can get pretty slow compared to rolling your own RNG.

Low quality

The quality of random numbers that rand() produces is poor, we already knew that it's not "cryptographically safe" to use. But if we look at some simple alternatives, we can easily get way higher quality random numbers. (longer periods for example, so less repetition in sequences)

Putting `rand()` to the test

Humans are pretty good at recognizing visual patterns. So to test a random number generator, you can use visualization to expose flaws. Let's do that with rand().

If we create a 960 × 540 pixel buffer, and pick random color values for each pixel using rand():

#define WIDTH 960
#define HEIGHT 540
#define DEPTH 3 // RGB

#define BUF_LEN (WIDTH * HEIGHT * DEPTH)

int main(void) {
  uint8_t pix_buffer[BUF_LEN] = {};

  for (size_t i = 0; i < WIDTH * HEIGHT; ++i) {
    uint8_t *pixel = &pix_buffer[i * DEPTH];

    uint32_t roll = rand();
    uint32_t pixel_col = roll / (RAND_MAX + 1.0) * (1 << 24);
    memcpy(pixel, &pixel_col, DEPTH);
  }

  // Writing the pixels to an image here
}

(if you want to know how to write the pixels to an image, I cover it in the video and you can see the code in the repository)

We get an image that looks like this:

Looks pretty random, no weird patterns or repetition.

But if we change the way we color in the pixels, we can push rand() to its limits.

Instead of looping over pixels, we'll take a certain amount of "samples". For every sample, we pick a random number to decide which pixel to color, then we pick another random number that decides the color for that pixel:

#define SAMPLE_COUNT (1 << 20)

#define WIDTH 960
#define HEIGHT 540
#define DEPTH 3 // RGB

int main(void) {
  uint8_t pix_buffer[BUF_LEN] = {};

  for (size_t i = 0; i < SAMPLE_COUNT; ++i) {
    uint32_t roll_a = rand();
    uint32_t roll_b = rand();

    size_t pixel_ix = roll_a / (RAND_MAX + 1.0) * WIDTH * HEIGHT;
    uint8_t *pixel = &pix_buffer[pixel_ix * DEPTH];

    uint32_t pixel_col = roll_b / (RAND_MAX + 1.0) * (1 << 24);

    memcpy(pixel, &pixel_col, DEPTH);
  }

  // Writing the pixels to an image here
}

And this is the image you get:

Looks okay at first glance, but if you zoom in you can clearly start to see some repetition:

The reason for this pattern is that we call rand() once for the position, and then again for the color. And if you call rand() twice, the second call really depends on the first call. So in this loop, the color depends on the location, that's what causes the stripe pattern.

So, rand() is clearly suboptimal. How can we improve it?

What about `random()` ?

There is a better alternative than rand() available, called random(). And yes, it gives better quality random numbers, it's also faster (compared on an M2 Mac).

But after diving into the alternatives, writing my own RNG function seemed so much more interesting that I went for that. And by writing it from scratch, we will still end up with a 2.7 times faster function that has twice the range (32 bits instead of 31). So rolling our own RNG is still a good idea.

RNG from first principles

I'd like to get a basic understanding of how a pseudo random number generator works.

There are a lot of different approaches for generating random numbers. Most of them share the basic principle of having some kind of state, and being able to scramble this state to make it appear "random".

The random number you get when you call the generator is based on this state, and every time you generate a random number, the state gets mutated. So the next time you generate a random number, you will get a different one.

With this in mind, the most basic example of a pseudo random number generator might be something like this:

static uint32_t rng_state = 1;

uint32_t rng_u(void) {
  return rng_state *= 12343;
}

It has a state rng_state, and it "scrambles" this state by multiplying it by some constant 12343. I just picked an arbitrary 5 digit prime number for this. My intuition is that prime numbers avoid any obvious repetition.

The list of "random" numbers this thing generates looks like this:

Even this basic example looks pretty random at first glance. But of course, you can see that the first number is exactly our factor 12343 and we multiply by this amount every time, until we wrap around back to 0 at 4,294,967,296 (2³²).

This also means that we never generate an even number. So there are plenty of flaws to this approach. But this is the basic principle: a state that gets scrambled. We just need to "scramble" it a bit better.

Larger state and better scrambling

What also helps, is to reserve more bytes for the state. It's generally a good idea to have more bytes of state than the bytes of the random number you want to generate. So if you want to generate 32-bit random numbers, having a state of 64 bits would be a good idea.

Getting the optimal scrambling is a wheel I'd rather not re-invent myself. So I've searched for robust existing methods that have proved to behave well, and are backed by research and testing.

The best approach I've found in terms of simplicity, performance, and quality, is the PCG family. On that website, they share a basic C implementation that looks like this:

// *Really* minimal PCG32 code / (c) 2014 M.E. O'Neill / pcg-random.org
// Licensed under Apache License 2.0 (NO WARRANTY, etc. see website)

typedef struct { uint64_t state;  uint64_t inc; } pcg32_random_t;

uint32_t pcg32_random_r(pcg32_random_t* rng)
{
    uint64_t oldstate = rng->state;
    // Advance internal state
    rng->state = oldstate * 6364136223846793005ULL + (rng->inc|1);
    // Calculate output function (XSH RR), uses old state for max ILP
    uint32_t xorshifted = ((oldstate >> 18u) ^ oldstate) >> 27u;
    uint32_t rot = oldstate >> 59u;
    return (xorshifted >> rot) | (xorshifted << ((-rot) & 31));
}

As you can see, for the state we use a struct called pcg32_random_t that holds two 64-bit integers, one is the actual state, the other decides which "path" or "trajectory" we take through the state.

Calling the function pcg32_random_r scrambles the state properly, better than simply multiplying it by a constant number.

In order to use this minimal example, we need to declare our global state. The minimal C example only defines a struct, but it's never instantiated. We can grab the following from their GitHub:

#define PCG32_INITIALIZER {0x853c49e6748fea9bULL, 0xda3e39cb94b95bdbULL}

static pcg32_random_t pcg32_global = PCG32_INITIALIZER;

Now we actually have a global state called pcg32_global.

To generate a random number, we have to call the function pcg32_random_r and pass it the address of our global state:

uint32_t roll = pcg32_random_r(&pcg32_global);

Adding some useful wrappers

When I need a random number, I just want to call a simple function, and not worry about passing it anything. So let's add a simple wrapper that allows us to do this:

uint32_t rng_u(void) {
  return pcg32_random_r(&pcg32_global);
}

Now we can simply call rng_u() to get a random uint32_t.

This adds a bit of indirection, which can slow down the code. So later on we'll look at inlining rng_u() and pcg32_random_r().

In addition to random integers, I'd like to get random floats too. Let's add a float rng_f(void):

float rng_f(void) {
  return pcg32_random_r(&pcg32_global) / (UINT32_MAX + 1.0);
}

We're dividing by UINT32_MAX + 1.0f to make sure we get a range from 0 to 1 but excluding 1.0. So the range we get is [0.0, 1.0). This is typically the most convenient 0 - 1 range to work with for most use cases where you need a random float.

Getting a random float this way is quite naive and can be improved a lot, which we will do in a future article. So stay tuned if that's something you'd like to see.

Sampling from a normal distribution

We can add another flavor of random floats: a random float sampled from a normal distribution. This can be very useful in machine learning and statistics.

If we look at a histogram of 1M random floats, it looks quite uniform:

We can get some interesting distributions by playing around with this. For example, we can add two random numbers together, which gives us this pyramid shaped distribution:

And if we go a step further, adding three random floats together, we're starting to get something that has the shape of a bell curve:

As we add more vanilla random numbers together (random numbers sampled from a uniform distribution), we get closer and closer to a true normal distribution.

What I want when getting a random "norm" float, is I want it to be sampled from a normal distribution that has a mean of 0.0 and standard deviation of 1.0.

In the video I explore this a bit more, but it turns out that if you add 12 random floats together that were sampled from a uniform distribution between 0 and 1, you end up with a standard deviation of exactly 1.0.

The mean will be sitting at 12 * 0.5 = 6, so we have to shift the numbers by -6 to get a mean of 0.0.

This can be wrapped in a function called rng_norm and we get something like this:

float rng_norm(void) {
  float result = -6.0f;

  for (size_t i = 0; i < 12; ++i) {
    result += rng_f();
  }

  return result;
}

This function builds upon our rng_f function, which isn't as optimal as I'd like yet. And moreover, it calls it a whopping 12 times, which isn't quite optimal either if you run it in a hot loop. So even though this kind of works, and gets you a pseudo normally distributed sample, we will look at optimizing rng_f and rng_norm more in a future article.

In this article let's keep the focus on our rand() replacement rng_u().

Optimizing `rng_u()`

Our vanilla random integer generator has a bunch of indirection. One way we can optimize it is by inlining both rng_u and pcg32_random_r:

static inline uint32_t pcg32_random_r(pcg32_random_t *rng) {
  uint64_t oldstate = rng->state;
  // LCG step (pcg_setseq_64_step_r)
  rng->state = oldstate * 6364136223846793005ULL + (rng->inc | 1);
  // XSH RR output (pcg_output_xsh_rr_64_32), fed the old state so the
  // step and the output function can overlap
  uint32_t xorshifted = ((oldstate >> 18u) ^ oldstate) >> 27u;
  uint32_t rot = oldstate >> 59u;
  return (xorshifted >> rot) | (xorshifted << ((-rot) & 31));
}
static inline uint32_t rng_u(void) { return pcg32_random_r(&pcg32_global); }

There's a little bit more to this if you want to stash the RNG code away into a lib with a .c and .h. See the GitHub repo for more details, as I might keep that more up to date than this article.

Results

What this gives us, is a proper rand() alternative where we have 100% control over the code, no dependencies.

So what does the random image look like that we get out of this new implementation?

Properly random like this:

And no patterns or repetition to be seen when we zoom in either:

How about the execution time?

I've written a more elaborate benchmark script that compares rand() with rng_u() (can be found in the repo as well).

This is the result on an M2 Macbook Pro:

rand    6.651 ns/call
random  2.760 ns/call
rng_u   1.016 ns/call

Our own implementation rng_u() is roughly 6.5 times faster than rand() (and 2.7 times faster than random()). Not bad!

Originally published at vanderoost.com.

Why 95% of company AI projects fail

Richard — Sun, 20 Sep 2026 13:26:17 +0000

It's an interesting time to be alive. The "AI transformation" is happening.

Many business owners feel FOMO on AI adoption. Yet, allegedly 95% of AI projects in companies fail, according to an MIT report. Why is this?

I've talked to business owners and AI automation agencies. This is what I found.

Challenge: GenAI is non-deterministic

This is the big one. If you think like a software engineer, AI is finicky / fuzzy compared to cold hard code. LLM's use a literal random number generator to produce their outputs.

So if you use LLM's for automation, you will have unexpected things happening.

Most of the risk surfaces when you're using AI Agents to automate tasks. But there is a more boring and deterministic approach to automation: AI workflows.

AI Agents vs. AI Workflows

These are the two main approaches to AI automation.

AI Agents

Agents [] are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.

This is currently the most hyped up version of automation:

Trigger an LLM, and let it run wild with tools.

And by "let it run wild with tools" I mean:

Give it a sense of which tools it can use, and let the LLM decide which tools it wants to call, and how.

Tools can be: reading / writing files on your computer, using a calculator, doing web search. Anything you might be able to do with a computer that could be useful for the task at hand.

The flexible "blank canvas" approach here makes it quite interesting, but every little mistake adds up, and over time, results can get wild. This is not what you want in a company procedure.

So it currently requires a lot of babysitting to be productive with agents, which kind of defeats the purpose of automation.

AI Workflows

Less flashy, more simple and deterministic.

Workflows are systems where LLMs and tools are orchestrated through predefined code paths.

AI workflows are simple software procedures, with deterministic logic. The are "set in stone" and designed upfront with a lot of care.

Being predefined makes them less flexible, but that's exactly what you want in a company with SOP's. Only where it makes sense, LLM calls are made.

This way, you keep the automation in check, and things don't spiral out of control by a hallucinating model.

Every LLM call has guardrails with enforced checks and fallbacks. So even if an LLM model completely shits the bed, your workflow can still move on in a reasonable way.

Recipes for failure

The common patterns of AI projects that fail are:

One system trying to automate everything
Automating workflows that still need human feedback
Architecting high level production systems

One system trying to automate everything

The man who chases two rabbits, catches none. If you try to automate too much with a single system, the chances of failure increase geometrically. And that is why it so often fails.

The better approach is to take one procedure at a time, something that is done manually so you know exactly what needs to be done. You know the exceptions, you know the intricate details. Then it's a lot easier to start building an automation for this.

Don't "automate the marketing" for your company, but automate budgeting your google ads account for example.

Automating workflows that still need human feedback

If you try to fully automate a workflow where you should be checking things before moving to the next step, you're gonna have a bad time.

For example, sending emails. If you think your agent can read incoming emails, figure out a reply, and send them off. This might work well for 90% of the cases. But unexpected situations can cause massive disasters.

Solution: Automate 95% of the process, but have a human give the final green light before moving on. So let the AI draft a reply, you're the one to send it off.

Architecting high level production systems

AI models wrapped up in coding harnesses are getting extremely good at software engineering. But when architecting high level production systems, AI currently just lacks some of the awareness, company history, that's required to lead this to a good outcome.

Solution: Human / agent collaboration. Have a senior engineer go back and forth with the coding agent to come to a good outcome.

What works well

As we'll see, the non-deterministic nature of genAI explains why it so often fails to automate a business procedure.

The common theme is that typically the more boring automations, that don't look exciting or flashy, are working the best.

This agrees with Anthropic's take on the matter:

we recommend finding the simplest solution possible, and only increasing complexity when needed.

After talking to business owners, these are some AI project areas that are either working well or failing miserably.

Data analytics

Most companies are collecting data. And LLM's are fantastic at pulling data from a database, and drawing conclusion.

Especially if you give it the proper context of what they have access to, and all the relations between entities.

This can be a great way to answer business questions with subtle nuances that are different every time. For example, a question like: "What was last quarter's revenue from returning European customers?" and "How many of them spent over $1,000?".

This used to take a MySQL (or Tableau/Power BI) expert and a complicated query for every single question.

Now, most state of the art LLM's are smart enough to connect the dots, and pull the correct data out.

Pro tip: Give the LLM read-only access to your database. For analytics there's no need to change the database. We've all heard the horror stories of "the AI wiped out production".

Specialised translation

LLM's are pretty good at language. So if you have a specific translation job to do, where context matters a lot, they can do a great job.

If context matters a lot, you do have to make sure to give that context to the LLM, obviously.

Examples of this could be: Translating restaurant menu's into different languages. Here, it's important to not translate everything literally, but now that everything is food related. And if a menu item says "Margarita" it's important to know whether it's under the pizza's or the cocktails section.

Another example could be: Translating subtitles for technical tutorial videos. Having the context of the technical topic, and jargon is important here. But once you give it this context, LLMs can be great.

This is a perfect example of where a workflow performs a lot better than agents.

Research

LLMs are great at processing large amounts of text. If you need to do research on a certain topic, you can let LLMs search the internet for sources, and cross reference different findings.

Conclusion

AI projects tend to fail because companies try to hastily adopt new workflows out of fear of missing out, and by nature, LLMs are non-deterministic.

The approach that works reliably is: keeping it simple.

When building applications with LLMs, use the simplest solution possible, and only increase complexity when needed.

This might mean not building "agentic" systems at all, but just stick to workflows.

Originally published at vanderoost.com.

Plotting histograms in the terminal

Richard — Sun, 20 Sep 2026 13:26:16 +0000

I was generating some random numbers the other day. And I really felt the urge to visualize them. Just to get an intuition, like, what's the shape of the distribution? Is it noisy or smooth?

When in Python, I would usually bust out pip install matplotlib for this kind of tech. But what are the options when you're in C?

I ended up writing a plot library from scratch of course :) plt.c on github

I wanted to keep it super simple, so I chose to plot in the terminal, using unicode block characters. No need for external graphics or imaging libraries.

This is what it looks like:

In the rest of this article, we'll walk through the process of writing this library.

Generating test data

Before we can plot anything, we need something to plot. I want my utility to work with simple float arrays. If we need other datatypes later we can always do this.

So let's generate some random floats:

#include <stdlib.h>

#define SAMPLE_COUNT 16

int main(void) {
  float data[SAMPLE_COUNT];
  for (size_t i = 0; i < SAMPLE_COUNT; ++i) {
    data[i] = (float)random() / RAND_MAX;
  }

  return 0;
}

Histogram buckets

To take a list of random numbers, and turn it into a histogram, we need to decide on our "buckets".

Let's say all the little green dots are our random numbers, or samples. The buckets are drawn as columns, and we just have to count how many samples fall in each bucket. Those counts will correspond to the bar heights of our histogram.

We can do that by looping over all samples:

#define COLS 10

...

  size_t buckets[COLS] = {};
  for (size_t i = 0; i < SAMPLE_COUNT; ++i) {
    size_t bucket_ix = data[i] * COLS;

    buckets[bucket_ix]++;
  }

We initialize our buckets as a size_t array, initialized to zero with the = {}.

Then we loop over all samples, and for each decide which bucket it belongs to. Since we're working with samples from 0.0 to 1.0, it's a simple multiply with the number of columns COLS.

First ugly plot

Now that we have bucket counts, we can try to plot them. Since we have columns, we should also introduce the concept of rows. Rows and columns refer to the terminal characters we can print. So plotting a 2D figure is simply a double loop over rows and columns:

#define ROWS 5

...

  for (size_t i = 0; i < rows; ++i) {
    size_t height = (rows - 1 - i);

    for (size_t j = 0; j < cols; ++j) {
      if (buckets[j] > height) {
        printf("#");
      } else {
        printf(" ");
      }
    }
    printf("\n");
  }

We hit every cell with our doubly nested loop. Then in each cell we decide whether we're above or below the height/count of the bucket. If we're above, we print a space, if we're below, we print a pound sign. Just an arbitrary character that fills up the cell.

This spits out:

If you squint your eyes, it kind of looks like a histogram..

But we can do better :)

Autoscaling the Y-axis

One big problem with this approach is that we're not scaling the Y-axis at all. So when our sample count increases, we end up plotting a full block where all bars max out.

This is what it looks like with SAMPLE_COUNT set to 100:

We can fix this by keeping track of the maximum bucket count:

size_t bucket_max = 0;
for (size_t i = 0; i < COLS; ++i) {
  if (buckets[i] > bucket_max) {
    bucket_max = buckets[i];
  }
}

With this bucket_max and ROWS, we can scale the buckets to the right size for our canvas:

  for (size_t i = 0; i < COLS; ++i) {
    buckets[i] = (buckets[i] * ROWS) / bucket_max;
  }

Multiplying by ROWS, so increasing our rows will make the bars scale up. Dividing by bucket_max so the highest bar will always be exactly ROWS high.

Now the height of the histogram automatically scales:

Using the full terminal width

We've set our COLS to an arbitrary 10. We could make the tool really fancy and auto-detect the width of the terminal, but I usually don't change my terminal width much, so I'm ok with just hard-coding it.

But we can find out our width of the terminal using the $COLUMNS variable:

% echo $COLUMNS
72

So I'll be using 72 from now on. And while we're at it, let's set ROWS to 16 and also increase the number of samples to 1000:

#define SAMPLE_COUNT 1000
#define ROWS 16
#define COLS 72

And now our histogram starts to get a bit more "definition":

Unicode block elements

Instead of the arbitrary pound signs, we can do a lot better. By using unicode block elements we can 8x our vertical resolution (without increasing rows).

We have 8 different block elements, going from 1/8 height (U+2581), all the way to a full block (U+2588):

▁ ▂ ▃ ▄ ▅ ▆ ▇ █
1 2 3 4 5 6 7 8

All we have to do now is figure out some logic that prints out the correct unicode characters at the correct spot.

We will still print one character at a time, so the number of rows and columns doesn't change. But we can now deal with 8 times more height levels.

And then there are 3 different situations for a character. The column height can either be:

Under the current character: print a space
Above the current character: print a full block
Inside the current character: print one of the sub-blocks

The three situations are drawn in yellow here.

If we represent all 8 block characters in an array, we can use the index as the "sub-block-height" and we prevent having to write a lot of if-else statements:

  char *blocks[] = {
    " ",
    "\u2581",
    "\u2582",
    "\u2583",
    "\u2584",
    "\u2585",
    "\u2586",
    "\u2587",
    "\u2588",
  };
  size_t block_count = sizeof(blocks) / sizeof(*blocks) - 1;

As you can see, I've also added the space character in there. So we have a total of 9 elements in our array. I still want to do the math with 8 levels though. So when I calculate block_count I subtract 1.

Then when we're autoscaling, we don't want to set the max bucket height equal to ROWS, but to 8 times ROWS, so we multiply it by block_count:

  for (size_t i = 0; i < cols; ++i) {
    buckets[i] = (buckets[i] * rows * block_count) / bucket_max;
  }

And then it's time for the plot loop:

  for (size_t i = 0; i < rows; ++i) {
    size_t height = (rows - 1 - i) * block_count;

    for (size_t j = 0; j < cols; ++j) {
      int block_ix = buckets[j] - height;
      block_ix = block_ix < 0 ? 0 : block_ix;
      block_ix = block_ix > (int)block_count ? block_count : block_ix;

      printf("%s", blocks[block_ix]);
    }
    printf("\n");
  }

Our height is now also multiplied by the block_count.

And then we calculate the index block_ix which we then have to clamp betwen 0 and 8 to make sure everything works.

And when we run it like this, we're plotting something that looks like a real histogram:

And maybe we should change the distribution a bit to really appreciate the extra resolution this has bought us. We can take the square root of each random number, and increase the sample count to 10,000:

...

#include <math.h>

#define SAMPLE_COUNT 10000

...

int main(void) {
  float data[SAMPLE_COUNT];
  for (size_t i = 0; i < SAMPLE_COUNT; ++i) {
    data[i] = sqrtf((float)random() / RAND_MAX);
  }

  return 0;
}

Using sqrtf (square root for floats) from math.h we're getting a more interesting distribution:

A plot like this would have never been possible with spaces and pound signs.

Autoscaling the X-axis

We're almost done, but there still is one issue: If our random floats go outside the 0.0 - 1.0 range, we have a problem.

Let's go back to a uniform distribution, but subtract 0.5 to center the numbers around 0.0:

  float data[SAMPLE_COUNT];
  for (size_t i = 0; i < SAMPLE_COUNT; ++i) {
    data[i] = (float)random() / RAND_MAX - 0.5f;
  }

That results in the following abomination:

We could either manually specify the range we want to plot our histogram at, or let it auto-scale the x-axis as well. I prefer the latter. This allows us to just throw anything at it, and the plot function will just figure it out.

So in order to do this, we need to keep track of the x-range (the minimum and maximum value of our samples):

  float x_min = data[0], x_max = data[0];
  for (size_t i = 1; i < SAMPLE_COUNT; ++i) {
    float val = data[i];

    if (val < x_min) {
      x_min = val;
    }

    if (val > x_max) {
      x_max = val;
    }
  }
  float x_range = x_max - x_min;

Now we have x_min, x_max and x_range. And we're going to do some basic math to scale and shift the samples back into a 0.0 - 1.0 range, after which we can multiply them with the number of columns COLS.

First we calculate the x-scale. And we guard against a range of 0.0 to avoid dividing by zero:

  float x_scale = x_range > 0.0f ? COLS / x_range : 0.0f;

With this, we can shift and scale each sample, before calculating which bucket it goes into:

  size_t buckets[COLS] = {};
  for (size_t i = 0; i < len; ++i) {
    size_t bucket_ix = (data[i] - x_min) * x_scale;
    bucket_ix = bucket_ix > COLS - 1 ? COLS - 1 : bucket_ix;

    buckets[bucket_ix]++;
  }

Subtracting x_min makes sure we shift the entire range to start from 0.0. Then multiplying by x_scale scales it up to our number of columns.

After this, we make sure we don't exceed COLS - 1 which would mean we access elements outside of our buckets array.

This gets us back to a properly scaled histogram of our uniform distribution:

Splitting the code into a library

Up until this point we've been cluttering up our main function. I'd like to clean it up and end up with something like this:

main.c

#include "plt/plt.h"
#include <stdio.h>
#include <stdlib.h>

#define SAMPLE_COUNT 10000
#define ROWS 16
#define COLS 72

int main(void) {
  float data[SAMPLE_COUNT];
  for (size_t i = 0; i < SAMPLE_COUNT; ++i) {
    float roll_a = (float)random() / RAND_MAX;
    float roll_b = (float)random() / RAND_MAX;

    data[i] = roll_a + roll_b;
  }

  plt_hist(data, SAMPLE_COUNT, ROWS, COLS);

  return 0;
}

A lot cleaner. Our plot functionality is now just one plt/plt.h include, and one plt_hist() call.

Note that we also do two random rolls, and add them together. This gives quite an interesting distribution:

And our plt library looks like this:

plt/plt.h

#ifndef _PLT_H
#define _PLT_H

#include <stdlib.h>

void plt_hist(float *data, size_t len, size_t rows, size_t cols);

#endif // _PLT_H

plt/plt.c

#include "plt.h"
#include <stdio.h>
#include <stdlib.h>

void plt_hist(float *data, size_t len, size_t rows, size_t cols) {
  // Get the x range
  float x_min = data[0], x_max = data[0];
  for (size_t i = 1; i < len; ++i) {
    float val = data[i];

    if (val < x_min) {
      x_min = val;
    }

    if (val > x_max) {
      x_max = val;
    }
  }
  float x_range = x_max - x_min;
  float x_scale = x_range > 0.0f ? cols / x_range : 0.0f;

  // Keep track of bucket counts
  size_t buckets[cols] = {};
  for (size_t i = 0; i < len; ++i) {
    size_t bucket_ix = (data[i] - x_min) * x_scale;
    bucket_ix = bucket_ix > cols - 1 ? cols - 1 : bucket_ix;

    buckets[bucket_ix]++;
  }

  // Find the max count
  size_t bucket_max = 0;
  for (size_t i = 0; i < cols; ++i) {
    if (buckets[i] > bucket_max) {
      bucket_max = buckets[i];
    }
  }

  // clang-format off
  char *blocks[] = {
    " ",
    "\u2581",
    "\u2582",
    "\u2583",
    "\u2584",
    "\u2585",
    "\u2586",
    "\u2587",
    "\u2588",
  };
  // clang-format on
  size_t block_count = sizeof(blocks) / sizeof(*blocks) - 1;

  // Scale heights
  for (size_t i = 0; i < cols; ++i) {
    buckets[i] = (buckets[i] * rows * block_count) / bucket_max;
  }

  // Plotting
  for (size_t i = 0; i < rows; ++i) {
    size_t height = (rows - 1 - i) * block_count;

    for (size_t j = 0; j < cols; ++j) {
      int block_ix = buckets[j] - height;
      block_ix = block_ix < 0 ? 0 : block_ix;
      block_ix = block_ix > (int)block_count ? block_count : block_ix;

      printf("%s", blocks[block_ix]);
    }
    printf("\n");
  }
}

That's it! Thanks for reading.

I'm maintaining it on github as plt.c so feel free to grab it from there.

Originally published at vanderoost.com.

Related

The 7 levels of highly effective Makefiles

Richard — Sun, 20 Sep 2026 13:26:13 +0000

Rumor has it that all Makefiles in use today were written in a time when dinosaurs roamed the earth. Nobody actually writes new Makefiles anymore, right?

Right. Makefiles cause a lot of anxiety, but in this article, I will walk you through the humbling experience of writing a Makefile from scratch. To automate a C build system.

If you don't know what I'm talking about, Make is a tool for making files based on certain rules. It can be abused to do more, and to automate other terminal shenanigans. Think of running your tests, deploying, building Docker images, etc.

Once you find yourself running certain commands repeatedly in a codebase, your first instinct might be to stash them away in some bash script.

This works, but Makefiles give you some extra tech: make automatically creates a dependency graph of all the files you want to "make", and then uses the last modification timestamps of each file to determine what actually has to be made.

So it's more efficient, and it has some other cool tricks that we'll dive into.

TL;DR (spoiler alert): this is the final Makefile we'll end up with:

Makefile

CFLAGS = -Wall -Wextra

NAME = main
BIN = bin
OBJ = obj
SRC = src

EXEC = $(BIN)/$(NAME)

BIN_SRCS = $(wildcard $(SRC)/*.c)
LIB_SRCS = $(wildcard $(SRC)/*/*.c)
ALL_SRCS = $(BIN_SRCS) $(LIB_SRCS)

BINS = $(patsubst $(SRC)/%.c,$(BIN)/%,$(BIN_SRCS))
OBJS = $(patsubst $(SRC)/%.c,$(OBJ)/%.o,$(LIB_SRCS))
DEPS = $(patsubst $(SRC)/%.c,$(OBJ)/%.d,$(ALL_SRCS))

all: $(BINS)

$(BINS): $(BIN)/%: $(OBJ)/%.o $(OBJS)
    @mkdir -p $(@D)
    $(CC) $(LDFLAGS) $^ $(LDLIBS) -o $@

$(OBJ)/%.o: $(SRC)/%.c
    @mkdir -p $(@D)
    $(CC) $(CFLAGS) -MMD -c $< -o $@

run: $(EXEC)
    $<

watch:
    find $(SRC) -type f | entr -c make run

clean:
    $(RM) -r $(BIN) $(OBJ)

-include $(DEPS)

.PHONY: all run watch clean

If this looks a bit intimidating, not to worry. We'll start from zero with only a main.c file and build it up step by step, to multiple .c and .h files in a proper project setup with subdirectories. I use this post myself as a Makefile cheatsheet.

All the code can also be found in my C Makefile template repo.

Level 0 - Nothing

Literally no Makefile at all, so this one doesn't count. But even without a Makefile, we can already start using make because it has a bunch of default rules.

So without a Makefile, our project directory contains only a single file:

└── main.c

Before we knew about make, we would compile it into a main executable like this:

Terminal

% cc main.c -o main

But with make, we can simply run make main to do the same:

Terminal

% make main
cc     main.c   -o main

That output on the last line shows the command that make runs for us.

It compiles main.c into an executable called main which we can run to verify it's all working:

Terminal

% ./main
hello world

And that works, but how did make know what to do without a Makefile?

There are some default pattern matching rules, and make magically figures it out.

You don't need to understand this right now, but the rule that applies here looks like this:

%: %.c
    $(LINK.c) $^ $(LOADLIBES) $(LDLIBS) -o $@

The % picks up the target we want to make, main in this case. The %.c means it has a prerequisite of main.c where the % is the pattern. We happen to have a main.c, which is why this works. Then the actual "recipe" for making it is a bunch of variables that end up running cc main.c -o main.

You can see all the implicit rules and default variables with make -p if you're curious.

If your file is called program.c instead, you can run make program, and it spits out the file program as the executable.

Making without a Makefile is a bit of a party trick, but would I ever use this in practice? Actually, yes. Every time I quickly write a main.c to test something, all I have to do is type make main and it's compiled.

What if you want to change the compiler, or add flags? No problem. The default behavior of make is to compile with whatever is set in the CC environment variable, and it uses the flags from CFLAGS.

So if you want to compile with gcc instead of cc, you can run it like this:

Terminal

% CC=gcc make main
gcc     main.c   -o main

Adding flags can be done with the CFLAGS variable:

Terminal

% CC=gcc CFLAGS="-Wall -Wextra" make main
gcc -Wall -Wextra    main.c   -o main

But at this point it's easier to just use a Makefile. So let's check out the next level.

Level 1 - Bare minimum

Now we actually write a Makefile, the configuration for make. For our "bare minimum" level I want to add three features:

Automatically run after compiling
Configure compile flags
Cleanup to get back to the initial state

The filename is just Makefile so our project directory looks like:

├── Makefile
└── main.c

A filename of makefile also works, but Makefile is the convention I'm sticking to.

A Makefile mainly consists of a bunch of rules. This is what a rule looks like:

target: prerequisites
    recipe

So we have a target that's typically a file, like main. It can have prerequisites which are typically other files, but can also be other non-file targets. And finally the recipe which is the command to build the target, like a cc compile command.

One thing to watch out for: that indentation before the recipe has to be a literal tab character. Spaces will get you Makefile:2: *** missing separator. Stop., which is the most common way to break a fresh Makefile.

To automatically run our program, feature 1, I'm going to add a target called run, with a prerequisite main because we need the main executable to run it. And the action of running it is just calling ./main.

Makefile

run: main
    ./main

Now we can run make run, and this is what happens:

Terminal

% make run
cc     main.c   -o main
./main
hello world

First it gets compiled, then it runs ./main. How does make know that it needs to compile? Because we said that main is a prerequisite of run (i.e. run depends on main). So it will try to make main first, before running it. And since make main already worked without a Makefile, this still works.

But even better, when we run it a second time:

Terminal

% make run
./main
hello world

Now it only runs main, without compiling. Why? Because make is smart enough to look at the prerequisites of our run target, main. And since it already exists, it's not going to "make" it again.

We know that the targets in a Makefile are usually files, but run is not supposed to be a file. What if there is a file in our project directory that's literally called run? Let's see what happens:

Terminal

% make main
cc     main.c   -o main
% touch run
% make run
make: `run' is up to date.

Now make run doesn't do anything, because the target run is "up to date". That happens because the target file run is newer than the prerequisite file main.

To tell make that our run target is not really referencing a file, we can mark it with .PHONY like so:

Makefile

run: main
    ./main

.PHONY: run

Now make run works again, regardless of our accidental run file:

Terminal

% make run
./main
hello world

Even though we'll probably never have a run file in the root of our project directory, it's good practice to mark all the non-file targets with .PHONY to clarify intent.

Feature 2 is adding custom compiler flags, easy:

Makefile

CFLAGS = -Wall -Wextra

run: main
    ./main

.PHONY: run

That's all. Because we're using the default rule to make main, the flags will be picked up automatically:

Terminal

% make main
cc -Wall -Wextra    main.c   -o main

Feature 3 is adding a cleanup shortcut to undo everything. I'll call it clean and you see this in 9 out of 10 Makefiles, so we're just sticking to the convention. This target is, like run, not supposed to be a file, so we mark it as .PHONY, and all I want it to do is remove our main executable:

Makefile

CFLAGS = -Wall -Wextra

run: main
    ./main

clean:
    rm main

.PHONY: run clean

So the target is clean, it has no prerequisites, and all it does is run rm main:

Terminal

% make clean
rm main

But what if we run make clean and main doesn't exist?

Terminal

% make clean
rm main
rm: main: No such file or directory
make: *** [clean] Error 1

That's an error. It doesn't really matter, but for good measure we can change the recipe to rm -f main or use the $(RM) variable that make has for us:

Makefile

CFLAGS = -Wall -Wextra

run: main
    ./main

clean:
    $(RM) main

.PHONY: run clean

Now make clean runs without errors, even if there is nothing to clean:

Terminal

% make clean
rm -f main

Before we go to the next level, I want to add one finishing touch here to change the behavior of running just make without anything else.

When you have a Makefile, running make will run the first rule specified in the file, which is run in our case.

That's a bit confusing. I want to run the program with make run, but when I type make, it makes more sense to only compile (make) it, without running it.

A common pattern to achieve this is using an all target at the top of the Makefile:

Makefile

CFLAGS = -Wall -Wextra

all: main

run: main
    ./main

clean:
    $(RM) main

.PHONY: all run clean

We give it a prerequisite of main just like we did for run, so running it will make sure that main.c is compiled into main. But then the recipe is empty, so it doesn't do anything else:

Terminal

% make
cc -Wall -Wextra    main.c   -o main

It just "makes" our program, which is the most intuitive thing to do after typing make (or make all). And again, all is not referring to a file, so it's added to the .PHONY list.

Level 2 - Immediate feedback

For me, programming is more productive and fun with a tight feedback loop. So when I make an edit, I want it to instantly compile and run (or crash).

To do this, we can use a "file watcher" utility. I always use entr for this, and set it up as a new rule in the Makefile.

So let's add a watch rule to the Makefile, because it "watches" our source files for changes:

Makefile

CFLAGS = -Wall -Wextra

all: main

run: main
    ./main

watch:
    ls *.c | entr make run

clean:
    $(RM) main

.PHONY: all run watch clean

This is what happens when we run make watch:

Terminal

% make watch
ls *.c | entr make run
cc -Wall -Wextra    main.c   -o main
./main
hello world

The first part, ls *.c just lists out all .c files in our project directory. All we have is main.c for now.

Then it pipes that list of files to entr, which starts watching the file names that got passed in. When a file changes, it runs the command make run which compiles and runs our main executable.

After running make watch, it stays "active", waiting for changes. So if we edit main.c and add some punctuation, we instantly see this:

Terminal

% make watch
ls *.c | entr make run
cc -Wall -Wextra    main.c   -o main
./main
hello world
cc -Wall -Wextra    main.c   -o main
./main
Hello, world!

Which is super useful. One thing I usually like to pass to entr is the -c flag which clears the screen before it updates:

Makefile

CFLAGS = -Wall -Wextra

all: main

run: main
    ./main

watch:
    ls *.c | entr -c make run

clean:
    $(RM) main

.PHONY: all run watch clean

This prevents the terminal from cluttering up too much.

Now, whenever we mess up, there is instant feedback. Like a subtle slap on the wrist that instantly catches errors and bugs.

It also allows for faster experimentation: just try something, hit save, and the instant compile + run shows you the result.

Also good to know when using entr: Hitting Space re-runs the command. Hitting Q will quit.

Level 3 - Compiling multiple files

So far we've just been using main.c as our source file. This is great for quick tools or testing some new concept. But most projects are organized across multiple files.

Let's say I want to implement some tools for generating random numbers. I have an rng.h header file, and an implementation in rng.c.

To keep it simple, I'm still storing everything in the root of our project:

├── Makefile
├── main.c
├── rng.c
└── rng.h

Our main.c file now has an #include "rng.h".

We could compile this by hand like so:

Terminal

% cc main.c rng.c -o main

Integrating this into the Makefile looks like this:

Makefile

CFLAGS = -Wall -Wextra

all: main

main: main.c rng.c

run: main
    ./main

watch:
    ls *.c | entr -c make run

clean:
    $(RM) main

.PHONY: all run watch clean

All we did was specify our target main and give it the prerequisites main.c and rng.c. We don't give it a recipe, because we can still rely on the implicit recipe that make comes with by default. So this now works:

Terminal

% make run
cc -Wall -Wextra    main.c rng.c   -o main
./main
random float: 0.633477

But there is a way to simplify this even more. We don't need to write out the main.c prerequisite, because that's also implied by make already. So the more compact version of the rule looks like this:

Makefile

CFLAGS = -Wall -Wextra

all: main

main: rng.c

run: main
    ./main

watch:
    ls *.c | entr -c make run

clean:
    $(RM) main

.PHONY: all run watch clean

And everything still works:

Terminal

% make run
cc -Wall -Wextra    main.c rng.c   -o main
./main
random float: 0.503928

Level 4 - Source directory

Let's take the first step into organizing our project a bit more, by moving our source code into a src directory:

├── Makefile
└── src
    ├── main.c
    ├── rng.c
    └── rng.h

That breaks our build, because make can't find our source files anymore:

Terminal

% make run
make: *** No rule to make target `rng.c', needed by `main'.  Stop.

Fixing this in our Makefile is surprisingly simple. We just have to tell it about the new src directory by adding it to the VPATH variable:

Makefile

CFLAGS = -Wall -Wextra

VPATH = src

all: main

main: rng.c

run: main
    ./main

watch:
    ls src/*.c | entr -c make run

clean:
    $(RM) main

.PHONY: all run watch clean

On line 13 we're also fixing our watch rule and letting it know about the new src directory.

And that fixes the build:

Terminal

% make run
cc -Wall -Wextra    src/main.c src/rng.c   -o main
./main
random float: 0.621248

We're starting to see a bit of repetition in our Makefile, so let's take a moment to add some variables to DRY things up:

Makefile

CFLAGS = -Wall -Wextra

EXEC = main
SRC = src

VPATH = $(SRC)

all: $(EXEC)

$(EXEC): rng.c

run: $(EXEC)
    ./$(EXEC)

watch:
    ls $(SRC)/*.c | entr -c make run

clean:
    $(RM) $(EXEC)

.PHONY: all run watch clean

We have an EXEC variable for our final executable. If we ever need to change this name, we can do it in one place. Same for our source code directory, stored in SRC.

We've already seen the syntax for referencing a make variable before when we used $(RM), and we use it to reference EXEC and SRC as well.

Level 5 - Separate compilation

Right now we're taking all our .c source files, and compiling them in a single command. For this toy example that's totally fine and probably the fastest way, but for larger projects it could make sense to split this into multiple steps.

This way, when you make an edit to one source file, you only have to recompile that source file, and then link all compiled object files together, instead of compiling all source files on every edit.

There's a second payoff too: because every .o file becomes an independent target with no dependencies on the others, make -j can compile them in parallel across multiple CPU cores.

Manually, you can compile your .c files into object .o files, and then link them to get the final executable:

Terminal

cc main.c -c -o main.o
cc rng.c -c -o rng.o
cc main.o rng.o -o main

It's also possible to only compile the rng library into an .o file, and then link that in while compiling main.c:

Terminal

cc rng.c -c -o rng.o
cc main.c rng.o -o main

Let's see what that would look like in our Makefile. There is one super simple tweak we can make:

Makefile

CFLAGS = -Wall -Wextra

EXEC = main
SRC = src

VPATH = $(SRC)

all: $(EXEC)

$(EXEC): rng.o

run: $(EXEC)
    ./$(EXEC)

watch:
    ls $(SRC)/*.c | entr -c make run

clean:
    $(RM) $(EXEC)

.PHONY: all run watch clean

It's almost too small to spot, but we've changed rng.c to rng.o. So we're telling make our main executable doesn't depend on rng.c anymore, but rng.o.

And make happens to know how to compile .c files into .o files by using another standard pattern matching rule. So this works perfectly:

Terminal

% make run
cc -Wall -Wextra   -c -o rng.o src/rng.c
cc -Wall -Wextra    src/main.c rng.o   -o main
./main
random float: 0.143407

We went from a single cc command to two. So if we now make an edit to main.c to change the message, and run make run again, it will skip compiling rng.c because its .o file is already up to date:

Terminal

% make run
cc -Wall -Wextra    src/main.c rng.o   -o main
./main
the chance is: 0.226574

For a project with two .c files and fewer than 20 lines of code, this sort of optimization is kind of silly over-engineering. But as the project grows it starts to make sense.

You might have noticed that we have an rng.o file sitting in our project directory now:

├── Makefile
├── main
├── rng.o
└── src
    ├── main.c
    ├── rng.c
    └── rng.h

This allows us to avoid recompiling the rng library, but when we run make clean we should clean it up:

Makefile

CFLAGS = -Wall -Wextra

EXEC = main
SRC = src

VPATH = $(SRC)

all: $(EXEC)

$(EXEC): rng.o

run: $(EXEC)
    ./$(EXEC)

watch:
    ls $(SRC)/*.c | entr -c make run

clean:
    $(RM) $(EXEC) *.o

.PHONY: all run watch clean

Since we might add more than one library, we'll use *.o to remove all object files on cleanup.

Level 6 - Detect source files

Our Makefile is in great shape, but one thing I don't like is that every time we decide to write a new library in our project, we have to also remember to edit the Makefile. Wouldn't it be great if make could dynamically detect all source files?

To make this work, we're going to use some new Makefile features like wildcard and patsubst to find files using pattern matching.

We're also going to reorganize our source files one more time to make a better distinction between entrypoint .c files and library .c files.

I've added a new sample library called vec, to show how our build system can automatically detect multiple libraries.

The new project structure looks like this:

├── Makefile
└── src
    ├── main.c
    ├── rng
    │   ├── rng.c
    │   └── rng.h
    └── vec
        ├── vec.c
        └── vec.h

So the convention is: Entrypoints that turn into an executable go directly under src, and all libraries in a subdirectory of src. By sticking to this rule, we can configure the Makefile to detect these files properly.

We also have to change any #include "rng.h" in our main.c to #include "rng/rng.h" after this reorganization.

Our .o files can be organized in their own dedicated directory obj to reduce clutter in the root of the project.

Our first step will be to detect all library source files based on a wildcard pattern. To do that, we use the wildcard function:

LIBS = $(wildcard $(SRC)/*/*.c)

This function just expands all files that match the wildcard. So in our case, it will match src/rng/rng.c and src/vec/vec.c.

Next, we use the function patsubst to derive file names of the .o files we want to keep track of:

OBJ = obj
OBJS = $(patsubst $(SRC)/%.c,$(OBJ)/%.o,$(LIBS))

This one is a bit more complicated: It takes three parameters. The first one is the pattern to match, the second one is the new pattern to turn it into, and the third is a list of paths to do this with.

So OBJS is created out of LIBS, and transforms them like this:

src/rng/rng.c -> obj/rng/rng.o
src/vec/vec.c -> obj/vec/vec.o

Now we're going to use OBJS as the prerequisites of our EXEC target:

$(EXEC): $(OBJS)

Instead of listing the .o files of each library manually, we now have the $(OBJS) variable that dynamically updates.

This is what the second rule looks like:

$(OBJ)/%.o: $(SRC)/%.c
    mkdir -p $(@D)
    $(CC) $(CFLAGS) -c $< -o $@

There's a lot more going on. The target is dynamic due to the %, so it matches all .o files in the obj directory and dynamically creates a corresponding .c prerequisite for each one in the src directory. So obj/rng/rng.o will match with src/rng/rng.c for example.

The recipe of this rule has two commands. The first one just ensures that the directory of the target exists. The variable $(@D) magically references the directory of the target.

The second command is just compiling the .c file into the .o file. Again, it uses two magic variables: $< to match the first prerequisite, and $@ to match the target.

Our watch rule has to look for source files recursively in src, so we can use find for this:

watch:
    find $(SRC) -type f | entr -c make run

Our clean rule also has to be updated to match the new directory structure:

clean:
    $(RM) -r $(EXEC) $(OBJ)

We're removing the executable, and the entire obj directory. Because we have the mkdir -p recipe, we make sure we always rebuild these obj directories when needed.

If we add all of this to our Makefile, we get this:

Makefile

CFLAGS = -Wall -Wextra

EXEC = main
SRC = src
OBJ = obj

LIBS = $(wildcard $(SRC)/*/*.c)
OBJS = $(patsubst $(SRC)/%.c,$(OBJ)/%.o,$(LIBS))

VPATH = $(SRC)

all: $(EXEC)

$(EXEC): $(OBJS)

$(OBJ)/%.o: $(SRC)/%.c
    mkdir -p $(@D)
    $(CC) $(CFLAGS) -c $< -o $@

run: $(EXEC)
    ./$(EXEC)

watch:
    find $(SRC) -type f | entr -c make run

clean:
    $(RM) -r $(EXEC) $(OBJ)

.PHONY: all run watch clean

And we can run make to see what happens:

Terminal

% make
mkdir -p obj/rng
cc -Wall -Wextra -c src/rng/rng.c -o obj/rng/rng.o
mkdir -p obj/vec
cc -Wall -Wextra -c src/vec/vec.c -o obj/vec/vec.o
cc -Wall -Wextra    src/main.c obj/rng/rng.o obj/vec/vec.o   -o main

And it seems to work. First we make sure we have an obj/rng directory. Then we're compiling src/rng/rng.c into obj/rng/rng.o.

We do the same thing for obj/vec/vec.o.

And finally we compile main.c and link rng.o and vec.o into the final executable main.

After running make, the project directory looks like this:

├── Makefile
├── main
├── obj
│   ├── rng
│   │   └── rng.o
│   └── vec
│       └── vec.o
└── src
    ├── main.c
    ├── rng
    │   ├── rng.c
    │   └── rng.h
    └── vec
        ├── vec.c
        └── vec.h

So everything is working as expected.

One thing I'd like to clean up is those mkdir commands. I don't really want to see this in the make output. We can prevent any recipe commands from being printed by prepending an @ like this:

Makefile

CFLAGS = -Wall -Wextra

EXEC = main
SRC = src
OBJ = obj

LIBS = $(wildcard $(SRC)/*/*.c)
OBJS = $(patsubst $(SRC)/%.c,$(OBJ)/%.o,$(LIBS))

VPATH = $(SRC)

all: $(EXEC)

$(EXEC): $(OBJS)

$(OBJ)/%.o: $(SRC)/%.c
    @mkdir -p $(@D)
    $(CC) $(CFLAGS) -c $< -o $@

run: $(EXEC)
    ./$(EXEC)

watch:
    find $(SRC) -type f | entr -c make run

clean:
    $(RM) -r $(EXEC) $(OBJ)

.PHONY: all run watch clean

Now it looks a bit cleaner:

Terminal

% make
cc -Wall -Wextra -c src/rng/rng.c -o obj/rng/rng.o
cc -Wall -Wextra -c src/vec/vec.c -o obj/vec/vec.o
cc -Wall -Wextra    src/main.c obj/rng/rng.o obj/vec/vec.o   -o main

And the great thing is: There is no trace of the word rng or vec anywhere in the Makefile, it's fully dynamic. So if we add more libraries later, they will be picked up and compiled automatically.

Level 7 - Header dependencies

There is one flaw in our current Makefile: When you edit a header (.h) file, make doesn't know it has to recompile that particular library.

A simple way to test this is just updating the modification timestamp of one of the .h files with touch and running make again:

Terminal

% make
cc -Wall -Wextra -c src/rng/rng.c -o obj/rng/rng.o
cc -Wall -Wextra -c src/vec/vec.c -o obj/vec/vec.o
cc -Wall -Wextra    src/main.c obj/rng/rng.o obj/vec/vec.o   -o main
% touch src/rng/rng.h
% make
make: Nothing to be done for `all'.

It says "Nothing to be done", but we could have completely changed the header file.

This is actually to be expected. We're not mentioning .h files in the Makefile. All we do is say that the final executable depends on its corresponding .c file, and all .o files. Every .o file only depends on its corresponding .c file.

Fortunately, compilers and make can work together to fix this.

When you compile, say, main.c to main.o, you can pass the -MMD flag to let the compiler spit out not just the object file main.o but also a dependency file main.d.

Terminal

% cc src/main.c -MMD -c

It spits out two files:

├── Makefile
├── main.d
├── main.o
└── src
    ├── main.c
    ├── rng
    │   ├── rng.c
    │   └── rng.h
    └── vec
        ├── vec.c
        └── vec.h

And that main.d file is nothing complicated at all, it's just plain text:

main.d

main.o: src/main.c src/rng/rng.h src/vec/vec.h

This looks like a make rule. And it specifies that main.o depends on src/main.c but also the two header files src/rng/rng.h and src/vec/vec.h.

The way the compiler "knows" this is by looking at the main.c file, which specifies things like #include "rng/rng.h" and #include "vec/vec.h".

The -MMD flag actually has a few variations. Plain -M prints the dependency list to stdout and doesn't compile anything. -MD writes it to a .d file and compiles as usual. And -MMD does the same as -MD, but leaves out system headers. So that's the one we want, system headers are irrelevant in this case since we just want to know which files to recompile after we change one of our own header files.

So now we want take those .d files, and treat them like rules in our Makefile. And guess what, we can include other files in our Makefile using the (you guessed it) include

I'd also like to make the final executable files a bit more flexible, allowing multiple final executables. And I want to store them in a subdirectory called bin.

So this is the first thing I want to add:

Makefile

NAME = main
BIN = bin
OBJ = obj
SRC = src

EXEC = $(BIN)/$(NAME)

Instead of specifying the EXEC directly, we derive it from $(BIN) and $(NAME). The main executable will now be located at bin/main.

Instead of only keeping track of the library .c files, I want to keep track of the entrypoint .c files as well in a variable:

Makefile

BIN_SRCS = $(wildcard $(SRC)/*.c)
LIB_SRCS = $(wildcard $(SRC)/*/*.c)

We can now distinguish between the entrypoint source files with $(BIN_SRCS), and library source files with $(LIB_SRCS).

Now we have to modify the patsubst line, and we'll add another one:

Makefile

BINS = $(patsubst $(SRC)/%.c,$(BIN)/%,$(BIN_SRCS))
OBJS = $(patsubst $(SRC)/%.c,$(OBJ)/%.o,$(LIB_SRCS))

What's happening here with BINS is pretty much: Take all BIN_SRCS (only src/main.c) and substitute pattern src/%.c to bin/%. So src/main.c becomes bin/main.

Similar for OBJS: Take all LIB_SRCS (for example src/vec/vec.c) and substitute pattern src/%.c to obj/%.o. So now the % spans multiple directory levels. So src/vec/vec.c becomes obj/vec/vec.o because % matches vec/vec.

With these variables we can create some make rules.

First of all, the all rule can now mean: Build all BINS:

Makefile

all: $(BINS)

There is currently only one file, src/main.c, but if we add more .c files directly under src they will be considered entrypoints and they will be compiled to binaries.

Because we're explicitly listing our source files like this, we don't have to specify VPATH = $(SRC) anymore.

Now we're going to be a bit more explicit about how to link all .o files into the final binary.

Previously, we were relying heavily on the implicit rules that make comes with. But now we've customized things enough such that we have to spell it out:

Makefile

$(BINS): $(BIN)/%: $(OBJ)/%.o $(OBJS)
    @mkdir -p $(@D)
    $(CC) $^ -o $@

This is some new exotic syntax we haven't seen before, called a static pattern rule. We have:

targets: target-pattern: prerequisites

This allows us to explicitly spell out which exact target files we're gonna make, based on variable $(BINS). Each target is then matched against the target-pattern to extract a part of the target name (called the stem). This stem is substituted into each of the prerequisites that have a pattern (like $(OBJ)/%.o) to get the prerequisite names.

For example: target bin/main, matched with bin/% creates stem main. Substitute stem main into pattern obj/%.o creates prerequisite obj/main.o.

The recipe of this rule should look familiar. Just making sure the target's directory exists, and then linking all the .o files into the final binary executable.

Since we now store everything we make in either the bin or obj directories, we can update the clean rule to just remove those directories entirely:

clean:
    $(RM) -r $(BIN) $(OBJ)

The full Makefile now looks like this:

Makefile

CFLAGS = -Wall -Wextra

NAME = main
BIN = bin
OBJ = obj
SRC = src

EXEC = $(BIN)/$(NAME)

BIN_SRCS = $(wildcard $(SRC)/*.c)
LIB_SRCS = $(wildcard $(SRC)/*/*.c)

BINS = $(patsubst $(SRC)/%.c,$(BIN)/%,$(BIN_SRCS))
OBJS = $(patsubst $(SRC)/%.c,$(OBJ)/%.o,$(LIB_SRCS))

all: $(BINS)

$(BINS): $(BIN)/%: $(OBJ)/%.o $(OBJS)
    @mkdir -p $(@D)
    $(CC) $^ -o $@

$(OBJ)/%.o: $(SRC)/%.c
    @mkdir -p $(@D)
    $(CC) $(CFLAGS) -c $< -o $@

run: $(EXEC)
    ./$(EXEC)

watch:
    find $(SRC) -type f | entr -c make run

clean:
    $(RM) -r $(BIN) $(OBJ)

.PHONY: all run watch clean

Running make works as expected:

Terminal

% make
cc -Wall -Wextra -c src/main.c -o obj/main.o
cc -Wall -Wextra -c src/rng/rng.c -o obj/rng/rng.o
cc -Wall -Wextra -c src/vec/vec.c -o obj/vec/vec.o
cc obj/main.o obj/rng/rng.o obj/vec/vec.o -o bin/main

First we're compiling the three source files to object files. Then we link them together into the final executable. But what about the .d files?

We haven't done anything about them, yet. We just needed this foundation to be able to pattern match all files. Let's add the final pieces.

We will create a .d file for every .c file, so let's make a list of all .c files called ALL_SRCS:

ALL_SRCS = $(BIN_SRCS) $(LIB_SRCS)

That's pretty simple, just concatenating the $(BIN_SRCS) with the $(LIB_SRCS).

Now we use those for another patsubst to get a list of .d files that we'll store in DEPS:

DEPS = $(patsubst $(SRC)/%.c,$(OBJ)/%.d,$(ALL_SRCS))

The substitution is exactly the same as the one we have for the .o files, except we change the extension to .d. This is because the dependency files will be placed next to their corresponding object files under the obj directory.

Now we need to tell the compiler to actually create those .d files. Specifying the list doesn't do anything (it just helps us import them later).

All we need to do is add the -MMD flag to our .o compilation rule:

$(OBJ)/%.o: $(SRC)/%.c
    @mkdir -p $(@D)
    $(CC) $(CFLAGS) -MMD -c $< -o $@

Now we're creating the .d files. You can see it by running make and checking the obj directory:

├── Makefile
├── bin
│   └── main
├── obj
│   ├── main.d
│   ├── main.o
│   ├── rng
│   │   ├── rng.d
│   │   └── rng.o
│   └── vec
│       ├── vec.d
│       └── vec.o
└── src
    ├── main.c
    ├── rng
    │   ├── rng.c
    │   └── rng.h
    └── vec
        ├── vec.c
        └── vec.h

Now we can include them into the Makefile with this syntax:

-include $(DEPS)

And that's why we created that $(DEPS) variable.

We're using -include here instead of include. This is so that when one of the .d files doesn't exist, it's silently ignored. If you use include, you might encounter something like this:

Terminal

% make
Makefile:37: obj/main.d: No such file or directory
Makefile:37: obj/rng/rng.d: No such file or directory
Makefile:37: obj/vec/vec.d: No such file or directory
make: *** No rule to make target `obj/vec/vec.d'.  Stop.

And now, lo and behold, we can make everything with make:

Terminal

% make
cc -Wall -Wextra -MMD -c src/main.c -o obj/main.o
cc -Wall -Wextra -MMD -c src/rng/rng.c -o obj/rng/rng.o
cc -Wall -Wextra -MMD -c src/vec/vec.c -o obj/vec/vec.o
cc obj/main.o obj/rng/rng.o obj/vec/vec.o -o bin/main

And when we modify one of the header files, make knows we need to recompile:

Terminal

% touch src/rng/rng.h
% make
cc -Wall -Wextra -MMD -c src/main.c -o obj/main.o
cc -Wall -Wextra -MMD -c src/rng/rng.c -o obj/rng/rng.o
cc obj/main.o obj/rng/rng.o obj/vec/vec.o -o bin/main

It recompiled src/main.c and src/rng/rng.c because they both include src/rng/rng.h.

Our watch rule also works properly now. It was already running make run on a change of any file inside the src directory, so that was already working. But now, when a .h file is the one that's being edited, it will trigger entr and properly run a recompile.

A few final tweaks before we sign off.

If your build needs linker flags, the convention is to split them across two variables. LDFLAGS holds linker options like -L/opt/lib and goes before the object files. LDLIBS holds the libraries themselves, like -lm, and goes after them, because the linker resolves symbols in the order it sees them. That's the same ordering make uses in its own implicit link rule:

$(BINS): $(BIN)/%: $(OBJ)/%.o $(OBJS)
    @mkdir -p $(@D)
    $(CC) $(LDFLAGS) $^ $(LDLIBS) -o $@

We can simplify our run target:

run: $(EXEC)
    $<

This is very optional, but the magic variable $< refers to the first prerequisite, which is $(EXEC), which is bin/main. So bin/main is executed as a command, which runs the main executable.

And that's it. We've finished our Makefile!

Makefile

CFLAGS = -Wall -Wextra

NAME = main
BIN = bin
OBJ = obj
SRC = src

EXEC = $(BIN)/$(NAME)

BIN_SRCS = $(wildcard $(SRC)/*.c)
LIB_SRCS = $(wildcard $(SRC)/*/*.c)
ALL_SRCS = $(BIN_SRCS) $(LIB_SRCS)

BINS = $(patsubst $(SRC)/%.c,$(BIN)/%,$(BIN_SRCS))
OBJS = $(patsubst $(SRC)/%.c,$(OBJ)/%.o,$(LIB_SRCS))
DEPS = $(patsubst $(SRC)/%.c,$(OBJ)/%.d,$(ALL_SRCS))

all: $(BINS)

$(BINS): $(BIN)/%: $(OBJ)/%.o $(OBJS)
    @mkdir -p $(@D)
    $(CC) $(LDFLAGS) $^ $(LDLIBS) -o $@

$(OBJ)/%.o: $(SRC)/%.c
    @mkdir -p $(@D)
    $(CC) $(CFLAGS) -MMD -c $< -o $@

run: $(EXEC)
    $<

watch:
    find $(SRC) -type f | entr -c make run

clean:
    $(RM) -r $(BIN) $(OBJ)

-include $(DEPS)

.PHONY: all run watch clean

We can now:

Automatically compile everything with make
Compile and run with make run
Recompile and run on edits with make watch
Clean up our mess with make clean

And the Makefile automatically detects our source files.

Thanks for reading. I hope this gives you the courage to go out into your codebase, whip up a new Makefile from scratch, and automate some of those repetitive commands.

Originally published at vanderoost.com.

Related

C Makefile template on Github

DEV Community: Richard

Generating random floats

The naive way

Looking at float bits

Randomising the 23 mantissa bits

Doubling the resolution

Back to basics

Tucking it into the library

Hacking floats to learn how they work

Writing C

How many bits?

Accessing bits of integers

Accessing float memory like it's an int

The pointer method

The union method

Experiments

Fancy terminal colors

Decoding the bits

Special floats

Stop using rand()

Why not?

Platform dependent

Slow

Low quality

Putting rand() to the test

What about random() ?

RNG from first principles

Larger state and better scrambling

Adding some useful wrappers

Sampling from a normal distribution

Optimizing rng_u()

Results

Why 95% of company AI projects fail

Challenge: GenAI is non-deterministic

AI Agents vs. AI Workflows

AI Agents

AI Workflows

Recipes for failure

One system trying to automate everything

Automating workflows that still need human feedback

What works well

Data analytics

Specialised translation

Research

Conclusion

Plotting histograms in the terminal

Generating test data

Histogram buckets

First ugly plot

Autoscaling the Y-axis

Using the full terminal width

Unicode block elements

Autoscaling the X-axis

Splitting the code into a library

The 7 levels of highly effective Makefiles

Level 0 - Nothing

Level 1 - Bare minimum

Level 2 - Immediate feedback

Level 3 - Compiling multiple files

Level 4 - Source directory

Level 5 - Separate compilation

Level 6 - Detect source files

Level 7 - Header dependencies

Putting `rand()` to the test

What about `random()` ?

Optimizing `rng_u()`