docs/mac_build_instructions.md

   1 # Mac Build Instructions
   2
   3 [TOC]
   4
   5 ## Prerequisites
   6
   7 *   A Mac running 10.8+.
   8 *   http://developer.apple.com/tools/xcode/XCode, 5+
   9 *   Install
  10     [gclient](http://dev.chromium.org/developers/how-tos/install-depot-tools),
  11     part of the
  12     [depot_tools](http://dev.chromium.org/developers/how-tos/depottools) package
  13     ([download](http://dev.chromium.org/developers/how-tos/install-depot-tools)).
  14     gclient is a wrapper around svn that we use to manage our working copies.
  15 *   Install [git](http://code.google.com/p/git-osx-installer/) on OSX 10.8. The
  16     system git shipping with OS X 10.9 / Xcode 5 works well too.
  17 *   (optional -- required if you don't have some commands such as svn natively)
  18     Install Xcode's "Command Line Tools" via Xcode menu -> Preferences ->
  19     Downloads
  20
  21 ## Getting the code
  22
  23 [Check out the source code](http://dev.chromium.org/developers/how-tos/get-the-code)
  24 using Git. If you're new to the project, you can skip all the information about
  25 git-svn, since you will not be committing directly to the repository.
  26
  27 Before checking out, go to the
  28 [waterfall](http://build.chromium.org/buildbot/waterfall/) and check that the
  29 source tree is open (to avoid pulling a broken tree).
  30
  31 The path to the build directory should not contain spaces (e.g. not
  32 `~/Mac OS X/chromium`), as this will cause the build to fail. This includes your
  33 drive name, the default "Macintosh HD2" for a second drive has a space.
  34
  35 ## Building
  36
  37 Chromium on OS X can only be built using the [Ninja](ninja_build.md) tool and
  38 the [Clang](clang.md) compiler. See both of those pages for further details on
  39 how to tune the build.
  40
  41 Before you build, you may want to
  42 [install API keys](https://sites.google.com/a/chromium.org/dev/developers/how-tos/api-keys)
  43 so that Chrome-integrated Google services work. This step is optional if you
  44 aren't testing those features.
  45
  46 ### Raising system-wide and per-user process limits
  47
  48 If you see errors like the following:
  49
  50 ```
  51 clang: error: unable to execute command: posix_spawn failed: Resource temporarily unavailable
  52 clang: error: clang frontend command failed due to signal (use -v to see invocation)
  53 ```
  54
  55 you may be running into too-low limits on the number of concurrent processes
  56 allowed on the machine. Check:
  57
  58     sysctl kern.maxproc
  59     sysctl kern.maxprocperuid
  60
  61 You can increase them with e.g.:
  62
  63     sudo sysctl -w kern.maxproc=2500
  64     sudo sysctl -w kern.maxprocperuid=2500
  65
  66 But normally this shouldn't be necessary if you're building on 10.7 or higher.
  67 If you see this, check if some rogue program spawned hundreds of processes and
  68 kill them first.
  69
  70 ## Faster builds
  71
  72 Full rebuilds are about the same speed in Debug and Release, but linking is a
  73 lot faster in Release builds.
  74
  75 Run
  76
  77     GYP_DEFINES=fastbuild=1 build/gyp_chromium
  78
  79 to disable debug symbols altogether, this makes both full rebuilds and linking
  80 faster (at the cost of not getting symbolized backtraces in gdb).
  81
  82 You might also want to [install ccache](ccache_cac.md) to speed up the build.
  83
  84 ## Running
  85
  86 All build output is located in the `out` directory (in the example above,
  87 `~/chromium/src/out`).  You can find the applications at
  88 `{Debug|Release}/ContentShell.app` and `{Debug|Release}/Chromium.app`, depending
  89 on the selected configuration.
  90
  91 ## Unit Tests
  92
  93 We have several unit test targets that build, and tests that run and pass. A
  94 small subset of these is:
  95
  96 *   `unit_tests` from `chrome/chrome.gyp`
  97 *   `base_unittests` from `base/base.gyp`
  98 *   `net_unittests` from `net/net.gyp`
  99 *   `url_unittests` from `url/url.gyp`
 100
 101 When these tests are built, you will find them in the `out/{Debug|Release}`
 102 directory. You can run them from the command line:
 103
 104     ~/chromium/src/out/Release/unit_tests
 105
 106
 107 ## Coding
 108
 109 According to the
 110 [Chromium style guide](http://dev.chromium.org/developers/coding-style) code is
 111 [not allowed to have whitespace on the ends of lines](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Horizontal_Whitespace).
 112 If you edit in Xcode, know that it loves adding whitespace to the ends of lines
 113 which can make editing in Xcode more painful than it should be. The
 114 [GTM Xcode Plugin](http://code.google.com/p/google-toolbox-for-mac/downloads/list)
 115 adds a preference panel to Xcode that allows you to strip whitespace off of the
 116 ends of lines on save. Documentation on how to install it is
 117 [here](http://code.google.com/p/google-toolbox-for-mac/wiki/GTMXcodePlugin).
 118
 119 ## Debugging
 120
 121 Good debugging tips can be found
 122 [here](http://dev.chromium.org/developers/how-tos/debugging-on-os-x). If you
 123 would like to debug in a graphical environment, rather than using `lldb` at the
 124 command line, that is possible without building in Xcode. See
 125 [Debugging in Xcode](http://www.chromium.org/developers/debugging-on-os-x/building-with-ninja-debugging-with-xcode)
 126 for information on how.
 127
 128 ## Contributing
 129
 130 Once you’re comfortable with building Chromium, check out
 131 [Contributing Code](http://dev.chromium.org/developers/contributing-code) for
 132 information about writing code for Chromium and contributing it.
 133
 134 ## Using Xcode-Ninja Hybrid
 135
 136 While using Xcode is unsupported, GYP supports a hybrid approach of using ninja
 137 for building, but Xcode for editing and driving compliation.  Xcode can still be
 138 slow, but it runs fairly well even **with indexing enabled**.
 139
 140 With hybrid builds, compilation is still handled by ninja, and can be run by the
 141 command line (e.g. ninja -C out/Debug chrome) or by choosing the chrome target
 142 in the hybrid workspace and choosing build.
 143
 144 To use Xcode-Ninja Hybrid, set `GYP_GENERATORS=ninja,xcode-ninja`.
 145
 146 Due to the way Xcode parses ninja output paths, it's also necessary to change
 147 the main gyp location to anything two directories deep. Otherwise Xcode build
 148 output will not be clickable. Adding
 149 `xcode_ninja_main_gyp=src/build/ninja/all.ninja.gyp` to your
 150 `GYP_GENERATOR_FLAGS` will fix this.
 151
 152 After generating the project files with gclient runhooks, open
 153 `src/build/ninja/all.ninja.xcworkspace`.
 154
 155 You may run into a problem where http://YES is opened as a new tab every time
 156 you launch Chrome. To fix this, open the scheme editor for the Run scheme,
 157 choose the Options tab, and uncheck "Allow debugging when using document
 158 Versions Browser". When this option is checked, Xcode adds
 159 `--NSDocumentRevisionsDebugMode YES` to the launch arguments, and the `YES` gets
 160 interpreted as a URL to open.
 161
 162 If you want to limit the number of targets visible, which is known to improve
 163 Xcode performance, add `xcode_ninja_executable_target_pattern=%target%` where
 164 `%target%` is a regular expression matching executable targets you'd like to
 165 include.
 166
 167 To include non-executable targets, use `xcode_ninja_target_pattern=All_iOS`.
 168
 169 If you have problems building, join us in `#chromium` on `irc.freenode.net` and
 170 ask there. As mentioned above, be sure that the
 171 [waterfall](http://build.chromium.org/buildbot/waterfall/) is green and the tree
 172 is open before checking out. This will increase your chances of success.
 173
 174 ## Using Emacs as `EDITOR` for `git commit`
 175
 176 Using the [Cocoa version of Emacs](http://emacsformacosx.com/) as the `EDITOR`
 177 environment variable on Mac OS will cause `git commit` to open the message in a
 178 window underneath all the others. To fix this, create a shell script somewhere
 179 (call it `$HOME/bin/EmacsEditor` in this example) containing the following:
 180
 181 ```
 182 #!/bin/sh
 183
 184 # All of these hacks are needed to get "git commit" to launch a new
 185 # instance of Emacs on top of everything else, properly pointing to
 186 # the COMMIT_EDITMSG.
 187
 188 realpath() {
 189     [[ $1 = /* ]] && echo "$1" || echo "$PWD/${1#./}"
 190 }
 191
 192 i=0
 193 full_paths=()
 194 for arg in "$@"
 195 do
 196   full_paths[$i]=$(realpath $arg)
 197   ((++i))
 198 done
 199
 200 open -nWa /Applications/Emacs.app/Contents/MacOS/Emacs --args --no-desktop \
 201     "${full_paths[@]}"
 202 ```
 203
 204 and in your `.bashrc` or similar,
 205
 206     export EDITOR=$HOME/bin/EmacsEditor