From e5415f6d8623e72144cbc9d163d53bf0c2070dbf Mon Sep 17 00:00:00 2001 From: Andrew Kaster Date: Mon, 8 Apr 2024 13:15:00 -0600 Subject: [PATCH] Documentation: Add more specific instructions on how to use the GN build --- Documentation/BuildInstructionsLadybird.md | 9 ++++ Meta/gn/README.md | 54 +++++++++++++++++++++- 2 files changed, 62 insertions(+), 1 deletion(-) diff --git a/Documentation/BuildInstructionsLadybird.md b/Documentation/BuildInstructionsLadybird.md index 77b8914a5a5..ad5c3ab7275 100644 --- a/Documentation/BuildInstructionsLadybird.md +++ b/Documentation/BuildInstructionsLadybird.md @@ -175,6 +175,15 @@ open -W --stdout $(tty) --stderr $(tty) ./Build/ladybird/bin/Ladybird.app open -W --stdout $(tty) --stderr $(tty) ./Build/ladybird/bin/Ladybird.app --args https://ladybird.dev ``` +### Experimental GN build + +There is an experimental GN build for Ladybird. It is not officially supported, but it is kept up to date on a best-effort +basis by interested contributors. See the [GN build instructions](../Meta/gn/README.md) for more information. + +In general, the GN build organizes ninja rules in a more compact way than the CMake build, and it may be faster on some systems. +GN also allows building host and cross-targets in the same build directory, which is useful for managing dependencies on host tools when +cross-compiling to other platforms. + ### Debugging with CLion Ladybird should be built with debug symbols first. In `Meta/CMake/lagom_compile_options.cmake` remove the optimizations by changing `-O2` to `-O0`. For macOS also change the debug option from `-g1` to `-g` so that lldb is happy with the emitted symbols. In linux `-g1` can be changed to `-ggdb3` for maximum debug info. diff --git a/Meta/gn/README.md b/Meta/gn/README.md index faa964ad4dc..957df113286 100644 --- a/Meta/gn/README.md +++ b/Meta/gn/README.md @@ -6,7 +6,35 @@ GN is a metabuild system. It always creates ninja files, but it can create some This is a good [overview of GN](https://docs.google.com/presentation/d/15Zwb53JcncHfEwHpnG_PoIbbzQ3GQi_cpujYwbpcbZo/edit#slide=id.g119d702868_0_12). -For more information, motivation, philosophy, and inspriation, see the LLVM documentation on its [GN build](https://github.com/llvm/llvm-project/tree/main/llvm/utils/gn#quick-start) +For more information, motivation, philosophy, and inspiration, see the LLVM documentation on its [GN build](https://github.com/llvm/llvm-project/tree/main/llvm/utils/gn#quick-start) + +# Creating a gn build + +To create a GN build, you need to have GN installed. You can install it via homebrew on macOS, or via your package manager on Linux. +On Ubuntu 22.04, the main package repos do not have an up to date enough package for GN, so you will need to build it from source or get a binary from Google. + +The easiest way to build GN from source is to use our [Toolchain/BuildGN.sh](../../Toolchain/BuildGN.sh) script, which will +drop the built binary into the `Toolchain/Local/gn/bin` directory. The instructions for downloading a prebuilt binary from Google are +[here](https://gn.googlesource.com/gn/+/refs/heads/main#getting-a-binary). + +Once you have GN installed, you can create a build directory by running the following commands: + +```sh +gn gen out +``` + +`gn gen` creates a ninja build in the `out` directory. You can then build the project with ninja: + +```sh +ninja -C out +``` + +If GN or ninja report a bunch of errors, it's likely that you need to create an `args.gn` that points to all the required tools. +`args.gn` belongs at the root of the build directory, and can be placed there before running gn gen, or modified with +`gn args `. See the section below for a typical `args.gn`. + +If you modify `args.gn` outside of `gn args`, be sure to run `gn gen` again to regenerate the ninja files. + # Typical gn args @@ -28,3 +56,27 @@ qt_install_libexec="/usr/lib/qt6/libexec/" ``` As with any gn project, ``gn args --list`` is your best friend. + +# Running binaries from the GN build + +Targets in the gn build are prefixed by the directory they are declared in. For example, to build the default target +in the Ladybird/ directory and LibWeb, you would run: + +```shell +ninja -C out Ladybird +ninja -C out Userland/Libraries/LibWeb +``` + +Binaries are placed in the `out/bin` directory, and can be run from there. + +```shell +./out/bin/Ladybird +# or on macOS +open -W --stdout $(tty) --stderr $(tty) ./out/bin/Ladybird.app --args https://ladybird.dev +``` + +There is also an incomplete target for SerenityOS, which can be tested with: + +```shell +ninja -C out serenity +```