docs/updating_clang_format_binaries.md

   1 # Updating Clang format binaries
   2
   3 Instructions on how to update the [clang-format binaries](clang_format.md) that
   4 come with a checkout of Chromium.
   5
   6 ## Prerequisites
   7
   8 You'll need a Windows machine, a Linux machine, and a Mac; all capable of
   9 building clang-format. You'll also need permissions to upload to the appropriate
  10 google storage bucket. Chromium infrastructure team members have this, and
  11 others can be granted the permission based on need. Talk to ncarter or hinoka
  12 about getting access.
  13
  14 ## Pick a head svn revision
  15
  16 Consult http://llvm.org/svn/llvm-project/ for the current head revision. This
  17 will be the CLANG_REV you'll use later to check out each platform to a
  18 consistent state.
  19
  20 ## Build a release-mode clang-format on each platform
  21
  22 Follow the the official instructions here:
  23 http://clang.llvm.org/get_started.html.
  24
  25 Windows step-by-step:
  26
  27 ```shell
  28 # [double check you have the tools you need]
  29 where cmake.exe  # You need to install this.
  30 where svn.exe  # Maybe fix with: set PATH=%PATH%;D:\src\depot_tools\svn_bin
  31 "c:\Program Files (x86)\Microsoft Visual Studio 12.0\vc\vcvarsall.bat" amd64_x86
  32
  33 set CLANG_REV=198831  # You must change this value (see above)
  34
  35 [from a clean directory, check out and build]
  36 rmdir /S /Q llvm
  37 rmdir /S /Q llvm-build
  38 mkdir llvm
  39 mkdir llvm-build
  40 svn co http://llvm.org/svn/llvm-project/llvm/trunk@%CLANG_REV% llvm
  41 cd llvm\tools
  42 svn co http://llvm.org/svn/llvm-project/cfe/trunk@%CLANG_REV% clang
  43 cd ..\..\llvm-build
  44 set CC=cl
  45 set CXX=cl
  46 cmake -G Ninja ..\llvm -DCMAKE_BUILD_TYPE=Release -DLLVM_USE_CRT_RELEASE=MT \
  47     -DLLVM_ENABLE_ASSERTIONS=NO -DLLVM_ENABLE_THREADS=NO \
  48     -DPYTHON_EXECUTABLE=d:\src\depot_tools\python276_bin\python.exe
  49 ninja clang-format
  50 bin\clang-format.exe --version
  51 ```
  52
  53 Mac & Linux step-by-step:
  54
  55 ```shell
  56 # Check out.
  57 export CLANG_REV=198831   # You must change this value (see above)
  58 rm -rf llvm
  59 rm -rf llvm-build
  60 mkdir llvm
  61 mkdir llvm-build
  62 svn co http://llvm.org/svn/llvm-project/llvm/trunk@$CLANG_REV llvm
  63 cd llvm/tools
  64 svn co http://llvm.org/svn/llvm-project/cfe/trunk@$CLANG_REV clang
  65 cd ../../llvm-build
  66
  67 # Option 1: with cmake
  68 MACOSX_DEPLOYMENT_TARGET=10.9 cmake -G Ninja  -DCMAKE_BUILD_TYPE=Release \
  69     -DLLVM_ENABLE_ASSERTIONS=NO -DLLVM_ENABLE_THREADS=NO ../llvm/
  70 time caffeinate ninja clang-format
  71 strip bin/clang-format
  72
  73 # (On Linux, to build with clang, which produces smaller binaries, add this to
  74 # your cmake invocation.
  75 # On Mac, the system compiler is already clang so it's not needed there.)
  76 -DCMAKE_C_COMPILER=$PWD/../chrome/src/third_party/llvm-build/Release+Asserts/bin/clang -DCMAKE_CXX_COMPILER=$PWD/../chrome/src/third_party/llvm-build/Release+Asserts/bin/clang++
  77 ```
  78
  79 TODO: these ^^ instructions looks odd. Are they correct???
  80
  81 Platform specific notes:
  82
  83 *   Windows: Visual Studio 2013 only.
  84 *   Linux: so far (as of January 2014) we've just included a 64-bit binary. It's
  85     important to disable threading, else clang-format will depend on
  86     libatomic.so.1 which doesn't exist on Precise.
  87 *   Mac: Remember to set `MACOSX_DEPLOYMENT_TARGET` when building! If you get
  88     configure warnings, you may need to install XCode 5 and avoid a goma
  89     environment.
  90
  91 ## Upload each binary to google storage
  92
  93 Copy the binaries into your chromium checkout (under
  94 `src/buildtools/(win|linux64|mac)/clang-format(.exe?)`). For each binary, you'll
  95 need to run upload_to_google_storage.py according to the instructions in
  96 [README.txt](/buildtools/clang_format/README.txt). This will upload the binary
  97 into a publicly accessible google storage bucket, and update `.sha1` file in
  98 your Chrome checkout. You'll check in the `.sha1` file (but NOT the clang-format
  99 binary) into source control. In order to be able to upload, you'll need write
 100 permission to the bucket -- see the prerequisites.
 101
 102 ## Copy the helper scripts and update README.chromium
 103
 104 There are some auxiliary scripts that ought to be kept updated in lockstep with
 105 the clang-format binary. These get copied into
 106 third_party/clang_format/scripts in your Chromium checkout.
 107
 108 The `README.chromium` file ought to be updated with version and date info.
 109
 110 ## Upload a CL according to the following template
 111
 112     Update clang-format binaries and scripts for all platforms.
 113
 114     I followed these instructions:
 115     https://chromium.googlesource.com/chromium/src/+/master/docs/updating_clang_format_binaries.md
 116
 117     The binaries were built at clang revision ####### on ####DATETIME####.
 118
 119     BUG=
 120
 121 The change should **always** include new `.sha1` files for each platform (we
 122 want to keep these in lockstep), should **never** include `clang-format`
 123 binaries directly. The change should **always** update `README.chromium`
 124
 125 clang-format binaries should weigh in at 1.5MB or less. Watch out for size
 126 regressions.