Using GN for a faster turnaround time

CMake is portable and flexible, and it has been battle-tested by many industrial projects. However, it has some serious issues when it comes to reconfigurations. As we saw in the previous sections, you can modify some of the CMake arguments once build files have been generated by editing the CMakeCache.txt file in the build folder. When you invoke the build command again, CMake will reconfigure the build files. If you edit the CMakeLists.txt files in your source folders, the same reconfiguration will also kick in. There are primarily two drawbacks of CMake's reconfiguration process:

• In some systems, the CMake configuration process is pretty slow. Even for reconfiguration, which theoretically only runs part of the process, it still takes a long time sometimes.
• Sometimes, CMake will fail to resolve the dependencies among different variables and build targets, so your changes will not reflect this. In the worst case, it will just silently fail and take you a long time to dig out the problem.

Generate Ninja, better known as GN, is a build file generator used by many of Google's projects, such as Chromium. GN generates Ninja files from its own description language. It has a good reputation for having a fast configuration time and reliable argument management. LLVM has brought GN support as an alternative (and experimental) building method since late 2018 (around version 8.0.0). GN is especially useful if your developments make changes to build files, or if you want to try out different building options in a short period.

Perform the following steps to use GN to build LLVM:

1. LLVM's GN support is sitting in the llvm/utils/gn folder. After switching to that folder, run the following get.py script to download GN's executable locally:

   $ cd llvm/utils/gn
   $ ./get.py

   Using a specific version of GN

   If you want to use a custom GN executable instead of the one fetched by get.py, simply put your version into the system's PATH. If you are wondering what other GN versions are available, you might want to check out the instructions for installing depot_tools at https://dev.chromium.org/developers/how-tos/install-depot-tools.

2. Use gn.py in the same folder to generate build files (the local version of gn.py is just a wrapper around the real gn, to set up the essential environment):

   $ ./gn.py gen out/x64.release

   out/x64.release is the name of the build folder. Usually, GN users will name the build folder in <architecture>.<build type>.<other features> format.

3. Finally, you can switch into the build folder and launch Ninja:

   $ cd out/x64.release
   $ ninja <build target>

4. Alternatively, you can use the -C Ninja option:

   $ ninja -C out/x64.release <build target>

You probably already know that the initial build file generation process is super fast. Now, if you want to change some of the build arguments, please navigate to the args.gn file under the build folder (out/x64.release/args.gn, in this case); for example, if you want to change the build type to debug and change the targets to build (that is, the LLVM_TARGETS_TO_BUILD CMake argument) into X86 and AArch64. It is recommended to use the following command to launch an editor to edit args.gn:

$ ./gn.py args out/x64.release

In the editor of args.gn, input the following contents:

# Inside args.gn
is_debug = true
llvm_targets_to_build = ["X86", "AArch64"]

Once you've saved and exited the editor, GN will do some syntax checking and regenerate the build files (of course, you can edit args.gn without using the gn command and the build files won't be regenerated until you invoke the ninja command). This regeneration/reconfiguration will also be fast. Most importantly, there won't be any infidelity behavior. Thanks to GN's language design, relationships between different build arguments can be easily analyzed with little ambiguity.

The list of GN's build arguments can be found by running this command:

$ ./gn.py args --list out/x64.release

Unfortunately, at the time of writing this book, there are still plenty of CMake arguments that haven't been ported to GN. GN is not a replacement for LLVM's existing CMake build system, but it is an alternative. Nevertheless, GN is still a decent building method if you want a fast turnaround time in your developments that involve many build configuration changes.