Minimal GN project

GN is a meta-build-system invented by the Chromium authors to build Chromium on multiple platforms. It generates NinjaBuild files which are then used to build the actual product. (GN == Generate Ninja)

It is a great build system, but heavily tied to Chromium. Only very few projects use it outside of Chromium, and there is very little documentation how to use it.

This project is a minimalistic Hello, World! cross platform GN build. It is ment to help others to learn more about GN and serve as a boilerplate for your own projects.

Prerequisites

You need to install Chromium's depot_tools.

Getting the code

Run these commands in an empty directory:

gclient config --unmanaged https://github.com/skopf/minimal-gn-project.git
gclient sync

The first command will create a .glient file pointing to this project. The second command will pull this project and all its dependancies.

Directory structure of minimal GN project

Once gclient sync finished, you will have a minimal-gn-project directory with this structure:

 minimal-gn-project (needs to be under GIT management)
  |
  +-- [build] --> https://chromium.googlesource.com/chromium/src/build.git@xxxx
  |
  +-- [buildtools] --> https://chromium.googlesource.com/chromium/buildtools.git@xxx
  |
  +-- tools
  |    |
  |    `-- [gyp] --> https://chromium.googlesource.com/external/gyp.git@xxx
  |
  +-- build_overrides
  |    |
  |    `-- build.gni
  |
  +-- (out) (generated by GN)
  |
  +-- lib
  |    |
  |    +-- say_hello.cc
  |    |
  |    +-- say_hello.h
  |    |
  |    `-- BUILD.GN  (defining the 'say_hello' static library)
  |
  +-- app
  |    |
  |    +-- hello_world.cc
  |    |
  |    `-- BUILD.GN  (defining the 'hello_world' executable)
  |
  +-- .gn  (pointing to BUILDCONFIG in //build directory)
  |
  +-- BUILD.gn  (umbrella project pointing to sub-projects, '/app' in our case)
  |
  `-- DEPS  (optional, required to use gclient to organize the project)

Please note that the topmost directory must be under git management. This is required by GN. You cannot setup a GN built project in a plain vanilla folder.

File content

This setup pulls many parts from the Chromium build. The project specific custom parts have the following content and meaning:

File	Content
build_overrides/build.gni	Multiple defines of variables required by the Chromium build process
app/hello_world.cc	Source file of the main application
app/BUILD.gn	GN project file for the main application
lib/say_hello.*	Source files of the static library
lib/BUILD.gn	GN project file for the static library
.gn	pointing to the buildconfig and secondary_source
BUILD.gn	top-level umbrella project pulling all sub-projects together
DEPS	(optional) declares dependencies so that this project can be managed by gclient

Build the project

In the minimal-gn-project directory, run this command:

gn gen out

This will create a Ninja build files in the new directoty out. Next, we run ninja to build our app:

ninja -C out

The hello_world executable has now been created in out. You can replace the name out with any name of your liking, or even use multiple different directories for different build configurations.

IDE integration

You will always build with Ninja, not the IDE. But there are integrations for different IDEs. GN can generate project files for different IDEs that then invoke GN and Ninja to build the project. For example:

gn gen --ide=vs2015 out

This will give you a Visual Studio 2015 Solution file: out/all.sln