HACKING.md

   1
   2 ### Adjusting build flags
   3
   4     CFLAGS=-O3 ./configure.py
   5
   6 ### Testing
   7
   8 #### Installing gtest
   9
  10 * On older Ubuntus it'll install as libraries into `/usr/lib`:
  11
  12         apt-get install libgtest
  13
  14 * On newer Ubuntus it's only distributed as source
  15
  16         apt-get install libgtest-dev
  17         ./configure --with-gtest=/usr/src/gtest
  18
  19 * Otherwise you need to download it, unpack it, and pass --with-gtest
  20   as appropriate.
  21
  22 #### Test-driven development
  23
  24 Set your build command to
  25
  26     ./ninja ninja_test && ./ninja_test --gtest_filter=MyTest.Name
  27
  28 now you can repeatedly run that while developing until the tests pass.
  29 Remember to build "all" before committing to verify the other source
  30 still works!
  31
  32 ### Testing performance impact of changes
  33
  34 If you have a Chrome build handy, it's a good test case.
  35 Otherwise, https://github.com/martine/ninja/downloads has a copy of
  36 the Chrome build files (and depfiles). You can untar that, then run
  37
  38     path/to/my/ninja chrome
  39
  40 and compare that against a baseline Ninja.
  41
  42 There's a script at `misc/measure.py` that repeatedly runs a command like
  43 the above (to address variance) and summarizes its runtime.  E.g.
  44
  45     path/to/misc/measure.py path/to/my/ninja chrome
  46
  47 For changing the depfile parser, you can also build `parser_perftest`
  48 and run that directly on some representative input files.
  49
  50 ## Coding guidelines
  51
  52 Generally it's the [Google C++ coding style][], but in brief:
  53
  54 * Function name are camelcase.
  55 * Member methods are camelcase, expect for trivial getters which are
  56   underscore separated.
  57 * Local variables are underscore separated.
  58 * Member variables are underscore separated and suffixed by an extra underscore.
  59 * Two spaces indentation.
  60 * Opening braces is at the end of line.
  61 * Lines are 80 columns maximum.
  62 * All source files should have the Google Inc. license header.
  63
  64 [Google C++ coding style]: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
  65
  66 ## Documentation
  67
  68 ### Style guidelines
  69
  70 * Use `///` for doxygen.
  71 * Use `\a` to refer to arguments.
  72 * It's not necessary to document each argument, especially when they're
  73   relatively self-evident (e.g. in `CanonicalizePath(string* path, string* err)`,
  74   the arguments are hopefully obvious)
  75
  76 ### Building the manual
  77
  78     sudo apt-get install asciidoc --no-install-recommends
  79     ./ninja manual
  80
  81 ## Building on Windows
  82
  83 While developing, it's helpful to copy `ninja.exe` to another name like
  84 `n.exe`; otherwise, rebuilds will be unable to write `ninja.exe` because
  85 it's locked while in use.
  86
  87 ### Via Visual Studio
  88
  89 * Install Visual Studio (Express is fine), [Python for Windows][],
  90   and (if making changes) googletest (see above instructions)
  91 * In a Visual Studio command prompt: `python bootstrap.py`
  92
  93 [Python for Windows]: http://www.python.org/getit/windows/
  94
  95 ### Via mingw on Linux (not well supported)
  96
  97 * `sudo apt-get install gcc-mingw32 wine`
  98 * `export CC=i586-mingw32msvc-cc CXX=i586-mingw32msvc-c++ AR=i586-mingw32msvc-ar`
  99 * `./configure.py --platform=mingw --host=linux`
 100 * Build `ninja.exe` using a Linux ninja binary: `/path/to/linux/ninja`
 101 * Run: `./ninja.exe`  (implicitly runs through wine(!))
 102
 103 ### Via mingw on Windows (not well supported)
 104 * Install mingw, msys, and python
 105 * In the mingw shell, put Python in your path, and: python bootstrap.py
 106 * To reconfigure, run `python configure.py`
 107 * Remember to strip the resulting executable if size matters to you
 108
 109 ## Clang
 110
 111 To use clang, set `CXX`:
 112
 113     CXX=clang++ ./configure.py