diff options
| -rw-r--r-- | HACKING | 76 | ||||
| -rw-r--r-- | HACKING.md | 113 |
2 files changed, 113 insertions, 76 deletions
diff --git a/HACKING b/HACKING deleted file mode 100644 index 4e01d49..0000000 --- a/HACKING +++ /dev/null @@ -1,76 +0,0 @@ -Adjusting build flags: - CFLAGS=-O3 ./configure.py - and rebuild. - -Building tests requires gtest, to get it: - - On older Ubuntus you can apt-get install libgtest. - - On newer Ubuntus it's only distributed as source; - 1) apt-get install libgtest-dev - 2) ./configure --with-gtest=/usr/src/gtest - - Otherwise you need to download it, unpack it, and pass --with-gtest - as appropriate. - -Test-driven development: - Set your build command to - ./ninja ninja_test && ./ninja_test --gtest_filter=MyTest.Name - now you can repeatedly run that while developing until the tests pass. - Remember to build "all" before committing to verify the other source - still works! - -Testing performance impact of changes: - If you have a Chrome build handy, it's a good test case. - Otherwise, https://github.com/martine/ninja/downloads has a copy of - the Chrome build files (and depfiles). You can untar that, then run - path/to/my/ninja chrome - and compare that against a baseline Ninja. - - There's a script at misc/measure.py that repeatedly runs a command like - the above (to address variance) and summarizes its runtime. E.g. - path/to/misc/measure.py path/to/my/ninja chrome - - For changing the depfile parser, you can also build 'parser_perftest' - and run that directly on some representative input files. - -Coding guidelines: -- Function name are camelcase. -- Member methods are camelcase, expect for trivial getters which are - underscore separated. -- Local variables are underscore separated. -- Member variables are underscore separated and suffixed by an extra underscore. -- Two spaces indentation. -- Opening braces is at the end of line. -- Lines are 80 columns maximum. -- All source files should have the Google Inc. license header. -- Also follow this style: - http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml - -Documentation guidelines: -- Use /// for doxygen. -- Use \a to refer to arguments. -- It's not necessary to document each argument, especially when they're - relatively self-evident (e.g. in CanonicalizePath(string* path, string* err), - the arguments are hopefully obvious) - -Generating the manual: - sudo apt-get install asciidoc --no-install-recommends - ./ninja manual - -Windows development on Linux (this is kind of hacky right now): -- Get the gtest source, unpack it into your source dir -- sudo apt-get install gcc-mingw32 wine -- export CC=i586-mingw32msvc-cc CXX=i586-mingw32msvc-c++ AR=i586-mingw32msvc-ar -- ./configure.py --platform=mingw --host=linux --with-gtest=gtest-1.6.0 -- Build ninja: /path/to/linux/ninja -- Run: ./ninja.exe (implicitly runs through wine(!)) - -Windows development on Windows: -- install mingw, msys, and python -- in the mingw shell, put Python in your path, and: python bootstrap.py -- to reconfigure, run 'python configure.py' -- remember to strip the resulting executable if size matters to you -- you'll need to rename ninja.exe into my-ninja.exe during development, - otherwise ninja won't be able to overwrite itself when building - -Using clang: -- Enable colors manually: - CXX='/path/to/llvm/Release+Asserts/bin/clang++ -fcolor-diagnostics' ./configure.py diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 0000000..aa965ca --- /dev/null +++ b/HACKING.md @@ -0,0 +1,113 @@ + +### Adjusting build flags + + CFLAGS=-O3 ./configure.py + +### Testing + +#### Installing gtest + +* On older Ubuntus it'll install as libraries into `/usr/lib`: + + apt-get install libgtest + +* On newer Ubuntus it's only distributed as source + + apt-get install libgtest-dev + ./configure --with-gtest=/usr/src/gtest + +* Otherwise you need to download it, unpack it, and pass --with-gtest + as appropriate. + +#### Test-driven development + +Set your build command to + + ./ninja ninja_test && ./ninja_test --gtest_filter=MyTest.Name + +now you can repeatedly run that while developing until the tests pass. +Remember to build "all" before committing to verify the other source +still works! + +### Testing performance impact of changes + +If you have a Chrome build handy, it's a good test case. +Otherwise, https://github.com/martine/ninja/downloads has a copy of +the Chrome build files (and depfiles). You can untar that, then run + + path/to/my/ninja chrome + +and compare that against a baseline Ninja. + +There's a script at `misc/measure.py` that repeatedly runs a command like +the above (to address variance) and summarizes its runtime. E.g. + + path/to/misc/measure.py path/to/my/ninja chrome + +For changing the depfile parser, you can also build `parser_perftest` +and run that directly on some representative input files. + +## Coding guidelines + +Generally it's the [Google C++ coding style][], but in brief: + +* Function name are camelcase. +* Member methods are camelcase, expect for trivial getters which are + underscore separated. +* Local variables are underscore separated. +* Member variables are underscore separated and suffixed by an extra underscore. +* Two spaces indentation. +* Opening braces is at the end of line. +* Lines are 80 columns maximum. +* All source files should have the Google Inc. license header. + +[Google C++ coding style]: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml + +## Documentation + +### Style guidelines + +* Use `///` for doxygen. +* Use `\a` to refer to arguments. +* It's not necessary to document each argument, especially when they're + relatively self-evident (e.g. in `CanonicalizePath(string* path, string* err)`, + the arguments are hopefully obvious) + +### Building the manual + + sudo apt-get install asciidoc --no-install-recommends + ./ninja manual + +## Building on Windows + +While developing, it's helpful to copy `ninja.exe` to another name like +`n.exe`; otherwise, rebuilds will be unable to write `ninja.exe` because +it's locked while in use. + +### Via Visual Studio + +* Install Visual Studio (Express is fine), [Python for Windows][], + and (if making changes) googletest (see above instructions) +* In a Visual Studio command prompt: `python bootstrap.py` + +[Python for Windows]: http://www.python.org/getit/windows/ + +### Via mingw on Linux (not well supported) + +* `sudo apt-get install gcc-mingw32 wine` +* `export CC=i586-mingw32msvc-cc CXX=i586-mingw32msvc-c++ AR=i586-mingw32msvc-ar` +* `./configure.py --platform=mingw --host=linux` +* Build `ninja.exe` using a Linux ninja binary: `/path/to/linux/ninja` +* Run: `./ninja.exe` (implicitly runs through wine(!)) + +### Via mingw on Windows (not well supported) +* Install mingw, msys, and python +* In the mingw shell, put Python in your path, and: python bootstrap.py +* To reconfigure, run `python configure.py` +* Remember to strip the resulting executable if size matters to you + +## Clang + +Enable colors manually via `-fcolor-diagnostics`: + + CXX='/path/to/llvm/Release+Asserts/bin/clang++ -fcolor-diagnostics' ./configure.py |