What are build systems?

I’ve been working on a small data structures library and recently finished writing the main code for it. This was my first multi file project in c snd so I want to organize it like how actual projects on GitHub are organized and use a build system for it. Since I’d mostly heard about Cmake being popular, I decided to learn how to use Cmake

However, as I try to understand how to structure my project and use Cmake, I keep on getting more and more lost. I’ve seen many tutorials on the internet but they all have different methods of going about it and, till now, I haven’t found any tutorial that explains how to properly structure a library and use it with Cmake

There are many terms in cmake that I fail to understand (such as target, static, public etc) and I don’t even think I understand the use of cmake. I thought a build system was used to compile our code in a simpler, more organized way but what I’m reading is that Cmake is a build system that builds build systems? I know how headers files, object code, linkers, etc work but I don’t understand how they work with Cmake

Overall these are my main questions:

How to structure a C project(specifically a library)?

What is a build system?

How Cmake works?

How to build a library with Cmake?

---

Comments

connorcinna • 17 points • 2024-06-20

it goes like this, in terms of abstraction:

1. learn to compile code with gcc from the terminal
2. learn to write a makefile to compile your projects with make ⇐ you are here
3. learn to write CMakeLists.txt to generate makefiles using cmake , which will then allow you to compile your projects with make

sidenote, make is only one build system, but it is the OG, so you should learn it. another popular one is ninja, but i’ve never set up a project with it personally so i can’t speak to it.

Immediate-Food8050 • 24 points • 2024-06-20

You’re right. Build systems help compile your code in a neat and structured way, and CMake does build the build systems and also helps use them. But I recommend learning Make/Makefile first, which CMake generates for you. Now, this doesn’t mean it’ll be much easier, but there is less depth to the earlier half of the learning curve and you’ll probably have an easier time getting something simple going. You can look at Make as a scripting language for a build system because that is exactly what it is. Learning Make will also IMO make learning CMake a lot easier.

bothunter • 10 points • 2024-06-20

I second this.  CMake is nice, but it’s a few levels of abstraction above what you’re actually doing which can make it difficult to understand.

Makefiles are actually quite simple once you strip out all the macros that people love to mix in.  Basically, it’s just a file that defines a list of inputs, outputs and how to make them.

It goes in the form:

target: inputs     command to generate target from inputs

For example:

main.o: main.c     gcc main.c -o main.o

Add a similar lines for each source file, and then one for the linker.  When you then run make, it builds a dependency tree and then figures out what needs to be rebuilt.

There’s a little more to it, such as adding a “clean” target, and sprinkling in some macros so you’re not just copy/pasting the same commands a hundred times, etc, but that’s the gist of it.

bothunter • 6 points • 2024-06-20

Reddit munged my formatting… But I found this tutorial: https://makefiletutorial.com/

CarlRJ • 4 points • 2024-06-20

Just edit the post and add 4 spaces on the front of each of the sample lines - it’ll trigger Reddit to display the lines verbatim (minus those leading 4 spaces), and in a monospaced font (this is a standard Markdown formatting rule; it’s also mentioned in the first rule of this subreddit). Like this:

main.o: main.c gcc main.c -o main.o

bothunter • 2 points • 2024-06-20

Easier to do when not on mobile.  ;) 

Reddit’s mobile site is trash.

CarlRJ • 1 points • 2024-06-20

Edit the text in some external text editor and paste it back into Reddit (website or mobile app).

helloiamsomeone • 4 points • 2024-06-20

Make/Makefile first, which CMake generates for you

Unless you use Ninja, or MSBuild, or Xcode, or GHS, or …
Should really only use Ninja instead of make nowadays.

gruntbatch • 10 points • 2024-06-20

For a smaller project, don’t discount the possibility of a simple shell script. On unix (posix?) I think all you have to do is this:

$ echo “your current compile command goes here” > build.sh

And to build your project, you just have to call that file:

$ sh ./build.sh

You can make the script executable, and all that good stuff too, if you like. I’m not sure what the equivalent is on Windows.

Advantages over using make/CMake:

• Incredibly easy

Disadvantages:

• Rebuilds the entire project every time you call it
• Possibly less portable
• Locks you in to a specific compiler/pipeline

ETA: I still recommend learning make, but sometimes a bandaid solution like this is fine

oh5nxo • 12 points • 2024-06-20

A trick to make a C file double-duty as a script:

if 0 set -ex cc -Wall -Wextra -g “$@""$0” exit #endif

include <sys/types.h> … rest is C …

gruntbatch • 4 points • 2024-06-20

Oh, that’s really clever! I’m filing this alongside the --> operator under “Things I wish my boss let me get away with.”

DaGarver • 4 points • 2024-06-21

What’s the use case for -->? It reads to me on first glance as -- >, but I’m not grokking where it would make more semantic sense to strip the whitespace between the operators.

gruntbatch • 4 points • 2024-06-21

You’re absolutely correct that --> is actually -- >. It’s sometimes jokingly called the goes to operator. You use it in loops:

for (int i = start_value; i ⇒ 0;) // i goes to 0

You would typically write the above loop like so:

for (int i = start_value - 1; i >= 0; i—)

It’s one of those “elegant” solutions that probably doesn’t belong in production code, though I have used it in my own projects. This trick isn’t nearly as crazy as Duff’s Device, but I would argue that it violates the principle of least astonishment.

cHaR_shinigami • 2 points • 2024-06-22

You would typically write the above loop like so

I’m sure you realize that the two loops aren’t equivalent - there’s a minor difference.

Just as a small note to beginners who may read the comment, the “goes to” operator i --> 0 decrements i before executing the loop body in each iteration, but the rewritten code in the “traditional way” decrements i after executing the loop body per iteration.

gruntbatch • 2 points • 2024-06-22

To clarify, the loops as written will iterate over the same values, so they are functionally equivalent, but you’re correct in that the “goes to” operator obfuscates things.

cHaR_shinigami • 2 points • 2024-06-22

Agreed, the two loops are indeed functionally equivalent.

Tasgall • 4 points • 2024-06-20

don’t discount the possibility of a simple shell script.

The most powerful and flexible build system of all time: ./build.sh

EmbeddedSoftEng • 3 points • 2024-06-21

Even with CMake, I use a build.sh file. There are only a handful of build types I generally have to use, so rather than requiring future-me to load up the IDE that was used during development and GUI-click my way to a build, I can just clone the repo, do the necessary pre-build steps, and then `./build.sh Release` and the release build gets made.

And I’ve double checked often that the resultant artifact is bit-for-bit identical to what the IDE build system would produce. You know, modulo the differing timestamps, and therefore checksums, but those differ even on back-to-back rapid fire builds from the IDE.

Jaanrett • 4 points • 2024-06-20

I’m not quite familiar with cmake but for my money, I’d start with make. Learn make, and create a simple make file for your project.

If I’m not mistaken, cmake generates make files. Old school is to write a make file. I think once you understand the basics of that, then look at cmake.

[deleted] • 4 points • 2024-06-21

Perhaps learn how to build multi-module programs without any build system at all.

Once you know what is involved and what needs to be done, you can think about whether to use a separate tool to do it, or what it might bring to the table.

For example, make files are big on defining dependencies between modules, so that if you’re stuck with a slow compiler, or you have a big project, then you don’t need to compile everything each time you change one line.

Or you will see what jobs can done better with a script.

(I can’t say I never use build systems, but I don’t use ones like ‘make’ or ‘cmake’; I prefer other solutions. But then with my own projects, I know exactly what is needed.)

EmbeddedSoftEng • 3 points • 2024-06-21

In a very real way, CMake is a meta-build system. Instead of learning GNU make, ninja, ant, etc., you can just learn CMake, and then retarget (see that word in there?) which underlying build system you want CMake to use to actually do the heavy lifting.

The main idea behind CMake is that it’s declarative. You state that here are my include directories, here are my source files, here’s the executable I want to build… get to it. None of the details are handled in the CMake file (CMakeLists.txt). CMake takes the information you give it and crafts the operative build files for the actual build system you told it you wanted to use, and then has it get the job done. That’s a major part of your confusion.

CMake is less a build system and more project management. Still very worthwhile to learn.

When building software, there are two, sometimes three, distinct machines/machine types that you need to be aware of. Since you’re not building a compiler, we’ll stick with two. The Host and the Target. The host is the machine you’re using to build your software. The target is the machine where you expect the resultant software to be run. It sounds like you mean for them to be one and the same, so there’s a vastly simplified playing field for you.

I’m an embedded software engineer, so my programs never run on the same machine I use to build them. And the devices that do run my programs can be diverse, so I need to be cognizant of what device I’m targetting with my build.

You’re doing a library, so the primary artifact that you’re looking for out of your build system is just the dynamic library file. .dll in the windows world, .so in the UNIX world. But most libraries also come with little example implementations of executable programs to show how to use the library to solve common tasks. The library file and those executable files have to be built separately. The files intended to become an executable file, you don’t necessarily want to get compiled and linked into the library itself. And with a dynamicly loaded library, you just want the executable to know about the library so that the linker-loader can do its job at run time. You don’t want library code to be built and linked directly into the executable (unless it’s a static-only library).

This makes the library file and the individual executable files separate targets of the build system. So, you have to be explicit about how to build and what goes into each separate target. If you only have one target for your build system, then that’s another vast simplification.

But building a library is a distinct task from building an executable. You’ll need to learn how to tell CMake to distinguish the two.

Lurchi1 • 5 points • 2024-06-20

I’d also encourage you to learn about Makefiles, and decide from there if you even want to dig into CMake.

Take a look at this very simple tutorial that shows how to build a C library using make (first pick from google, there might be better).

If you happen to use Gnu make, they have excellent documentation to help you getting a deeper understanding of make’s capabilities.

You can start with a trivial directory structure: put everything in one directory (including the Makefile), just like in the tutorial above. Once you have everything up and running, a common simple structure would be to create two subdirectories src and include and to move all .C files to the former and all .H files to the latter. Be prepared for a bit of a learning curve when adjusting your Makefile to that directory layout, just remember: Google is your friend, as is your make’s documentation.

pkkm • 2 points • 2024-06-20

A build system is basically a layer of automation over compilation, linking, and potentially other tasks like making a package. For the simple cases, a shell script works fine, but an advanced build system can come in handy when you want your program/library to compile on multiple OSes with different library paths, multiple compilers with different flag formats, or when you want to have several compilation variants (e.g. debug, release with debug info, normal release, release optimized for minimum size). Importantly for large projects, build systems usually support incremental compilation - meaning that when you rebuild after making a small source change, the build system compiles only the files that need to be recompiled.

With CMake, it’s actually two layers. CMake generates instructions for Make, a simpler build system with less abstraction, which is the one that actually runs the commands to compile and link your program.

Don’t get discouraged if it’s unintuitive at first - CMake is infamous for that. Its scripting language has a lot of unfortunate design choices, like not having an actual list type (they’re just strings separated with ;). It has also evolved a great deal over the years, so when googling questions, it’s easy to find a mix of answers with modern practices and answers with techniques that are no longer recommended. The situation is better if you use “modern cmake” rather than just “cmake” in your search queries.

[deleted] • 2 points • 2024-06-21

Just use make. Whenever I see a library with plain make I breathe a sigh of relief. That blows up fast though, which is why there are build systems. So when I see a hand written makefile I know the code is probably minimal too, and I rejoice.

heptadecagram • 2 points • 2024-06-21

I would suggest starting out with learning what make is doing before understanding how CMake makes it easier.

ucario • 1 points • 2024-06-21

First understand the problem that they solve. How does the compiler work? What is linking? Etc etc.

Learn how to do this yourself via the command line.

Once you understand the process of ‘building’ you will understand the problems that a ‘build system’ simplifies and helps to solve

Dull_Category7045 • 1 points • 2024-06-21

I don’t know much about Cmake but It seems interesting

These-Bedroom-5694 • 1 points • 2024-06-21

CMake is cancer. I can never get open source projects to build with it.

mihemihe • 1 points • 2024-06-21

Learn Rust, port your small library, and use Rust cargo. I assure you this path will be shorter and less painful than learning and using CMake. I am only half-joking here

Limp_Day_6012 • 1 points • 2024-06-21

Imo, for build systems, just use xmake, it just works well and imo is the best build system

Visual_Thing_7211 • 1 points • 2024-06-22

Of course you can put the files in your project wherever you want and still use CMake—it doesn’t proscribe any specific hierarchy of directories, but many people have found it useful to put source code in a directory called src and put public header files of a library in a separate directory called include.

Many people find CMake confusing or hard to get started with, but it doesn’t have to be. An excellent intro to CMake that is simple to follow for newer CMake users is: https://m.youtube.com/watch?v=7YcbaupsY8I

M_e_l_v_i_n • 1 points • 2024-06-23

It’s a program that reads a text file which tells it how to invoke the compjler of your choise and where you want the object files to end up.

I just use a .bat file to compile all of my stuff, don’t need a build system to do it. If you write your code sensibly, your compile times should be always <10s

BrokenG502 • 1 points • 2024-06-21

In addition to what other people here have already said, I’ll just add that meson https://mesonbuild.com is incredibly effective in my experience. Do however learn about make (and ninja too ig) as well, I think it’s a very good step in transitioning from shell commands into a full build system. 

Cmake is notoriously terrible in a lot of ways, but it’s so widely used you may wish to learn it anyway, in which case I wish you good luck as I have absolutely no wish to do anything related to cmake.

I will say that it is a good idea to learn the cmake commands used for compiling an existing cmake based project.

frozenbrains • -2 points • 2024-06-20

How to structure a C project(specifically a library)?

I am a fan of the traditional way: 

libraryname/

 ----build/

 ----doc/ 

----src/

----tests/ 

The build directory should be ignored by source control and generated by the build system.

What is a build system?

Exactly what the name implies. Some are simple (e.g. Makefiles), some are more complex (cmake). Basically it is software you feed a list of source files for your program/library, and it figures out what depends on what, what’s necessary to generate a binary. Cmake generates a Makefile for you that knows your toolchain and target platform, without you having to do the work yourself (like gcc on Linux vs Visual Studio on Windows).

It can also handle debug and release builds. It basically abstracts the differences between different compilers and implementations of make like Microsoft nmake vs gnu make.

How Cmake works?  

RTFS?

How to build a library with Cmake?  

RTFM?

There’s a ton of tutorials out there, but look for more recent ones. I’m rusty on cmake myself, and was never much of a fan of it, but back when I was into it I had the best luck searching for “modern cmake”.

*Multiple edits because Reddit ate my formatting. I give up.