mirror of
https://github.com/reactos/ninja.git
synced 2024-11-23 03:39:48 +00:00
Use short CONTRIBUTING.md instead of HACKING.md
* Only the most important parts and some new guidelines in CONTRIBUTING.md. * Complete HACKING.md content moved to the GitHub wiki: https://github.com/ninja-build/ninja/wiki * README is now also Markdown formatted.
This commit is contained in:
Jan Niklas Hasse
parent
6ee71118b8
commit
a37da20ae7
270
CONTRIBUTING.md
270
CONTRIBUTING.md
@ -1,252 +1,34 @@
|
|||||||
## Basic overview
|
# How to successfully make changes to Ninja
|
||||||
|
|
||||||
`./configure.py` generates the `build.ninja` files used to build
|
We're very wary of changes that increase the complexity of Ninja (in particular,
|
||||||
ninja. It accepts various flags to adjust build parameters.
|
new build file syntax or command-line flags) or increase the maintenance burden
|
||||||
Run './configure.py --help' for more configuration options.
|
of Ninja. Ninja is already successfully used by hundreds of developers for large
|
||||||
|
projects and it already achieves (most of) the goals we set out for it to do.
|
||||||
The primary build target of interest is `ninja`, but when hacking on
|
It's probably best to discuss new feature ideas on the
|
||||||
Ninja your changes should be testable so it's more useful to build and
|
[mailing list](https://groups.google.com/forum/#!forum/ninja-build) or in an
|
||||||
run `ninja_test` when developing.
|
issue before creating a PR.
|
||||||
|
|
||||||
### Bootstrapping
|
|
||||||
|
|
||||||
Ninja is built using itself. To bootstrap the first binary, run the
|
|
||||||
configure script as `./configure.py --bootstrap`. This first compiles
|
|
||||||
all non-test source files together, then re-builds Ninja using itself.
|
|
||||||
You should end up with a `ninja` binary (or `ninja.exe`) in the project root.
|
|
||||||
|
|
||||||
#### Windows
|
|
||||||
|
|
||||||
On Windows, you'll need to install Python to run `configure.py`, and
|
|
||||||
run everything under a Visual Studio Tools Command Prompt (or after
|
|
||||||
running `vcvarsall` in a normal command prompt).
|
|
||||||
|
|
||||||
For other combinations such as gcc/clang you will need the compiler
|
|
||||||
(gcc/cl) in your PATH and you will have to set the appropriate
|
|
||||||
platform configuration script.
|
|
||||||
|
|
||||||
See below if you want to use mingw or some other compiler instead of
|
|
||||||
Visual Studio.
|
|
||||||
|
|
||||||
##### Using Visual Studio
|
|
||||||
Assuming that you now have Python installed, then the steps for building under
|
|
||||||
Windows using Visual Studio are:
|
|
||||||
|
|
||||||
Clone and checkout the latest release (or whatever branch you want). You
|
|
||||||
can do this in either a command prompt or by opening a git bash prompt:
|
|
||||||
|
|
||||||
```
|
|
||||||
$ git clone git://github.com/ninja-build/ninja.git && cd ninja
|
|
||||||
$ git checkout release
|
|
||||||
```
|
|
||||||
|
|
||||||
Then:
|
|
||||||
|
|
||||||
1. Open a Windows command prompt in the folder where you checked out ninja.
|
|
||||||
2. Select the Microsoft build environment by running
|
|
||||||
`vcvarsall.bat` with the appropriate environment.
|
|
||||||
3. Build ninja and test it.
|
|
||||||
|
|
||||||
The steps for a Visual Studio 2015 64-bit build are outlined here:
|
|
||||||
|
|
||||||
```
|
|
||||||
> "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x64
|
|
||||||
> python configure.py --bootstrap
|
|
||||||
> ninja --help
|
|
||||||
```
|
|
||||||
Copy the ninja executable to another location, if desired, e.g. C:\local\Ninja.
|
|
||||||
|
|
||||||
Finally add the path where ninja.exe is to the PATH variable.
|
|
||||||
|
|
||||||
### Adjusting build flags
|
|
||||||
|
|
||||||
Build in "debug" mode while developing (disables optimizations and builds
|
|
||||||
way faster on Windows):
|
|
||||||
|
|
||||||
./configure.py --debug
|
|
||||||
|
|
||||||
To use clang, set `CXX`:
|
|
||||||
|
|
||||||
CXX=clang++ ./configure.py
|
|
||||||
|
|
||||||
## How to successfully make changes to Ninja
|
|
||||||
|
|
||||||
Github pull requests are convenient for me to merge (I can just click
|
|
||||||
a button and it's all handled server-side), but I'm also comfortable
|
|
||||||
accepting pre-github git patches (via `send-email` etc.).
|
|
||||||
|
|
||||||
Good pull requests have all of these attributes:
|
|
||||||
|
|
||||||
* Are scoped to one specific issue
|
|
||||||
* Include a test to demonstrate their correctness
|
|
||||||
* Update the docs where relevant
|
|
||||||
* Match the Ninja coding style (see below)
|
|
||||||
* Don't include a mess of "oops, fix typo" commits
|
|
||||||
|
|
||||||
These are typically merged without hesitation. If a change is lacking
|
|
||||||
any of the above I usually will ask you to fix it, though there are
|
|
||||||
obvious exceptions (fixing typos in comments don't need tests).
|
|
||||||
|
|
||||||
I am very wary of changes that increase the complexity of Ninja (in
|
|
||||||
particular, new build file syntax or command-line flags) or increase
|
|
||||||
the maintenance burden of Ninja. Ninja is already successfully used
|
|
||||||
by hundreds of developers for large projects and it already achieves
|
|
||||||
(most of) the goals I set out for it to do. It's probably best to
|
|
||||||
discuss new feature ideas on the [mailing list](https://groups.google.com/forum/#!forum/ninja-build)
|
|
||||||
before I shoot down your patch.
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
### 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
|
|
||||||
(I frequently set it as my compilation command in Emacs). 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. There's a
|
|
||||||
script at `misc/measure.py` that repeatedly runs a command (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
|
## Coding guidelines
|
||||||
|
|
||||||
Generally it's the [Google C++ coding style][], but in brief:
|
Generally it's the
|
||||||
|
[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) with
|
||||||
|
a few additions:
|
||||||
|
|
||||||
* Function name are camelcase.
|
* Any code merged into the Ninja codebase which will be part of the main
|
||||||
* Member methods are camelcase, except for trivial getters which are
|
executable must compile as C++03. You may use C++11 features in a test or an
|
||||||
underscore separated.
|
unimportant tool if you guard your code with `#if __cplusplus >= 201103L`.
|
||||||
* Local variables are underscore separated.
|
* We have used `using namespace std;` a lot in the past. For new contributions,
|
||||||
* Member variables are underscore separated and suffixed by an extra
|
please try to avoid relying on it and instead whenever possible use `std::`.
|
||||||
underscore.
|
However, please do not change existing code simply to add `std::` unless your
|
||||||
* Two spaces indentation.
|
contribution already needs to change that line of code anyway.
|
||||||
* Opening braces is at the end of line.
|
|
||||||
* Lines are 80 columns maximum.
|
|
||||||
* All source files should have the Google Inc. license header.
|
* All source files should have the Google Inc. license header.
|
||||||
|
* Use `///` for [Doxygen](http://www.doxygen.nl/) (use `\a` to refer to
|
||||||
[Google C++ coding style]: https://google.github.io/styleguide/cppguide.html
|
arguments).
|
||||||
|
|
||||||
## Documentation
|
|
||||||
|
|
||||||
### Style guidelines
|
|
||||||
|
|
||||||
* Use `///` for doxygen.
|
|
||||||
* Use `\a` to refer to arguments.
|
|
||||||
* It's not necessary to document each argument, especially when they're
|
* It's not necessary to document each argument, especially when they're
|
||||||
relatively self-evident (e.g. in `CanonicalizePath(string* path, string* err)`,
|
relatively self-evident (e.g. in
|
||||||
the arguments are hopefully obvious)
|
`CanonicalizePath(string* path, string* err)`, the arguments are hopefully
|
||||||
|
obvious).
|
||||||
|
|
||||||
### Building the manual
|
If you're unsure about code formatting, please use
|
||||||
|
[clang-format](https://clang.llvm.org/docs/ClangFormat.html). However, please do
|
||||||
sudo apt-get install asciidoc --no-install-recommends
|
not format code that is not otherwise part of your contribution.
|
||||||
./ninja manual
|
|
||||||
|
|
||||||
### Building the code documentation
|
|
||||||
|
|
||||||
sudo apt-get install doxygen
|
|
||||||
./ninja doxygen
|
|
||||||
|
|
||||||
## Building for 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 configure.py --bootstrap`
|
|
||||||
|
|
||||||
[Python for Windows]: http://www.python.org/getit/windows/
|
|
||||||
|
|
||||||
### Via mingw on Windows (not well supported)
|
|
||||||
|
|
||||||
* Install mingw, msys, and python
|
|
||||||
* In the mingw shell, put Python in your path, and
|
|
||||||
`python configure.py --bootstrap`
|
|
||||||
* To reconfigure, run `python configure.py`
|
|
||||||
* Remember to strip the resulting executable if size matters to you
|
|
||||||
|
|
||||||
### Via mingw on Linux (not well supported)
|
|
||||||
|
|
||||||
Setup on Ubuntu Lucid:
|
|
||||||
* `sudo apt-get install gcc-mingw32 wine`
|
|
||||||
* `export CC=i586-mingw32msvc-cc CXX=i586-mingw32msvc-c++ AR=i586-mingw32msvc-ar`
|
|
||||||
|
|
||||||
Setup on Ubuntu Precise:
|
|
||||||
* `sudo apt-get install gcc-mingw-w64-i686 g++-mingw-w64-i686 wine`
|
|
||||||
* `export CC=i686-w64-mingw32-gcc CXX=i686-w64-mingw32-g++ AR=i686-w64-mingw32-ar`
|
|
||||||
|
|
||||||
Setup on Arch:
|
|
||||||
* Uncomment the `[multilib]` section of `/etc/pacman.conf` and `sudo pacman -Sy`.
|
|
||||||
* `sudo pacman -S mingw-w64-gcc wine`
|
|
||||||
* `export CC=x86_64-w64-mingw32-cc CXX=x86_64-w64-mingw32-c++ AR=x86_64-w64-mingw32-ar`
|
|
||||||
* `export CFLAGS=-I/usr/x86_64-w64-mingw32/include`
|
|
||||||
|
|
||||||
Then run:
|
|
||||||
* `./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(!))
|
|
||||||
|
|
||||||
### Using Microsoft compilers on Linux (extremely flaky)
|
|
||||||
|
|
||||||
The trick is to install just the compilers, and not all of Visual Studio,
|
|
||||||
by following [these instructions][win7sdk].
|
|
||||||
|
|
||||||
[win7sdk]: http://www.kegel.com/wine/cl-howto-win7sdk.html
|
|
||||||
|
|
||||||
### Using gcov
|
|
||||||
|
|
||||||
Do a clean debug build with the right flags:
|
|
||||||
|
|
||||||
CFLAGS=-coverage LDFLAGS=-coverage ./configure.py --debug
|
|
||||||
ninja -t clean ninja_test && ninja ninja_test
|
|
||||||
|
|
||||||
Run the test binary to generate `.gcda` and `.gcno` files in the build
|
|
||||||
directory, then run gcov on the .o files to generate `.gcov` files in the
|
|
||||||
root directory:
|
|
||||||
|
|
||||||
./ninja_test
|
|
||||||
gcov build/*.o
|
|
||||||
|
|
||||||
Look at the generated `.gcov` files directly, or use your favorite gcov viewer.
|
|
||||||
|
|
||||||
### Using afl-fuzz
|
|
||||||
|
|
||||||
Build with afl-clang++:
|
|
||||||
|
|
||||||
CXX=path/to/afl-1.20b/afl-clang++ ./configure.py
|
|
||||||
ninja
|
|
||||||
|
|
||||||
Then run afl-fuzz like so:
|
|
||||||
|
|
||||||
afl-fuzz -i misc/afl-fuzz -o /tmp/afl-fuzz-out ./ninja -n -f @@
|
|
||||||
|
|
||||||
You can pass `-x misc/afl-fuzz-tokens` to use the token dictionary. In my
|
|
||||||
testing, that did not seem more effective though.
|
|
||||||
|
|
||||||
#### Using afl-fuzz with asan
|
|
||||||
|
|
||||||
If you want to use asan (the `isysroot` bit is only needed on OS X; if clang
|
|
||||||
can't find C++ standard headers make sure your LLVM checkout includes a libc++
|
|
||||||
checkout and has libc++ installed in the build directory):
|
|
||||||
|
|
||||||
CFLAGS="-fsanitize=address -isysroot $(xcrun -show-sdk-path)" \
|
|
||||||
LDFLAGS=-fsanitize=address CXX=path/to/afl-1.20b/afl-clang++ \
|
|
||||||
./configure.py
|
|
||||||
AFL_CXX=path/to/clang++ ninja
|
|
||||||
|
|
||||||
Make sure ninja can find the asan runtime:
|
|
||||||
|
|
||||||
DYLD_LIBRARY_PATH=path/to//lib/clang/3.7.0/lib/darwin/ \
|
|
||||||
afl-fuzz -i misc/afl-fuzz -o /tmp/afl-fuzz-out ./ninja -n -f @@
|
|
||||||
|
|||||||
@ -1,21 +1,23 @@
|
|||||||
|
# Ninja
|
||||||
|
|
||||||
Ninja is a small build system with a focus on speed.
|
Ninja is a small build system with a focus on speed.
|
||||||
https://ninja-build.org/
|
https://ninja-build.org/
|
||||||
|
|
||||||
See the manual -- https://ninja-build.org/manual.html or
|
See [the manual](https://ninja-build.org/manual.html) or
|
||||||
doc/manual.asciidoc included in the distribution -- for background
|
`doc/manual.asciidoc` included in the distribution for background
|
||||||
and more details.
|
and more details.
|
||||||
|
|
||||||
Binaries for Linux, Mac, and Windows are available at
|
Binaries for Linux, Mac, and Windows are available at
|
||||||
https://github.com/ninja-build/ninja/releases
|
[GitHub](https://github.com/ninja-build/ninja/releases).
|
||||||
Run './ninja -h' for Ninja help.
|
Run `./ninja -h` for Ninja help.
|
||||||
|
|
||||||
To build your own binary, on many platforms it should be sufficient to
|
To build your own binary, on many platforms it should be sufficient to
|
||||||
just run `./configure.py --bootstrap`; for more details see HACKING.md.
|
just run `./configure.py --bootstrap`; for more details see
|
||||||
(Also read that before making changes to Ninja, as it has advice.)
|
[the wiki](https://github.com/ninja-build/ninja/wiki).
|
||||||
|
|
||||||
Installation is not necessary because the only required file is the
|
Installation is not necessary because the only required file is the
|
||||||
resulting ninja binary. However, to enable features like Bash
|
resulting ninja binary. However, to enable features like Bash
|
||||||
completion and Emacs and Vim editing modes, some files in misc/ must be
|
completion and Emacs and Vim editing modes, some files in misc/ must be
|
||||||
copied to appropriate locations.
|
copied to appropriate locations.
|
||||||
|
|
||||||
If you're interested in making changes to Ninja, read HACKING.md first.
|
If you're interested in making changes to Ninja, read CONTRIBUTING.md first.
|
||||||
@ -1,7 +1,7 @@
|
|||||||
Notes to myself on all the steps to make for a Ninja release.
|
Notes to myself on all the steps to make for a Ninja release.
|
||||||
|
|
||||||
Push new release branch:
|
Push new release branch:
|
||||||
1. Run afl-fuzz for a day or so (see HACKING.md) and run ninja_test
|
1. Run afl-fuzz for a day or so and run ninja_test
|
||||||
2. Consider sending a heads-up to the ninja-build mailing list first
|
2. Consider sending a heads-up to the ninja-build mailing list first
|
||||||
3. Make sure branches 'master' and 'release' are synced up locally
|
3. Make sure branches 'master' and 'release' are synced up locally
|
||||||
4. Update src/version.cc with new version (with ".git"), then
|
4. Update src/version.cc with new version (with ".git"), then
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user