tools/gn/docs/faq.md

   1 # GN Frequently Asked Questions
   2
   3 [TOC]
   4
   5 ## How will the build be converted?
   6
   7 We intend to build a second independent build in parallel to the GYP
   8 build. Previous efforts to generate GYP as an intermediate stage proved
   9 difficult. There will be some smaller set of bots compiling this build,
  10 and we'll keep the GN build running on these configurations.
  11
  12 ## What is unsupported in GN?
  13
  14 The main features not supported in GN yet are:
  15   * Mac bundles
  16   * Loadable module (this only matters on Mac where shared library !=
  17     lodable module)
  18   * Precompiled headers
  19
  20 ## Where is the GN documentation?
  21
  22 Rather than on a separate wiki, it is versioned with the tool. Run `gn
  23 help`. See also the [quick start](quick_start.md) guide and the
  24 [language and operation details](language.md).
  25
  26 ## What is likely to break?
  27
  28 Since common.gypi is not used for GN-generated GYP files, any rules
  29 there will no longer apply. There is a _lot_ of logic in there for many
  30 build configurations and various conditions where certain flags should
  31 or should not be used. Some of these build configurations aren't even
  32 supported any more. Some are run on other waterfalls or are used by
  33 individuals manually setting GYP\_DEFINES on their local system.
  34
  35 ## Will XCode/Visual Studio still be supported?
  36
  37 They're not supported now.
  38
  39 Long-term, if your use-case is to use Ninja for building but Visual
  40 Studio or XCode for debugging, there is desire to write a simple wrapper
  41 around Ninja that lists the files in Visual Studio or XCode format, and
  42 has a command to run ninja for when you press build. This setup should
  43 provide the type of interactive debugging experience people want (the
  44 iOS team currently uses a Ninja/XCode build like this with success).
  45
  46 This project is not staffed. If you're interested, it probably isn't too
  47 hard. It won't get done unless somebody volunteers. There is a [spec for
  48 IDE
  49 integration](https://docs.google.com/document/d/1kwREU99u8GpRammLbbKwrfaDI6WV7nsMAaoF5dcuhOU/edit?usp=sharing).
  50
  51 ## I'm weird. Will my uncommon build mode be supported?
  52
  53 One of the main benefits of the build changeover is that it will
  54 encourage us to refactor the build system. The project has generally not
  55 been as strict with build complexity and maintenance as we have with
  56 source code, and a lot of cruft has accumulated.
  57
  58 In most cases, we will want to rethink how build flags are supported. We
  59 want to be more modular rather than throwing everything in the
  60 common.gypi equivalent. The bar for additions at this level will be very
  61 high, and we will need to figure out how to design certain build
  62 features. If you are interested in some weird configurations, this will
  63 likely make your life more difficult in the short term, but will
  64 hopefully bring long-term benefits for everybody.
  65
  66 In some cases, we may decide that the overhead of supporting your build
  67 for BeOS running on a DEC Alpha is not in the interests of the project.
  68 There will likely be discussions about where to draw the line, and how
  69 to allow those who want to do weird things to do them cleanly without
  70 negatively affecting the rest of the Chromium community.
  71
  72 ## I'm only a little bit weird, will my development build flag be supported?
  73
  74 Only if you do it yourself!
  75
  76 Some features have build flags that turn on a debugging mode or switch
  77 between internal/external builds. This can be supported, but  as with
  78 GYP, your team will have to add an maintain the support.
  79
  80 ## I use supplement.gypi, what's the GN equivalent?
  81
  82 Some projects use files called `supplement.gypi` to set build flags. GYP
  83 looks in each directory under `src` and adds merges these files into the
  84 build. The model is that then adding something to your gclient to add
  85 something to your build (e.g `src-internal`) automatically sets flags.
  86
  87 This behavior is fragile and mysterious. Some people get build flags and
  88 they don't know why. If you remove the entry from your `.gclient` and
  89 don't remove the directory you'll be stuck on an old version of the
  90 flags/code and not know why. You can't have builds in the same checkout
  91 with the corresponding flags on and off. Some people and projects were
  92 abusing this behavior.
  93
  94 In GN, such things should be done with build arguments (`gn args`) and
  95 configured on your build directory when you set it up. For some people,
  96 this will be an extra step. But it is explicit and clear, and you can
  97 have multiple builds in the same checkout with different flags.
  98
  99 ## How do I generate common build variants?
 100
 101 In GN, args go with a build directory rather than being global in the
 102 environment. To edit the args for your `out/Default` build directory:
 103
 104 ```
 105 gn args out/Default
 106 ```
 107
 108 You can set variables in that file:
 109
 110   * The default is a debug build. To do a release build add
 111     `is_debug = false`
 112   * The default is a static build. To do a component build add
 113     `is_component_build = true`
 114   * The default is a developer build. To do an official build, set
 115     `is_official_build = true`
 116   * The default is Chromium branding. To do Chrome branding, set
 117     `is_chrome_branded = true`
 118
 119 ## How do I do cross-compiles?
 120
 121 GN has robust support for doing cross compiles and building things for
 122 multiple architectures in a single build.
 123
 124 See [GNCrossCompiles](cross_compiles.md) for more info.