README.fuchsia

Name: Ninja
URL: https://ninja-build.org
Gerrit Git: https://fuchsia.googlesource.com/third_party/github.com/ninja-build/ninja
Upstream Git: https://github.com/ninja-build/ninja
Fuchsia RFC: https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0153_ninja_customization?hl=en
License: Apache 2.0
License File: COPYING
Fuchsia Bug: https://fxbug.dev/91545
Description:

Ninja is a small build system with a focus on speed. As explained in the
Fuchsia RFC-0153 document, this is a temporary custom branch of the upstream
Ninja sources to provide various improvements for the Fuchsia build. All
changes should be expressed as a set of small commits on top of the upstream
main branch, periodically rebased according to the strategy described in the
RFC document. Due to this, local modifications are not listed explictly here
to reduce unnecessary merge conflicts in this file.

Note that:

- Development happens in the `main` branch of
  `https://fuchsia.googlesource.com/third_party/github.com/ninja-build/ninja`

- All patches need to be uploaded to Gerrit for review approval.
  (https://fuchsia-review.googlesource.com).

- Sync branches can only be created on Gerrit, and require filing
  a ticket, see associated bug for details.

Use `git log origin/upstream/master..main` to see the detail log
of changes instead.

To facilite sync branch creation and management, the commit message of
patches should following these conventions:

- Patches that were cherry-picked from upstream should have a line that
  starts with `Upstream-Cherry-Pick: <COMMIT>` added to their original
  commit message.

- Patches that were cherry-picked from the upstream GitHub pull requests
  should have a line that starts with  `Upstream-GitHub-PR: <URL>`
  pointing to the corresponding pull request.

- Patches that should not be sent upstream should have a line that
  starts with `Fuchsia-Only: <REASON>`. These should only matter for
  Fuchsia specific documentation (such as this file), or development
  scripts.

- Non-trivial changes that address a specific feature should be provided
  as a series of small patches whose commit messages all include a line
  that starts with `Fuchsia-Topic: <name>`, where `<name>` is a small
  identifier describing the common feature (e.g. `faster-manifest-parser`)
  described by the list in the next section of this README.fuchsia file.

  This will allow collecting the commits to send them as upstream pull
  requests (after removing these lines from the commit message), or to
  re-order them during sync-branch rebase operations.

Fuchsia-specific scripts or data files should go under `misc/fuchsia/`.

List of Fuchsia-Topic items:

multi-line-status
  Improve the status display in smart terminals to include a list of
  the oldest pending commands that are still running. This feature is
  controlled by setting NINJA_STATUS_MAX_COMMANDS in the
  environment to a decimal value that is >= 1.

advanced-ipc
  Provide support for advanced inter-process communication using
  named pipes (on Win32) or unix domain sockets (on Posix). This
  will be used to implement both the `persistent-mode` feature
  and the `jobserver-support` feature.

persistent-mode
  Allow the Ninja process to run in daemon mode after parsing the
  Ninja build plan, until a .ninja file is changed or some fixed
  expiration time, in order to start future `ninja` invocations
  immediately (instead of spending several seconds to re-load the
  build plan every time).
  Requires: advanced-ipc

jobserver-support
  Allow Ninja to act as both a GNU Make jobserver client
  (when invoking from other build systems), and a server
  (when invoking sub-commands).
  Requires: advanced-ipc