/gn-build

Basic //build directory for use with Chromium's GN

Primary LanguagePython

//build directory for GN-based projects

This project provides a work-in-progress standalone version of the toolchains and configs used by the Chromium project.

Supported platforms

The toolchains have been tested on the following platforms:

  • Windows (MSVC 2013/2015/2017/2019/2022, Clang 3.8 - 17.0)
  • FreeBSD (GCC 6, Clang 11)
  • Linux (GCC 6, Clang 3.8)
  • OS X (Xcode 7.3.1)

The testsrc branch contains the test/example project used by the CI tests.

Reference

Basic variables

All variables described here are build args and can be overridden in the user's args.gn file.

(these variables are available everywhere)

  • is_debug (default: true): Toggle between debug and release builds.
  • is_clang (default: false): Favor Clang over the platform default (GCC/MSVC).
  • is_official_build (default: !is_debug): Set to enable the official build level of optimization. This enables an additional level of optimization above release (!is_debug).
  • external (default: "//external"): Label of the external projects directory. By convention, all 3rd-party projects should end up in this directory, so they can depend on each other (e.g. $external/mysql_connector -> $external/zlib)
  • use_lld (default: false): Use the new LLD linker. This requires is_clang to be true.
  • clang_base_path (default: ""): The path of your Clang installation folder (without /bin). If you use Clang on Windows, you are required to set this, as the Clang installation isn't automatically detected.
  • gcc_version (default: auto-detected): Version of the GCC compiler. Note: Auto-detection is toolchain-specific and happens only if GCC is the active compiler.
    Format: major * 10000 + minor * 100 + patchlevel
  • clang_version (default: auto-detected): Version of the Clang compiler. Note: Auto-detection is toolchain-specific and happens only if Clang is the active compiler.
    Format: major * 10000 + minor * 100 + patchlevel
  • msc_ver (default: auto-detected): Value of the _MSC_VER variable. See https://msdn.microsoft.com/en-us/library/b0084kay.aspx. Note: Auto-detection happens only when targeting Windows.
  • msc_full_ver (default: auto-detected): Value of the _MSC_FULL_VER variable. See https://msdn.microsoft.com/en-us/library/b0084kay.aspx. Note: Auto-detection happens only when targeting Windows.

Windows toolchain

  • visual_studio_version (default: "latest"): Desired version of Visual Studio. If visual_studio_path is set, this must be the version of the VS installation at the visual_studio_path.

    Use "2013" for Visual Studio 2013 or "latest" for automatically choosing the highest version (visual_studio_path must be unset in this case).

  • visual_studio_path (default: auto-detected): The path of your MSVC installation. If this is set you must set visual_studio_version as well. Autodetected based on visual_studio_version.

  • windows_sdk_version (default: auto-detected): Windows SDK version to use. Can either be a full Windows 10 SDK number (e.g. 10.0.10240.0), "8.1" for the Windows 8.1 SDK or "default" for the default SDK selected by VS.

  • clang_msc_ver (default: auto-detected): MSVC version clang-cl will report in _MSC_VER.

POSIX toolchain

This is the default toolchain for POSIX operating systems, which is used for all POSIX systems that don't have special toolchains.

  • gcc_cc (default: gcc): Path of the GCC C compiler executable. Does not have to be absolute.
  • gcc_cxx (default: g++): Path of the GCC C++ compiler executable. Does not have to be absolute.
  • clang_cc (default: clang): Path of the Clang C compiler executable. Does not have to be absolute. Note: If clang_base_path is set, the default will be clang_base_path/bin/clang.
  • clang_cxx (default: clang++): Path of the Clang C++ compiler executable. Does not have to be absolute. Note: If clang_base_path is set, the default will be clang_base_path/bin/clang++.

Mac/iOS toolchain

  • use_system_xcode (default: true): Use the system install of Xcode for tools like ibtool, libtool, etc. This does not affect the compiler. When this variable is false, targets will instead use a hermetic install of Xcode.
  • hermetic_xcode_path (default: ""): The path to the hermetic install of Xcode. Only relevant when use_system_xcode = false.
  • use_xcode_clang (default: true): Compile with Xcode version of clang instead of hermetic version shipped with the build. If true, clang_base_path needs to be set.
  • enable_dsyms (default: true): Produce dSYM files for targets that are configured to do so. dSYM generation is controlled globally as it is a linker output (produced via the //build/toolchain/mac/linker_driver.py. Enabling this will result in all shared library, loadable module, and executable targets having a dSYM generated.
  • enable_stripping (default: is_official_build): Strip symbols from linked targets by default. If this is enabled, the //build/config/mac:strip_all config will be applied to all linked targets. If custom stripping parameters are required, remove that config from a linked target and apply custom -Wcrl,strip flags. See //build/toolchain/mac/linker_driver.py for more information.
  • mac_sdk_min (default: "10.10"): Minimum supported version of the Mac SDK.
  • mac_deployment_target (default: "10.9"): Minimum supported version of OSX.
  • mac_sdk_path (default: ""): Path to a specific version of the Mac SDK, not including a slash at the end. If empty, the path to the lowest version greater than or equal to mac_sdk_min is used.
  • mac_sdk_name (default: "macosx"): The SDK name as accepted by xcodebuild.
  • ios_sdk_path (default: ""): Path to a specific version of the iOS SDK, not including a slash at the end. When empty this will use the default SDK based on the value of use_ios_simulator.

    SDK properties (required when ios_sdk_path is non-empty):

    • ios_sdk_name: The SDK name as accepted by xcodebuild.
    • ios_sdk_version
    • ios_sdk_platform
    • ios_sdk_platform_path
    • xcode_version
    • xcode_build
    • machine_os_build
  • ios_deployment_target (default: "9.0"): Minimum supported version of OSX.

Android toolchain

  • android_ndk_root (default: "$external/android_tools/ndk"): Path of the Android NDK.
  • android_ndk_version (default: "r12b"): NDK Version string.
  • android_ndk_major_version (default: 12): NDK Major version.
  • android_sdk_root (default: "$external/android_tools/sdk"): Path of the Android SDK.
  • android_sdk_version (default: "24"): Android SDK version.
  • android_sdk_build_tools_version (default: "24.0.2"): Version of the Build Tools contained in the SDK.
  • android_libcpp_lib_dir (default: ""): Libc++ library directory. Override to use a custom libc++ binary.
  • use_order_profiling (default: false): Adds intrumentation to each function. Writes a file with the order that functions are called at startup.

Recommended workflow

Fork this repo and add it as a submodule/subtree/DEPS-entry to your project. This way you can modify every part of the //build directory while still being able to easily merge upstream changes (e.g. support for new GN features that you don't want to implement yourself.)

To ease sharing/composition of projects using this //build repo, it is recommended that you refrain from modifying large parts of the toolchains/configs. If changes are necessary, consider contributing them back ;)

For more complex projects, it might be feasible to use a custom build-config file that just import()s //build/config/BUILDCONFIG.gn and then overrides the defaults set inside BUILDCONFIG.gn. There's also GN's default_args scope, which can be used to provide project-specific argument overrides.