03: Building with Meson

NOTE I'm not sure if this is the best place to show how to use Meson. It does make building the C++ code a lot easier, but it could also be delayed until later since most of the exercises use only a single file and the c++ compiler can do that much. Tell me if you think this is too early, or a good spot to do it.

In Exercise 2 I had you build your code using the c++ compiler like this:

c++ ex02.cpp -o ex02

This works fine for any small single file programs but eventually you'll want to make bigger projects. Larger projects have multiple files, and also use libraries of code by other people. For example, if you want to create a video game you'll most likely use a game library like SFML or SDL2.

I'm going to have you use a build tool called Meson which knows how to build your code, no matter how complex, for multiple platforms, and use any libraries you need. This will also make it easier to get through the course since each exercise will require only a single change to your build file, or a new similar build file.

The meson.build File

In the directory where you saved ex02.cpp I want you to make a new file named meson.build (mine is called ex03a.build here only for formatting in the course). This meson.build should have these contents that has this in it:

View Source file ex03a.build Only

project('learn-cpp-the-hard-way', 'cpp',
    default_options: ['cpp_std=c++20'])

executable('ex02', 'ex02.cpp')

For example, I have a directory called lcthw/lcpp that I do my work in for the course. Inside that directory I have my ex02.cpp file. That means I should place the meson.build file in this same lcthw/lcpp directory.

To test that you've done this right, you should be able to type these two commands and not receive an error:

cat ex02.cpp
cat meson.build

If you get an error, then you didn't set this up right. Use ls and start (open on macOS) to figure out where your files are in your Terminal. If you don't get an error but instead get no output then you didn't save your file. Go back to your editor and save it again.

WARNING I highly recommend you delete anything you compiled. If you've only done Exercise 02, then simple do rm ex02 on macOS, or rm ex02.exe on Windows. If you've done more, then delete everything except your source files. This will prevent you from accidentally running the wrong executable. If you ever find yourself changing your code but "nothing happens" then this is probably what you did. I do this all the time.

Configuring Your Project

Meson uses a "build directory" to create your projects. In Exercise 02 you compiled your ex02.cpp file right in the same place as the output ex02 program. This is fine for a while, but eventually your project directory will become littered with junk that confuses you. Meson solves this by keeping all the "junk" in a directory so you can easily delete the directory to clean up.

To configure this build directory, use this command:

meson setup --reconfigure builddir

This should create a new directory named builddir that will contain your compiled executables, but also any other build "junk" that gets created. Using my previous example of lcthw/lcpp your builddir is at lcthw/lcpp/builddir and should be at the same level as your ex02.cpp and meson.build file.

To test that you did this correctly, type this command:

ls ex02.cpp
ls meson.build
ls builddir

If any of these commands produce an error then you've done it wrong. Go back and look at your commands, where you were when you typed them, and try to fix it.

You only need to do this once or if you change any options for meson. You'll notice I added a --reconfigure but I've found that meson may not actually reconfigure, so it may be easier to just delete the directory and run meson setup --reconfigure builddir again.

Compiling Your Exercises

Once the builddir directory is setup you can then continually re-run this command to build everything you're working on:

meson compile -C builddir

Make sure that you run this command in the same location as your ex02.cpp and meson.build file. Do not--I repeat--do not do this:

cd builddir # wrong! wrong wrong wrong! No!
meson compile -C builddir

If you made this mistake, just type cd .. to get back and then type the ls builddir to confirm you can actually access builddir.

Cleaning Your Project

If you ever need to clean your build you do this:

meson compile --clean -C builddir

You should know though that this is not normal. Other tools just have a clean command, but meson made the "genius" decision to add an option to compile that cleans your builddir but...then doesn't actually do the compile. It's weird so just remember you have to pass an option to meson compile to get it to --clean.

If this doesn't work, or you want to do a "hard reset" then you can remove the directory and reset it. On Linux or OSX you do this:

rm -rf builddir
meson setup --reconfigure builddir

On Windows you can do a similar command:

rm -recurse -force builddir
meson setup --reconfigure builddir

Once you do that it's guaranteed to be completely reset and you can run the compile command to rebuild.

Where's Your Executable?

After you run the build command meson compile -C builddir it will place all output in the builddir, which includes your executables. To run the ex02 executable after this you simply type:

./builddir/ex02

And it will run like before.

What You Should See

When you run your build with all the commands it looks like this:

$ meson setup --reconfigure builddir
Cleaning... 0 files.
The Meson build system
Version: 1.4.1
Source dir: .
Build dir: .\builddir
Build type: native build
Project name: learn-cpp-the-hard-way
Project version: undefined
C++ compiler for the host machine: c++ (gcc 10.2.0 "c++ (MinGW-W64 x86_64-posix-seh, built by Brecht Sanders) 10.2.0")
C++ linker for the host machine: c++ ld.bfd 2.36.1
Host machine cpu family: x86_64
Host machine cpu: x86_64
Build targets in project: 1

Found ninja-1.12.1 at "C:\Program Files\Meson\ninja.EXE"

$ meson compile --clean -C builddir
ninja: Entering directory `./builddir'
[1/1] Cleaning
Cleaning... 2 files.
INFO: autodetecting backend as ninja
INFO: calculating backend command to run: "C:\Program Files\Meson\ninja.EXE" -C ./builddir clean

$ meson compile -C builddir
ninja: Entering directory `./builddir'
[1/2] Compiling C++ object ex02.exe.p/ex02.cpp.obj
[2/2] Linking target ex02.exe
INFO: autodetecting backend as ninja
INFO: calculating backend command to run: "C:\Program Files\Meson\ninja.EXE" -C ./builddir

Just remember, most of the time, you only need to run:

meson compile -C builddir

For most of your work. This command is nice because it will rebuild all of your source files, but only if they need to be recompiled. If you got back to change ex02.cpp then this one command will buid it again. Add a new source file to meson.build and this one command will build it.

Adding a New Source File

When you go to a new exercise, you'll simply copy the executable() line in your meson.build, change it to the new source file, and rerun meson compile -C builddir to build it. For example, let's say you want to create ex05.cpp. Copy the last line that compiles ex02.cpp and make your file look like this:

View Source file ex03b.build Only

project('learn-cpp-the-hard-way', 'cpp',
    default_options: ['cpp_std=c++20'])

executable('ex02', 'ex02.cpp')
executable('ex05', 'ex05.cpp')

Then you rerun the compile command meson compile -C builddir and you're done. Meson will figure out there's new source to build, and build it.

Further Study

Take the time now to make sure your build file is correct and you can build your ex02.cpp code. Come back to this exercise when you want to start a new project and need a build file.