diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 0000000000..6d53cc315a --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,54 @@ + +version: 2.1 +jobs: + build-test: + docker: + - image: cimg/base:current + steps: + # Checkout the code as the first step. + - checkout + - run: + name: InstallPreq + command: | + echo "Installing clang-tidy" + sudo apt-get update && sudo apt-get install -y clang-tidy + echo "Installed" + - run: + name: Build + command: | + echo "Building" + mkdir build && cd build + cmake -S .. + make -j $(nproc) + cd ../ + echo "Built" + - run: + name: ninjaTest + command: | + cd build + ./ninja_test --gtest_output=XML + echo "Testing Done" + - store_test_results: + path: build + - run: + name: ctest + command: | + echo "Start Testing" + cd build + ctest --output-junit results.xml + echo "Testing Done" + - store_test_results: + path: build/results.xml + - run: + name: Run Performance Tests + command: | + cd build + for test in build_log_perftest canon_perftest clparser_perftest elide_middle_perftest hash_collision_bench; do + echo "Running $test" + ./$test + done + +workflows: + build-test-workflow: + jobs: + - build-test diff --git a/CMakeLists.txt b/CMakeLists.txt index 47b1f9c117..98b3a60e8e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -3,6 +3,13 @@ cmake_minimum_required(VERSION 3.15) include(CheckSymbolExists) include(CheckIPOSupported) +find_program(CLANG_TIDY_EXE NAMES clang-tidy) +if(CLANG_TIDY_EXE) + set(CMAKE_CXX_CLANG_TIDY "${CLANG_TIDY_EXE}") +else() + message(WARNING "clang-tidy not found!") +endif() + option(NINJA_BUILD_BINARY "Build ninja binary" ON) option(NINJA_FORCE_PSELECT "Use pselect() even on platforms that provide ppoll()" OFF) @@ -312,6 +319,7 @@ if(BUILD_TESTING) endif() add_test(NAME NinjaTest COMMAND ninja_test) + endif() if(NINJA_BUILD_BINARY) diff --git a/README.md b/README.md index 9312d935f3..6249912138 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,42 @@ -# Ninja - -Ninja is a small build system with a focus on speed. -https://ninja-build.org/ - -See [the manual](https://ninja-build.org/manual.html) or -`doc/manual.asciidoc` included in the distribution for background -and more details. - -Binaries for Linux, Mac and Windows are available on - [GitHub](https://github.com/ninja-build/ninja/releases). -Run `./ninja -h` for Ninja help. - -Installation is not necessary because the only required file is the -resulting ninja binary. However, to enable features like Bash -completion and Emacs and Vim editing modes, some files in misc/ must be -copied to appropriate locations. - -If you're interested in making changes to Ninja, read -[CONTRIBUTING.md](CONTRIBUTING.md) first. - -## Building Ninja itself - -You can either build Ninja via the custom generator script written in Python or -via CMake. For more details see -[the wiki](https://github.com/ninja-build/ninja/wiki). - -### Python - -``` -./configure.py --bootstrap -``` - -This will generate the `ninja` binary and a `build.ninja` file you can now use -to build Ninja with itself. - -If you have a GoogleTest source directory, you can build the tests -by passing its path with `--gtest-source-dir=PATH` option, or the -`GTEST_SOURCE_DIR` environment variable, e.g.: - -``` -./configure.py --bootstrap --gtest-source-dir=/path/to/googletest -./ninja all # build ninja_test and other auxiliary binaries -./ninja_test` # run the unit-test suite. -``` - -Use the CMake build below if you want to use a preinstalled binary -version of the library. - -### CMake - -``` -cmake -Bbuild-cmake -cmake --build build-cmake +# Shadowdash + +Shadowdash is a lightweight build system based on Ninja, focused on increasing build speed. + +## CMake +1. Build Shadowdash and move ninja executable file to your local/bin: +```bash +mkdir build && cd build +cmake -S .. +make -j $(nproc) +sudo cp ninja /usr/local/bin/ +ninja --version +``` +2. Build Clang-Tidy from source code: +```bash +git clone https://github.com/llvm/llvm-project.git +cd llvm-project +mkdir build +cd build +cmake -G "Ninja" -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra" -DCMAKE_BUILD_TYPE=Release ../llvm +ninja clang-tidy +export PATH=$PATH:/path/to/your/llvm-project/build/bin +clang-tidy --version +``` +Alternative Installation via Package Manager (Debian-based Systems): +If you’re using a Debian-based distribution like Ubuntu, you can install Clang-Tidy using the following command: +```bash +sudo apt-get install -y clang-tidy +``` +3. Test: +```bash +cd build +ctest ``` The `ninja` binary will now be inside the `build-cmake` directory (you can choose any other name you like). To run the unit tests: - ``` ./build-cmake/ninja_test ``` - -## Generating documentation - -### Ninja Manual - -You must have `asciidoc` and `xsltproc` in your PATH, then do: - -``` -./configure.py -ninja manual doc/manual.pdf -``` - -Which will generate `doc/manual.html`. - -To generate the PDF version of the manual, you must have `dblatext` in your PATH then do: - -``` -./configure.py # only if you didn't do it previously. -ninja doc/manual.pdf -``` - -Which will generate `doc/manual.pdf`. - -### Doxygen documentation - -If you have `doxygen` installed, you can build documentation extracted from C++ -declarations and comments to help you navigate the code. Note that Ninja is a standalone -executable, not a library, so there is no public API, all details exposed here are -internal. - -``` -./configure.py # if needed -ninja doxygen -``` - -Then open `doc/doxygen/html/index.html` in a browser to look at it. diff --git a/doc/README.md b/doc/README.md deleted file mode 100644 index 6afe5d4672..0000000000 --- a/doc/README.md +++ /dev/null @@ -1,11 +0,0 @@ -This directory contains the Ninja manual and support files used in -building it. Here's a brief overview of how it works. - -The source text, `manual.asciidoc`, is written in the AsciiDoc format. -AsciiDoc can generate HTML but it doesn't look great; instead, we use -AsciiDoc to generate the Docbook XML format and then provide our own -Docbook XSL tweaks to produce HTML from that. - -In theory using AsciiDoc and DocBook allows us to produce nice PDF -documentation etc. In reality it's not clear anyone wants that, but the -build rules are in place to generate it if you install dblatex. diff --git a/doc/dblatex.xsl b/doc/dblatex.xsl deleted file mode 100644 index c0da212708..0000000000 --- a/doc/dblatex.xsl +++ /dev/null @@ -1,7 +0,0 @@ - - - - 0 - 0 - diff --git a/doc/docbook.xsl b/doc/docbook.xsl deleted file mode 100644 index 2235be2e37..0000000000 --- a/doc/docbook.xsl +++ /dev/null @@ -1,34 +0,0 @@ - - -]> - - - - - - - - - - - book toc - - - 0 - - - 1 - - - ul - - - diff --git a/doc/doxygen.config b/doc/doxygen.config deleted file mode 100644 index d933021e2b..0000000000 --- a/doc/doxygen.config +++ /dev/null @@ -1,1250 +0,0 @@ -# Doxyfile 1.4.5 - -# This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project -# -# All text after a hash (#) is considered a comment and will be ignored -# The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- - -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. - -PROJECT_NAME = "Ninja" - -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. - -# PROJECT_NUMBER = "0" - -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. - -OUTPUT_DIRECTORY = "doc/doxygen/" - -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. - -CREATE_SUBDIRS = NO - -# The OUTPUT_LANGUAGE tag is used to specify the language in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, -# Dutch, Finnish, French, German, Greek, Hungarian, Italian, Japanese, -# Japanese-en (Japanese with English messages), Korean, Korean-en, Norwegian, -# Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, -# Swedish, and Ukrainian. - -OUTPUT_LANGUAGE = English - -# This tag can be used to specify the encoding used in the generated output. -# The encoding is not always determined by the language that is chosen, -# but also whether or not the output is meant for Windows or non-Windows users. -# In case there is a difference, setting the USE_WINDOWS_ENCODING tag to YES -# forces the Windows encoding (this is the default for the Windows binary), -# whereas setting the tag to NO uses a Unix-style encoding (the default for -# all platforms other than Windows). - -# Obsolet option. -#USE_WINDOWS_ENCODING = YES - -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. - -BRIEF_MEMBER_DESC = YES - -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the -# brief descriptions will be completely suppressed. - -REPEAT_BRIEF = YES - -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" - -ABBREVIATE_BRIEF = - -# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief -# description. - -ALWAYS_DETAILED_SEC = NO - -# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all -# inherited members of a class in the documentation of that class as if those -# members were ordinary class members. Constructors, destructors and assignment -# operators of the base classes will not be shown. - -INLINE_INHERITED_MEMB = YES - -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. - -FULL_PATH_NAMES = YES - -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. - -STRIP_FROM_PATH = src - -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. - -STRIP_FROM_INC_PATH = src/ - -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. - -SHORT_NAMES = NO - -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like the Qt-style comments (thus requiring an -# explicit @brief command for a brief description. - -JAVADOC_AUTOBRIEF = YES - -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. - -MULTILINE_CPP_IS_BRIEF = NO - -# If the DETAILS_AT_TOP tag is set to YES then Doxygen -# will output the detailed description near the top, like JavaDoc. -# If set to NO, the detailed description appears after the member -# documentation. - -# Has become obsolete. -#DETAILS_AT_TOP = NO - -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. - -INHERIT_DOCS = YES - -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. - -SEPARATE_MEMBER_PAGES = NO - -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. - -TAB_SIZE = 2 - -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. - -ALIASES = - -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. - -OPTIMIZE_OUTPUT_FOR_C = NO - -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java -# sources only. Doxygen will then generate output that is more tailored for Java. -# For instance, namespaces will be presented as packages, qualified scopes -# will look different, etc. - -OPTIMIZE_OUTPUT_JAVA = NO - -# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want to -# include (a tag file for) the STL sources as input, then you should -# set this tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. -# func(std::string) {}). This also make the inheritance and collaboration -# diagrams that involve STL classes more complete and accurate. - -# BUILTIN_STL_SUPPORT = NO - -# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first -# member in the group (if any) for the other members of the group. By default -# all members of a group must be documented explicitly. - -DISTRIBUTE_GROUP_DOC = NO - -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. - -SUBGROUPING = YES - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- - -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES - -EXTRACT_ALL = YES - -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. - -EXTRACT_PRIVATE = YES - -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. - -EXTRACT_STATIC = YES - -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. - -EXTRACT_LOCAL_CLASSES = YES - -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. - -EXTRACT_LOCAL_METHODS = NO - -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_MEMBERS = NO - -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. - -HIDE_UNDOC_CLASSES = NO - -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the -# documentation. - -HIDE_FRIEND_COMPOUNDS = NO - -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. - -HIDE_IN_BODY_DOCS = NO - -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. - -INTERNAL_DOCS = NO - -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. - -CASE_SENSE_NAMES = YES - -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. - -HIDE_SCOPE_NAMES = NO - -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. - -SHOW_INCLUDE_FILES = YES - -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. - -INLINE_INFO = YES - -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. - -SORT_MEMBER_DOCS = YES - -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. - -SORT_BRIEF_DOCS = YES - -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. -# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. - -SORT_BY_SCOPE_NAME = NO - -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. - -GENERATE_TODOLIST = YES - -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. - -GENERATE_TESTLIST = YES - -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. - -GENERATE_BUGLIST = YES - -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. - -GENERATE_DEPRECATEDLIST= YES - -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. - -ENABLED_SECTIONS = - -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. - -MAX_INITIALIZER_LINES = 30 - -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the -# list will mention the files that were used to generate the documentation. - -SHOW_USED_FILES = YES - -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. The default is YES. - -SHOW_DIRECTORIES = YES - -# The FILE_VERSION_FILTER tag can be used to specify a program or script that -# doxygen should invoke to get the current version for each file (typically from the -# version control system). Doxygen will invoke the program by executing (via -# popen()) the command , where is the value of -# the FILE_VERSION_FILTER tag, and is the name of an input file -# provided by doxygen. Whatever the program writes to standard output -# is used as the file version. See the manual for examples. - -FILE_VERSION_FILTER = - -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- - -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. - -QUIET = NO - -# The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. - -WARNINGS = YES - -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. - -WARN_IF_UNDOCUMENTED = YES - -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. - -WARN_IF_DOC_ERROR = YES - -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. - -WARN_NO_PARAMDOC = NO - -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) - -WARN_FORMAT = "$file:$line: $text " - -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. - -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- - -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. - -INPUT = src \ - build/doxygen_mainpage - -# If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx -# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py - -FILE_PATTERNS = *.cc \ - *.h - -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. - -RECURSIVE = YES - -# The EXCLUDE tag can be used to specify files and/or directories that should -# excluded from the INPUT source files. This way you can easily exclude a -# subdirectory from a directory tree whose root is specified with the INPUT tag. - -EXCLUDE = - -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded -# from the input. - -EXCLUDE_SYMLINKS = NO - -# If the value of the INPUT tag contains directories, you can use the -# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* - -EXCLUDE_PATTERNS = - -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). - -EXAMPLE_PATH = src - -# If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. - -EXAMPLE_PATTERNS = *.cpp \ - *.cc \ - *.h \ - *.hh \ - INSTALL DEPENDENCIES CHANGELOG LICENSE LGPL - -# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. - -EXAMPLE_RECURSIVE = YES - -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). - -IMAGE_PATH = src - -# The INPUT_FILTER tag can be used to specify a program that doxygen should -# invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. If FILTER_PATTERNS is specified, this tag will be -# ignored. - -INPUT_FILTER = - -# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. - -FILTER_PATTERNS = - -# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). - -FILTER_SOURCE_FILES = NO - -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- - -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. - -SOURCE_BROWSER = YES - -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. - -INLINE_SOURCES = NO - -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. - -STRIP_CODE_COMMENTS = NO - -# If the REFERENCED_BY_RELATION tag is set to YES (the default) -# then for each documented function all documented -# functions referencing it will be listed. - -REFERENCED_BY_RELATION = YES - -# If the REFERENCES_RELATION tag is set to YES (the default) -# then for each documented function all documented entities -# called/used by that function will be listed. - -REFERENCES_RELATION = YES - -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. - -USE_HTAGS = NO - -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. - -VERBATIM_HEADERS = YES - -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- - -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. - -ALPHABETICAL_INDEX = YES - -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 2 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. - -IGNORE_PREFIX = - -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- - -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. - -GENERATE_HTML = YES - -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. - -HTML_OUTPUT = html - -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. - -HTML_FILE_EXTENSION = .html - -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a -# standard header. -HTML_HEADER = - - -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. - -HTML_FOOTER = - -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! - -HTML_STYLESHEET = - -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. - -HTML_ALIGN_MEMBERS = YES - -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compressed HTML help file (.chm) -# of the generated HTML documentation. - -GENERATE_HTMLHELP = YES - -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be -# written to the html output directory. - -CHM_FILE = - -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. - -HHC_LOCATION = - -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). - -GENERATE_CHI = NO - -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. - -BINARY_TOC = NO - -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. - -TOC_EXPAND = NO - -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. - -DISABLE_INDEX = NO - -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 4 - -# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be -# generated containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, -# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are -# probably better off using the HTML help feature. - -GENERATE_TREEVIEW = YES - -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. - -TREEVIEW_WIDTH = 250 - -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- - -# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will -# generate Latex output. - -GENERATE_LATEX = NO - -# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `latex' will be used as the default path. - -LATEX_OUTPUT = latex - -# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be -# invoked. If left blank `latex' will be used as the default command name. - -LATEX_CMD_NAME = - -# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to -# generate index for LaTeX. If left blank `makeindex' will be used as the -# default command name. - -MAKEINDEX_CMD_NAME = - -# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact -# LaTeX documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_LATEX = NO - -# The PAPER_TYPE tag can be used to set the paper type that is used -# by the printer. Possible values are: a4, a4wide, letter, legal and -# executive. If left blank a4wide will be used. - -PAPER_TYPE = a4 - -# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX -# packages that should be included in the LaTeX output. - -EXTRA_PACKAGES = - -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for -# the generated latex document. The header should contain everything until -# the first chapter. If it is left blank doxygen will generate a -# standard header. Notice: only use this tag if you know what you are doing! - -LATEX_HEADER = - -# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated -# is prepared for conversion to pdf (using ps2pdf). The pdf file will -# contain links (just like the HTML output) instead of page references -# This makes the output suitable for online browsing using a pdf viewer. - -PDF_HYPERLINKS = YES - -# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of -# plain latex in the generated Makefile. Set this option to YES to get a -# higher quality PDF documentation. - -USE_PDFLATEX = YES - -# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. -# command to the generated LaTeX files. This will instruct LaTeX to keep -# running if errors occur, instead of asking the user for help. -# This option is also used when generating formulas in HTML. - -LATEX_BATCHMODE = YES - -# If LATEX_HIDE_INDICES is set to YES then doxygen will not -# include the index chapters (such as File Index, Compound Index, etc.) -# in the output. - -LATEX_HIDE_INDICES = NO - -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- - -# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output -# The RTF output is optimized for Word 97 and may not look very pretty with -# other RTF readers or editors. - -GENERATE_RTF = NO - -# The RTF_OUTPUT tag is used to specify where the RTF docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `rtf' will be used as the default path. - -RTF_OUTPUT = rtf - -# If the COMPACT_RTF tag is set to YES Doxygen generates more compact -# RTF documents. This may be useful for small projects and may help to -# save some trees in general. - -COMPACT_RTF = NO - -# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated -# will contain hyperlink fields. The RTF file will -# contain links (just like the HTML output) instead of page references. -# This makes the output suitable for online browsing using WORD or other -# programs which support those fields. -# Note: wordpad (write) and others do not support links. - -RTF_HYPERLINKS = NO - -# Load stylesheet definitions from file. Syntax is similar to doxygen's -# config file, i.e. a series of assignments. You only have to provide -# replacements, missing definitions are set to their default value. - -RTF_STYLESHEET_FILE = - -# Set optional variables used in the generation of an rtf document. -# Syntax is similar to doxygen's config file. - -RTF_EXTENSIONS_FILE = - -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- - -# If the GENERATE_MAN tag is set to YES (the default) Doxygen will -# generate man pages - -GENERATE_MAN = NO - -# The MAN_OUTPUT tag is used to specify where the man pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `man' will be used as the default path. - -MAN_OUTPUT = man - -# The MAN_EXTENSION tag determines the extension that is added to -# the generated man pages (default is the subroutine's section .3) - -MAN_EXTENSION = .3 - -# If the MAN_LINKS tag is set to YES and Doxygen generates man output, -# then it will generate one additional man file for each entity -# documented in the real man page(s). These additional files -# only source the real man page, but without them the man command -# would be unable to find the correct page. The default is NO. - -MAN_LINKS = NO - -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- - -# If the GENERATE_XML tag is set to YES Doxygen will -# generate an XML file that captures the structure of -# the code including all documentation. - -GENERATE_XML = NO - -# The XML_OUTPUT tag is used to specify where the XML pages will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `xml' will be used as the default path. - -XML_OUTPUT = xml - -# The XML_SCHEMA tag can be used to specify an XML schema, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_SCHEMA = - -# The XML_DTD tag can be used to specify an XML DTD, -# which can be used by a validating XML parser to check the -# syntax of the XML files. - -XML_DTD = - -# If the XML_PROGRAMLISTING tag is set to YES Doxygen will -# dump the program listings (including syntax highlighting -# and cross-referencing information) to the XML output. Note that -# enabling this will significantly increase the size of the XML output. - -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- - -# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will -# generate an AutoGen Definitions (see autogen.sf.net) file -# that captures the structure of the code including all -# documentation. Note that this feature is still experimental -# and incomplete at the moment. - -GENERATE_AUTOGEN_DEF = NO - -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- - -# If the GENERATE_PERLMOD tag is set to YES Doxygen will -# generate a Perl module file that captures the structure of -# the code including all documentation. Note that this -# feature is still experimental and incomplete at the -# moment. - -GENERATE_PERLMOD = NO - -# If the PERLMOD_LATEX tag is set to YES Doxygen will generate -# the necessary Makefile rules, Perl scripts and LaTeX code to be able -# to generate PDF and DVI output from the Perl module output. - -PERLMOD_LATEX = NO - -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be -# nicely formatted so it can be parsed by a human reader. This is useful -# if you want to understand what is going on. On the other hand, if this -# tag is set to NO the size of the Perl module output will be much smaller -# and Perl will parse it just the same. - -PERLMOD_PRETTY = YES - -# The names of the make variables in the generated doxyrules.make file -# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX. -# This is useful so different doxyrules.make files included by the same -# Makefile don't overwrite each other's variables. - -PERLMOD_MAKEVAR_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include -# files. - -ENABLE_PREPROCESSING = YES - -# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro -# names in the source code. If set to NO (the default) only conditional -# compilation will be performed. Macro expansion can be done in a controlled -# way by setting EXPAND_ONLY_PREDEF to YES. - -MACRO_EXPANSION = YES - -# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES -# then the macro expansion is limited to the macros specified with the -# PREDEFINED and EXPAND_AS_DEFINED tags. - -EXPAND_ONLY_PREDEF = YES - -# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files -# in the INCLUDE_PATH (see below) will be search if a #include is found. - -SEARCH_INCLUDES = YES - -# The INCLUDE_PATH tag can be used to specify one or more directories that -# contain include files that are not input files but should be processed by -# the preprocessor. - -INCLUDE_PATH = - -# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard -# patterns (like *.h and *.hpp) to filter out the header-files in the -# directories. If left blank, the patterns specified with FILE_PATTERNS will -# be used. - -INCLUDE_FILE_PATTERNS = - -# The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are -# omitted =1 is assumed. To prevent a macro definition from being -# undefined via #undef or recursively expanded use the := operator -# instead of the = operator. - -PREDEFINED = - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. -# The macro definition that is found in the sources will be used. -# Use the PREDEFINED tag if you want to use a different macro definition. - -EXPAND_AS_DEFINED = - -# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then -# doxygen's preprocessor will remove all function-like macros that are alone -# on a line, have an all uppercase name, and do not end with a semicolon. Such -# function macros are typically used for boiler-plate code, and will confuse -# the parser if not removed. - -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- - -# The TAGFILES option can be used to specify one or more tagfiles. -# Optionally an initial location of the external documentation -# can be added for each tagfile. The format of a tag file without -# this location is as follows: -# TAGFILES = file1 file2 ... -# Adding location for the tag files is done as follows: -# TAGFILES = file1=loc1 "file2 = loc2" ... -# where "loc1" and "loc2" can be relative or absolute paths or -# URLs. If a location is present for each tag, the installdox tool -# does not have to be run to correct the links. -# Note that each tag file must have a unique name -# (where the name does NOT include the path) -# If a tag file is not located in the directory in which doxygen -# is run, you must also specify the path to the tagfile here. - -TAGFILES = - -# When a file name is specified after GENERATE_TAGFILE, doxygen will create -# a tag file that is based on the input files it reads. - -GENERATE_TAGFILE = doc/doxygen/html/Ninja.TAGFILE - -# If the ALLEXTERNALS tag is set to YES all external classes will be listed -# in the class index. If set to NO only the inherited external classes -# will be listed. - -ALLEXTERNALS = YES - -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed -# in the modules index. If set to NO, only the current project's groups will -# be listed. - -EXTERNAL_GROUPS = YES - -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of `which perl'). - -PERL_PATH = /usr/bin/perl - -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- - -# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will -# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base -# or super classes. Setting the tag to NO turns the diagrams off. Note that -# this option is superseded by the HAVE_DOT option below. This is only a -# fallback. It is recommended to install and use dot, since it yields more -# powerful graphs. - -CLASS_DIAGRAMS = YES - -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = YES - -# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is -# available from the path. This tool is part of Graphviz, a graph visualization -# toolkit from AT&T and Lucent Bell Labs. The other options in this section -# have no effect if this option is set to NO (the default) - -HAVE_DOT = YES - -# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect inheritance relations. Setting this tag to YES will force the -# the CLASS_DIAGRAMS tag to NO. - -CLASS_GRAPH = YES - -# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for each documented class showing the direct and -# indirect implementation dependencies (inheritance, containment, and -# class references variables) of the class with other documented classes. - -COLLABORATION_GRAPH = NO - -# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen -# will generate a graph for groups, showing the direct groups dependencies - -GROUP_GRAPHS = YES - -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and -# collaboration diagrams in a style similar to the OMG's Unified Modeling -# Language. - -UML_LOOK = NO -# UML_LOOK = YES - -# If set to YES, the inheritance and collaboration graphs will show the -# relations between templates and their instances. - -TEMPLATE_RELATIONS = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT -# tags are set to YES then doxygen will generate a graph for each documented -# file showing the direct and indirect include dependencies of the file with -# other documented files. - -INCLUDE_GRAPH = YES - -# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and -# HAVE_DOT tags are set to YES then doxygen will generate a graph for each -# documented header file showing the documented files that directly or -# indirectly include this file. - -INCLUDED_BY_GRAPH = YES - -# If the CALL_GRAPH and HAVE_DOT tags are set to YES then doxygen will -# generate a call dependency graph for every global function or class method. -# Note that enabling this option will significantly increase the time of a run. -# So in most cases it will be better to enable call graphs for selected -# functions only using the \callgraph command. - -CALL_GRAPH = NO - -# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen -# will graphical hierarchy of all classes instead of a textual one. - -GRAPHICAL_HIERARCHY = YES - -# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES -# then doxygen will show the dependencies a directory has on other directories -# in a graphical way. The dependency relations are determined by the #include -# relations between the files in the directories. - -DIRECTORY_GRAPH = YES - -# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. Possible values are png, jpg, or gif -# If left blank png will be used. - -DOT_IMAGE_FORMAT = png - -# The tag DOT_PATH can be used to specify the path where the dot tool can be -# found. If left blank, it is assumed the dot tool can be found in the path. - -DOT_PATH = - -# The DOTFILE_DIRS tag can be used to specify one or more directories that -# contain dot files that are included in the documentation (see the -# \dotfile command). - -DOTFILE_DIRS = - -# The MAX_DOT_GRAPH_WIDTH tag can be used to set the maximum allowed width -# (in pixels) of the graphs generated by dot. If a graph becomes larger than -# this value, doxygen will try to truncate the graph, so that it fits within -# the specified constraint. Beware that most browsers cannot cope with very -# large images. - -# Obsolet option. -#MAX_DOT_GRAPH_WIDTH = 1280 - -# The MAX_DOT_GRAPH_HEIGHT tag can be used to set the maximum allows height -# (in pixels) of the graphs generated by dot. If a graph becomes larger than -# this value, doxygen will try to truncate the graph, so that it fits within -# the specified constraint. Beware that most browsers cannot cope with very -# large images. - -# Obsolet option. -#MAX_DOT_GRAPH_HEIGHT = 1024 - -# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the -# graphs generated by dot. A depth value of 3 means that only nodes reachable -# from the root by following a path via at most 3 edges will be shown. Nodes -# that lay further from the root node will be omitted. Note that setting this -# option to 1 or 2 may greatly reduce the computation time needed for large -# code bases. Also note that a graph may be further truncated if the graph's -# image dimensions are not sufficient to fit the graph (see MAX_DOT_GRAPH_WIDTH -# and MAX_DOT_GRAPH_HEIGHT). If 0 is used for the depth value (the default), -# the graph is not depth-constrained. - -MAX_DOT_GRAPH_DEPTH = 0 - -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, which results in a white background. -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). - -DOT_TRANSPARENT = NO - -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output -# files in one run (i.e. multiple -o and -T options on the command line). This -# makes dot run faster, but since only newer versions of dot (>1.8.10) -# support this, this feature is disabled by default. -# JW -# DOT_MULTI_TARGETS = NO -DOT_MULTI_TARGETS = YES - -# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will -# generate a legend page explaining the meaning of the various boxes and -# arrows in the dot generated graphs. - -GENERATE_LEGEND = YES - -# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will -# remove the intermediate dot files that are used to generate -# the various graphs. - -DOT_CLEANUP = YES - -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- - -# The SEARCHENGINE tag specifies whether or not a search engine should be -# used. If set to NO the values of all tags below this one will be ignored. - -# JW SEARCHENGINE = NO -SEARCHENGINE = YES diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc deleted file mode 100644 index e8b66807cf..0000000000 --- a/doc/manual.asciidoc +++ /dev/null @@ -1,1277 +0,0 @@ -The Ninja build system -====================== - - -Introduction ------------- - -Ninja is yet another build system. It takes as input the -interdependencies of files (typically source code and output -executables) and orchestrates building them, _quickly_. - -Ninja joins a sea of other build systems. Its distinguishing goal is -to be fast. It is born from -http://neugierig.org/software/chromium/notes/2011/02/ninja.html[my -work on the Chromium browser project], which has over 30,000 source -files and whose other build systems (including one built from custom -non-recursive Makefiles) would take ten seconds to start building -after changing one file. Ninja is under a second. - -Philosophical overview -~~~~~~~~~~~~~~~~~~~~~~ - -Where other build systems are high-level languages, Ninja aims to be -an assembler. - -Build systems get slow when they need to make decisions. When you are -in an edit-compile cycle you want it to be as fast as possible -- you -want the build system to do the minimum work necessary to figure out -what needs to be built immediately. - -Ninja contains the barest functionality necessary to describe -arbitrary dependency graphs. Its lack of syntax makes it impossible -to express complex decisions. - -Instead, Ninja is intended to be used with a separate program -generating its input files. The generator program (like the -`./configure` found in autotools projects) can analyze system -dependencies and make as many decisions as possible up front so that -incremental builds stay fast. Going beyond autotools, even build-time -decisions like "which compiler flags should I use?" or "should I -build a debug or release-mode binary?" belong in the `.ninja` file -generator. - -Design goals -~~~~~~~~~~~~ - -Here are the design goals of Ninja: - -* very fast (i.e., instant) incremental builds, even for very large - projects. - -* very little policy about how code is built. Different projects and - higher-level build systems have different opinions about how code - should be built; for example, should built objects live alongside - the sources or should all build output go into a separate directory? - Is there a "package" rule that builds a distributable package of - the project? Sidestep these decisions by trying to allow either to - be implemented, rather than choosing, even if that results in - more verbosity. - -* get dependencies correct, and in particular situations that are - difficult to get right with Makefiles (e.g. outputs need an implicit - dependency on the command line used to generate them; to build C - source code you need to use gcc's `-M` flags for header - dependencies). - -* when convenience and speed are in conflict, prefer speed. - -Some explicit _non-goals_: - -* convenient syntax for writing build files by hand. _You should - generate your ninja files using another program_. This is how we - can sidestep many policy decisions. - -* built-in rules. _Out of the box, Ninja has no rules for - e.g. compiling C code._ - -* build-time customization of the build. _Options belong in - the program that generates the ninja files_. - -* build-time decision-making ability such as conditionals or search - paths. _Making decisions is slow._ - -To restate, Ninja is faster than other build systems because it is -painfully simple. You must tell Ninja exactly what to do when you -create your project's `.ninja` files. - -Comparison to Make -~~~~~~~~~~~~~~~~~~ - -Ninja is closest in spirit and functionality to Make, relying on -simple dependencies between file timestamps. - -But fundamentally, make has a lot of _features_: suffix rules, -functions, built-in rules that e.g. search for RCS files when building -source. Make's language was designed to be written by humans. Many -projects find make alone adequate for their build problems. - -In contrast, Ninja has almost no features; just those necessary to get -builds correct while punting most complexity to generation of the -ninja input files. Ninja by itself is unlikely to be useful for most -projects. - -Here are some of the features Ninja adds to Make. (These sorts of -features can often be implemented using more complicated Makefiles, -but they are not part of make itself.) - -* Ninja has special support for discovering extra dependencies at build - time, making it easy to get <> - correct for C/C++ code. - -* A build edge may have multiple outputs. - -* Outputs implicitly depend on the command line that was used to generate - them, which means that changing e.g. compilation flags will cause - the outputs to rebuild. - -* Output directories are always implicitly created before running the - command that relies on them. - -* Rules can provide shorter descriptions of the command being run, so - you can print e.g. `CC foo.o` instead of a long command line while - building. - -* Builds are always run in parallel, based by default on the number of - CPUs your system has. Underspecified build dependencies will result - in incorrect builds. - -* Command output is always buffered. This means commands running in - parallel don't interleave their output, and when a command fails we - can print its failure output next to the full command line that - produced the failure. - - -Using Ninja for your project ----------------------------- - -Ninja currently works on Unix-like systems and Windows. It's seen the -most testing on Linux (and has the best performance there) but it runs -fine on Mac OS X and FreeBSD. - -If your project is small, Ninja's speed impact is likely unnoticeable. -(However, even for small projects it sometimes turns out that Ninja's -limited syntax forces simpler build rules that result in faster -builds.) Another way to say this is that if you're happy with the -edit-compile cycle time of your project already then Ninja won't help. - -There are many other build systems that are more user-friendly or -featureful than Ninja itself. For some recommendations: the Ninja -author found http://gittup.org/tup/[the tup build system] influential -in Ninja's design, and thinks https://github.com/apenwarr/redo[redo]'s -design is quite clever. - -Ninja's benefit comes from using it in conjunction with a smarter -meta-build system. - -https://gn.googlesource.com/gn/[gn]:: The meta-build system used to -generate build files for Google Chrome and related projects (v8, -node.js), as well as Google Fuchsia. gn can generate Ninja files for -all platforms supported by Chrome. - -https://cmake.org/[CMake]:: A widely used meta-build system that -can generate Ninja files on Linux as of CMake version 2.8.8. Newer versions -of CMake support generating Ninja files on Windows and Mac OS X too. - -https://github.com/ninja-build/ninja/wiki/List-of-generators-producing-ninja-build-files[others]:: Ninja ought to fit perfectly into other meta-build software -like https://premake.github.io/[premake]. If you do this work, -please let us know! - -Running Ninja -~~~~~~~~~~~~~ - -Run `ninja`. By default, it looks for a file named `build.ninja` in -the current directory and builds all out-of-date targets. You can -specify which targets (files) to build as command line arguments. - -There is also a special syntax `target^` for specifying a target -as the first output of some rule containing the source you put in -the command line, if one exists. For example, if you specify target as -`foo.c^` then `foo.o` will get built (assuming you have those targets -in your build files). - -`ninja -h` prints help output. Many of Ninja's flags intentionally -match those of Make; e.g `ninja -C build -j 20` changes into the -`build` directory and runs 20 build commands in parallel. (Note that -Ninja defaults to running commands in parallel anyway, so typically -you don't need to pass `-j`.) - - -Environment variables -~~~~~~~~~~~~~~~~~~~~~ - -Ninja supports one environment variable to control its behavior: -`NINJA_STATUS`, the progress status printed before the rule being run. - -Several placeholders are available: - -`%s`:: The number of started edges. -`%t`:: The total number of edges that must be run to complete the build. -`%p`:: The percentage of finished edges. -`%r`:: The number of currently running edges. -`%u`:: The number of remaining edges to start. -`%f`:: The number of finished edges. -`%o`:: Overall rate of finished edges per second -`%c`:: Current rate of finished edges per second (average over builds -specified by `-j` or its default) -`%e`:: Elapsed time in seconds. _(Available since Ninja 1.2.)_ -`%E`:: Remaining time (ETA) in seconds. _(Available since Ninja 1.12.)_ -`%w`:: Elapsed time in [h:]mm:ss format. _(Available since Ninja 1.12.)_ -`%W`:: Remaining time (ETA) in [h:]mm:ss format. _(Available since Ninja 1.12.)_ -`%P`:: The percentage (in ppp% format) of time elapsed out of predicted total runtime. _(Available since Ninja 1.12.)_ -`%%`:: A plain `%` character. - -The default progress status is `"[%f/%t] "` (note the trailing space -to separate from the build rule). Another example of possible progress status -could be `"[%u/%r/%f] "`. - -Extra tools -~~~~~~~~~~~ - -The `-t` flag on the Ninja command line runs some tools that we have -found useful during Ninja's development. The current tools are: - -[horizontal] -`query`:: dump the inputs and outputs of a given target. - -`browse`:: browse the dependency graph in a web browser. Clicking a -file focuses the view on that file, showing inputs and outputs. This -feature requires a Python installation. By default, port 8000 is used -and a web browser will be opened. This can be changed as follows: -+ ----- -ninja -t browse --port=8000 --no-browser mytarget ----- -+ -`graph`:: output a file in the syntax used by `graphviz`, an automatic -graph layout tool. Use it like: -+ ----- -ninja -t graph mytarget | dot -Tpng -ograph.png ----- -+ -In the Ninja source tree, `ninja graph.png` -generates an image for Ninja itself. If no target is given generate a -graph for all root targets. - -`targets`:: output a list of targets either by rule or by depth. If used -like +ninja -t targets rule _name_+ it prints the list of targets -using the given rule to be built. If no rule is given, it prints the source -files (the leaves of the graph). If used like -+ninja -t targets depth _digit_+ it -prints the list of targets in a depth-first manner starting by the root -targets (the ones with no outputs). Indentation is used to mark dependencies. -If the depth is zero it prints all targets. If no arguments are provided -+ninja -t targets depth 1+ is assumed. In this mode targets may be listed -several times. If used like this +ninja -t targets all+ it -prints all the targets available without indentation and it is faster -than the _depth_ mode. - -`commands`:: given a list of targets, print a list of commands which, if -executed in order, may be used to rebuild those targets, assuming that all -output files are out of date. - -`inputs`:: given a list of targets, print a list of all inputs used to -rebuild those targets. -_Available since Ninja 1.11._ - -`clean`:: remove built files. By default, it removes all built files -except for those created by the generator. Adding the `-g` flag also -removes built files created by the generator (see <>). Additional arguments are -targets, which removes the given targets and recursively all files -built for them. -+ -If used like +ninja -t clean -r _rules_+ it removes all files built using -the given rules. -+ -Files created but not referenced in the graph are not removed. This -tool takes in account the +-v+ and the +-n+ options (note that +-n+ -implies +-v+). - -`cleandead`:: remove files produced by previous builds that are no longer in the -build file. _Available since Ninja 1.10._ - -`compdb`:: given a list of rules, each of which is expected to be a -C family language compiler rule whose first input is the name of the -source file, prints on standard output a compilation database in the -http://clang.llvm.org/docs/JSONCompilationDatabase.html[JSON format] expected -by the Clang tooling interface. -_Available since Ninja 1.2._ - -`deps`:: show all dependencies stored in the `.ninja_deps` file. When given a -target, show just the target's dependencies. _Available since Ninja 1.4._ - -`missingdeps`:: given a list of targets, look for targets that depend on -a generated file, but do not have a properly (possibly transitive) dependency -on the generator. Such targets may cause build flakiness on clean builds. -+ -The broken targets can be found assuming deps log / depfile dependency -information is correct. Any target that depends on a generated file (output -of a generator-target) implicitly, but does not have an explicit or order-only -dependency path to the generator-target, is considered broken. -+ -The tool's findings can be verified by trying to build the listed targets in -a clean outdir without building any other targets. The build should fail for -each of them with a missing include error or equivalent pointing to the -generated file. -_Available since Ninja 1.11._ - -`recompact`:: recompact the `.ninja_deps` file. _Available since Ninja 1.4._ - -`restat`:: updates all recorded file modification timestamps in the `.ninja_log` -file. _Available since Ninja 1.10._ - -`rules`:: output the list of all rules. It can be used to know which rule name -to pass to +ninja -t targets rule _name_+ or +ninja -t compdb+. Adding the `-d` -flag also prints the description of the rules. - -`msvc`:: Available on Windows hosts only. -Helper tool to invoke the `cl.exe` compiler with a pre-defined set of -environment variables, as in: -+ ----- -ninja -t msvc -e ENVFILE -- cl.exe ----- -+ -Where `ENVFILE` is a binary file that contains an environment block suitable -for CreateProcessA() on Windows (i.e. a series of zero-terminated strings that -look like NAME=VALUE, followed by an extra zero terminator). Note that this uses -the local codepage encoding. -+ -This tool also supports a deprecated way of parsing the compiler's output when -the `/showIncludes` flag is used, and generating a GCC-compatible depfile from it: -+ ----- -ninja -t msvc -o DEPFILE [-p STRING] -- cl.exe /showIncludes ----- -+ -When using this option, `-p STRING` can be used to pass the localized line prefix -that `cl.exe` uses to output dependency information. For English-speaking regions -this is `"Note: including file: "` without the double quotes, but will be different -for other regions. -+ -Note that Ninja supports this natively now, with the use of `deps = msvc` and -`msvc_deps_prefix` in Ninja files. Native support also avoids launching an extra -tool process each time the compiler must be called, which can speed up builds -noticeably on Windows. - -`wincodepage`:: Available on Windows hosts (_since Ninja 1.11_). -Prints the Windows code page whose encoding is expected in the build file. -The output has the form: -+ ----- -Build file encoding: ----- -+ -Additional lines may be added in future versions of Ninja. -+ -The `` is one of: - -`UTF-8`::: Encode as UTF-8. - -`ANSI`::: Encode to the system-wide ANSI code page. - -Writing your own Ninja files ----------------------------- - -The remainder of this manual is only useful if you are constructing -Ninja files yourself: for example, if you're writing a meta-build -system or supporting a new language. - -Conceptual overview -~~~~~~~~~~~~~~~~~~~ - -Ninja evaluates a graph of dependencies between files, and runs -whichever commands are necessary to make your build target up to date -as determined by file modification times. If you are familiar with -Make, Ninja is very similar. - -A build file (default name: `build.ninja`) provides a list of _rules_ --- short names for longer commands, like how to run the compiler -- -along with a list of _build_ statements saying how to build files -using the rules -- which rule to apply to which inputs to produce -which outputs. - -Conceptually, `build` statements describe the dependency graph of your -project, while `rule` statements describe how to generate the files -along a given edge of the graph. - -Syntax example -~~~~~~~~~~~~~~ - -Here's a basic `.ninja` file that demonstrates most of the syntax. -It will be used as an example for the following sections. - ---------------------------------- -cflags = -Wall - -rule cc - command = gcc $cflags -c $in -o $out - -build foo.o: cc foo.c ---------------------------------- - -Variables -~~~~~~~~~ -Despite the non-goal of being convenient to write by hand, to keep -build files readable (debuggable), Ninja supports declaring shorter -reusable names for strings. A declaration like the following - ----------------- -cflags = -g ----------------- - -can be used on the right side of an equals sign, dereferencing it with -a dollar sign, like this: - ----------------- -rule cc - command = gcc $cflags -c $in -o $out ----------------- - -Variables can also be referenced using curly braces like `${in}`. - -Variables might better be called "bindings", in that a given variable -cannot be changed, only shadowed. There is more on how shadowing works -later in this document. - -Rules -~~~~~ - -Rules declare a short name for a command line. They begin with a line -consisting of the `rule` keyword and a name for the rule. Then -follows an indented set of `variable = value` lines. - -The basic example above declares a new rule named `cc`, along with the -command to run. In the context of a rule, the `command` variable -defines the command to run, `$in` expands to the list of -input files (`foo.c`), and `$out` to the output files (`foo.o`) for the -command. A full list of special variables is provided in -<>. - -Build statements -~~~~~~~~~~~~~~~~ - -Build statements declare a relationship between input and output -files. They begin with the `build` keyword, and have the format -+build _outputs_: _rulename_ _inputs_+. Such a declaration says that -all of the output files are derived from the input files. When the -output files are missing or when the inputs change, Ninja will run the -rule to regenerate the outputs. - -The basic example above describes how to build `foo.o`, using the `cc` -rule. - -In the scope of a `build` block (including in the evaluation of its -associated `rule`), the variable `$in` is the list of inputs and the -variable `$out` is the list of outputs. - -A build statement may be followed by an indented set of `key = value` -pairs, much like a rule. These variables will shadow any variables -when evaluating the variables in the command. For example: - ----------------- -cflags = -Wall -Werror -rule cc - command = gcc $cflags -c $in -o $out - -# If left unspecified, builds get the outer $cflags. -build foo.o: cc foo.c - -# But you can shadow variables like cflags for a particular build. -build special.o: cc special.c - cflags = -Wall - -# The variable was only shadowed for the scope of special.o; -# Subsequent build lines get the outer (original) cflags. -build bar.o: cc bar.c - ----------------- - -For more discussion of how scoping works, consult <>. - -If you need more complicated information passed from the build -statement to the rule (for example, if the rule needs "the file -extension of the first input"), pass that through as an extra -variable, like how `cflags` is passed above. - -If the top-level Ninja file is specified as an output of any build -statement and it is out of date, Ninja will rebuild and reload it -before building the targets requested by the user. - -Generating Ninja files from code -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -`misc/ninja_syntax.py` in the Ninja distribution is a tiny Python -module to facilitate generating Ninja files. It allows you to make -Python calls like `ninja.rule(name='foo', command='bar', -depfile='$out.d')` and it will generate the appropriate syntax. Feel -free to just inline it into your project's build system if it's -useful. - - -More details ------------- - -The `phony` rule -~~~~~~~~~~~~~~~~ - -The special rule name `phony` can be used to create aliases for other -targets. For example: - ----------------- -build foo: phony some/file/in/a/faraway/subdir/foo ----------------- - -This makes `ninja foo` build the longer path. Semantically, the -`phony` rule is equivalent to a plain rule where the `command` does -nothing, but phony rules are handled specially in that they aren't -printed when run, logged (see below), nor do they contribute to the -command count printed as part of the build process. - -When a `phony` target is used as an input to another build rule, the -other build rule will, semantically, consider the inputs of the -`phony` rule as its own. Therefore, `phony` rules can be used to group -inputs, e.g. header files. - -`phony` can also be used to create dummy targets for files which -may not exist at build time. If a phony build statement is written -without any dependencies, the target will be considered out of date if -it does not exist. Without a phony build statement, Ninja will report -an error if the file does not exist and is required by the build. - -To create a rule that never rebuilds, use a build rule without any input: ----------------- -rule touch - command = touch $out -build file_that_always_exists.dummy: touch -build dummy_target_to_follow_a_pattern: phony file_that_always_exists.dummy ----------------- - - -Default target statements -~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, if no targets are specified on the command line, Ninja -will build every output that is not named as an input elsewhere. -You can override this behavior using a default target statement. -A default target statement causes Ninja to build only a given subset -of output files if none are specified on the command line. - -Default target statements begin with the `default` keyword, and have -the format +default _targets_+. A default target statement must appear -after the build statement that declares the target as an output file. -They are cumulative, so multiple statements may be used to extend -the list of default targets. For example: - ----------------- -default foo bar -default baz ----------------- - -This causes Ninja to build the `foo`, `bar` and `baz` targets by -default. - - -[[ref_log]] -The Ninja log -~~~~~~~~~~~~~ - -For each built file, Ninja keeps a log of the command used to build -it. Using this log Ninja can know when an existing output was built -with a different command line than the build files specify (i.e., the -command line changed) and knows to rebuild the file. - -The log file is kept in the build root in a file called `.ninja_log`. -If you provide a variable named `builddir` in the outermost scope, -`.ninja_log` will be kept in that directory instead. - - -[[ref_versioning]] -Version compatibility -~~~~~~~~~~~~~~~~~~~~~ - -_Available since Ninja 1.2._ - -Ninja version labels follow the standard major.minor.patch format, -where the major version is increased on backwards-incompatible -syntax/behavioral changes and the minor version is increased on new -behaviors. Your `build.ninja` may declare a variable named -`ninja_required_version` that asserts the minimum Ninja version -required to use the generated file. For example, - ------ -ninja_required_version = 1.1 ------ - -declares that the build file relies on some feature that was -introduced in Ninja 1.1 (perhaps the `pool` syntax), and that -Ninja 1.1 or greater must be used to build. Unlike other Ninja -variables, this version requirement is checked immediately when -the variable is encountered in parsing, so it's best to put it -at the top of the build file. - -Ninja always warns if the major versions of Ninja and the -`ninja_required_version` don't match; a major version change hasn't -come up yet so it's difficult to predict what behavior might be -required. - -[[ref_headers]] -C/C++ header dependencies -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To get C/C++ header dependencies (or any other build dependency that -works in a similar way) correct Ninja has some extra functionality. - -The problem with headers is that the full list of files that a given -source file depends on can only be discovered by the compiler: -different preprocessor defines and include paths cause different files -to be used. Some compilers can emit this information while building, -and Ninja can use that to get its dependencies perfect. - -Consider: if the file has never been compiled, it must be built anyway, -generating the header dependencies as a side effect. If any file is -later modified (even in a way that changes which headers it depends -on) the modification will cause a rebuild as well, keeping the -dependencies up to date. - -When loading these special dependencies, Ninja implicitly adds extra -build edges such that it is not an error if the listed dependency is -missing. This allows you to delete a header file and rebuild without -the build aborting due to a missing input. - -depfile -^^^^^^^ - -`gcc` (and other compilers like `clang`) support emitting dependency -information in the syntax of a Makefile. (Any command that can write -dependencies in this form can be used, not just `gcc`.) - -To bring this information into Ninja requires cooperation. On the -Ninja side, the `depfile` attribute on the `build` must point to a -path where this data is written. (Ninja only supports the limited -subset of the Makefile syntax emitted by compilers.) Then the command -must know to write dependencies into the `depfile` path. -Use it like in the following example: - ----- -rule cc - depfile = $out.d - command = gcc -MD -MF $out.d [other gcc flags here] ----- - -The `-MD` flag to `gcc` tells it to output header dependencies, and -the `-MF` flag tells it where to write them. - -deps -^^^^ - -_(Available since Ninja 1.3.)_ - -It turns out that for large projects (and particularly on Windows, -where the file system is slow) loading these dependency files on -startup is slow. - -Ninja 1.3 can instead process dependencies just after they're generated -and save a compacted form of the same information in a Ninja-internal -database. - -Ninja supports this processing in two forms. - -1. `deps = gcc` specifies that the tool outputs `gcc`-style dependencies - in the form of Makefiles. Adding this to the above example will - cause Ninja to process the `depfile` immediately after the - compilation finishes, then delete the `.d` file (which is only used - as a temporary). - -2. `deps = msvc` specifies that the tool outputs header dependencies - in the form produced by the Visual Studio compiler's - http://msdn.microsoft.com/en-us/library/hdkef6tk(v=vs.90).aspx[`/showIncludes` - flag]. Briefly, this means the tool outputs specially-formatted lines - to its stdout. Ninja then filters these lines from the displayed - output. No `depfile` attribute is necessary, but the localized string - in front of the header file path should be globally defined. For instance, - `msvc_deps_prefix = Note: including file:` - for an English Visual Studio (the default). -+ ----- -msvc_deps_prefix = Note: including file: -rule cc - deps = msvc - command = cl /showIncludes -c $in /Fo$out ----- - -If the include directory directives are using absolute paths, your depfile -may result in a mixture of relative and absolute paths. Paths used by other -build rules need to match exactly. Therefore, it is recommended to use -relative paths in these cases. - -[[ref_pool]] -Pools -~~~~~ - -_Available since Ninja 1.1._ - -Pools allow you to allocate one or more rules or edges a finite number -of concurrent jobs which is more tightly restricted than the default -parallelism. - -This can be useful, for example, to restrict a particular expensive rule -(like link steps for huge executables), or to restrict particular build -statements which you know perform poorly when run concurrently. - -Each pool has a `depth` variable which is specified in the build file. -The pool is then referred to with the `pool` variable on either a rule -or a build statement. - -No matter what pools you specify, ninja will never run more concurrent jobs -than the default parallelism, or the number of jobs specified on the command -line (with `-j`). - ----------------- -# No more than 4 links at a time. -pool link_pool - depth = 4 - -# No more than 1 heavy object at a time. -pool heavy_object_pool - depth = 1 - -rule link - ... - pool = link_pool - -rule cc - ... - -# The link_pool is used here. Only 4 links will run concurrently. -build foo.exe: link input.obj - -# A build statement can be exempted from its rule's pool by setting an -# empty pool. This effectively puts the build statement back into the default -# pool, which has infinite depth. -build other.exe: link input.obj - pool = - -# A build statement can specify a pool directly. -# Only one of these builds will run at a time. -build heavy_object1.obj: cc heavy_obj1.cc - pool = heavy_object_pool -build heavy_object2.obj: cc heavy_obj2.cc - pool = heavy_object_pool - ----------------- - -The `console` pool -^^^^^^^^^^^^^^^^^^ - -_Available since Ninja 1.5._ - -There exists a pre-defined pool named `console` with a depth of 1. It has -the special property that any task in the pool has direct access to the -standard input, output and error streams provided to Ninja, which are -normally connected to the user's console (hence the name) but could be -redirected. This can be useful for interactive tasks or long-running tasks -which produce status updates on the console (such as test suites). - -While a task in the `console` pool is running, Ninja's regular output (such -as progress status and output from concurrent tasks) is buffered until -it completes. - -[[ref_ninja_file]] -Ninja file reference --------------------- - -A file is a series of declarations. A declaration can be one of: - -1. A rule declaration, which begins with +rule _rulename_+, and - then has a series of indented lines defining variables. - -2. A build edge, which looks like +build _output1_ _output2_: - _rulename_ _input1_ _input2_+. + - Implicit dependencies may be tacked on the end with +| - _dependency1_ _dependency2_+. + - Order-only dependencies may be tacked on the end with +|| - _dependency1_ _dependency2_+. (See <>.) - Validations may be taken on the end with +|@ _validation1_ _validation2_+. - (See <>.) -+ -Implicit outputs _(available since Ninja 1.7)_ may be added before -the `:` with +| _output1_ _output2_+ and do not appear in `$out`. -(See <>.) - -3. Variable declarations, which look like +_variable_ = _value_+. - -4. Default target statements, which look like +default _target1_ _target2_+. - -5. References to more files, which look like +subninja _path_+ or - +include _path_+. The difference between these is explained below - <>. - -6. A pool declaration, which looks like +pool _poolname_+. Pools are explained - <>. - -[[ref_lexer]] -Lexical syntax -~~~~~~~~~~~~~~ - -Ninja is mostly encoding agnostic, as long as the bytes Ninja cares -about (like slashes in paths) are ASCII. This means e.g. UTF-8 or -ISO-8859-1 input files ought to work. - -Comments begin with `#` and extend to the end of the line. - -Newlines are significant. Statements like `build foo bar` are a set -of space-separated tokens that end at the newline. Newlines and -spaces within a token must be escaped. - -There is only one escape character, `$`, and it has the following -behaviors: - -`$` followed by a newline:: escape the newline (continue the current line -across a line break). - -`$` followed by text:: a variable reference. - -`${varname}`:: alternate syntax for `$varname`. - -`$` followed by space:: a space. (This is only necessary in lists of -paths, where a space would otherwise separate filenames. See below.) - -`$:` :: a colon. (This is only necessary in `build` lines, where a colon -would otherwise terminate the list of outputs.) - -`$$`:: a literal `$`. - -A `build` or `default` statement is first parsed as a space-separated -list of filenames and then each name is expanded. This means that -spaces within a variable will result in spaces in the expanded -filename. - ----- -spaced = foo bar -build $spaced/baz other$ file: ... -# The above build line has two outputs: "foo bar/baz" and "other file". ----- - -In a `name = value` statement, whitespace at the beginning of a value -is always stripped. Whitespace at the beginning of a line after a -line continuation is also stripped. - ----- -two_words_with_one_space = foo $ - bar -one_word_with_no_space = foo$ - bar ----- - -Other whitespace is only significant if it's at the beginning of a -line. If a line is indented more than the previous one, it's -considered part of its parent's scope; if it is indented less than the -previous one, it closes the previous scope. - -[[ref_toplevel]] -Top-level variables -~~~~~~~~~~~~~~~~~~~ - -Two variables are significant when declared in the outermost file scope. - -`builddir`:: a directory for some Ninja output files. See <>. (You can also store other build output - in this directory.) - -`ninja_required_version`:: the minimum version of Ninja required to process - the build correctly. See <>. - - -[[ref_rule]] -Rule variables -~~~~~~~~~~~~~~ - -A `rule` block contains a list of `key = value` declarations that -affect the processing of the rule. Here is a full list of special -keys. - -`command` (_required_):: the command line to run. Each `rule` may - have only one `command` declaration. See <> for more details on quoting and executing multiple commands. - -`depfile`:: path to an optional `Makefile` that contains extra - _implicit dependencies_ (see <>). This is explicitly to support C/C++ header - dependencies; see <>. - -`deps`:: _(Available since Ninja 1.3.)_ if present, must be one of - `gcc` or `msvc` to specify special dependency processing. See - <>. The generated database is - stored as `.ninja_deps` in the `builddir`, see <>. - -`msvc_deps_prefix`:: _(Available since Ninja 1.5.)_ defines the string - which should be stripped from msvc's /showIncludes output. Only - needed when `deps = msvc` and no English Visual Studio version is used. - -`description`:: a short description of the command, used to pretty-print - the command as it's running. The `-v` flag controls whether to print - the full command or its description; if a command fails, the full command - line will always be printed before the command's output. - -`dyndep`:: _(Available since Ninja 1.10.)_ Used only on build statements. - If present, must name one of the build statement inputs. Dynamically - discovered dependency information will be loaded from the file. - See the <> section for details. - -`generator`:: if present, specifies that this rule is used to - re-invoke the generator program. Files built using `generator` - rules are treated specially in two ways: firstly, they will not be - rebuilt if the command line changes; and secondly, they are not - cleaned by default. - -`in`:: the space-separated list of files provided as inputs to the build line - referencing this `rule`, shell-quoted if it appears in commands. (`$in` is - provided solely for convenience; if you need some subset or variant of this - list of files, just construct a new variable with that list and use - that instead.) - -`in_newline`:: the same as `$in` except that multiple inputs are - separated by newlines rather than spaces. (For use with - `$rspfile_content`; this works around a bug in the MSVC linker where - it uses a fixed-size buffer for processing input.) - -`out`:: the space-separated list of files provided as outputs to the build line - referencing this `rule`, shell-quoted if it appears in commands. - -`restat`:: if present, causes Ninja to re-stat the command's outputs - after execution of the command. Each output whose modification time - the command did not change will be treated as though it had never - needed to be built. This may cause the output's reverse - dependencies to be removed from the list of pending build actions. - -`rspfile`, `rspfile_content`:: if present (both), Ninja will use a - response file for the given command, i.e. write the selected string - (`rspfile_content`) to the given file (`rspfile`) before calling the - command and delete the file after successful execution of the - command. -+ -This is particularly useful on Windows OS, where the maximal length of -a command line is limited and response files must be used instead. -+ -Use it like in the following example: -+ ----- -rule link - command = link.exe /OUT$out [usual link flags here] @$out.rsp - rspfile = $out.rsp - rspfile_content = $in - -build myapp.exe: link a.obj b.obj [possibly many other .obj files] ----- - -[[ref_rule_command]] -Interpretation of the `command` variable -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Fundamentally, command lines behave differently on Unixes and Windows. - -On Unixes, commands are arrays of arguments. The Ninja `command` -variable is passed directly to `sh -c`, which is then responsible for -interpreting that string into an argv array. Therefore, the quoting -rules are those of the shell, and you can use all the normal shell -operators, like `&&` to chain multiple commands, or `VAR=value cmd` to -set environment variables. - -On Windows, commands are strings, so Ninja passes the `command` string -directly to `CreateProcess`. (In the common case of simply executing -a compiler this means there is less overhead.) Consequently, the -quoting rules are determined by the called program, which on Windows -are usually provided by the C library. If you need shell -interpretation of the command (such as the use of `&&` to chain -multiple commands), make the command execute the Windows shell by -prefixing the command with `cmd /c`. Ninja may error with "invalid parameter" -which usually indicates that the command line length has been exceeded. - -[[ref_outputs]] -Build outputs -~~~~~~~~~~~~~ - -There are two types of build outputs which are subtly different. - -1. _Explicit outputs_, as listed in a build line. These are - available as the `$out` variable in the rule. -+ -This is the standard form of output to be used for e.g. the -object file of a compile command. - -2. _Implicit outputs_, as listed in a build line with the syntax +| - _out1_ _out2_+ + before the `:` of a build line _(available since - Ninja 1.7)_. The semantics are identical to explicit outputs, - the only difference is that implicit outputs don't show up in the - `$out` variable. -+ -This is for expressing outputs that don't show up on the -command line of the command. - -[[ref_dependencies]] -Build dependencies -~~~~~~~~~~~~~~~~~~ - -There are three types of build dependencies which are subtly different. - -1. _Explicit dependencies_, as listed in a build line. These are - available as the `$in` variable in the rule. Changes in these files - cause the output to be rebuilt; if these files are missing and - Ninja doesn't know how to build them, the build is aborted. -+ -This is the standard form of dependency to be used e.g. for the -source file of a compile command. - -2. _Implicit dependencies_, either as picked up from - a `depfile` attribute on a rule or from the syntax +| _dep1_ - _dep2_+ on the end of a build line. The semantics are identical to - explicit dependencies, the only difference is that implicit dependencies - don't show up in the `$in` variable. -+ -This is for expressing dependencies that don't show up on the -command line of the command; for example, for a rule that runs a -script that reads a hardcoded file, the hardcoded file should -be an implicit dependency, as changes to the file should cause -the output to rebuild, even though it doesn't show up in the arguments. -+ -Note that dependencies as loaded through depfiles have slightly different -semantics, as described in the <>. - -3. _Order-only dependencies_, expressed with the syntax +|| _dep1_ - _dep2_+ on the end of a build line. When these are out of date, the - output is not rebuilt until they are built, but changes in order-only - dependencies alone do not cause the output to be rebuilt. -+ -Order-only dependencies can be useful for bootstrapping dependencies -that are only discovered during build time: for example, to generate a -header file before starting a subsequent compilation step. (Once the -header is used in compilation, a generated dependency file will then -express the implicit dependency.) - -File paths are compared as is, which means that an absolute path and a -relative path, pointing to the same file, are considered different by Ninja. - -[[validations]] -Validations -~~~~~~~~~~~ - -_Available since Ninja 1.11._ - -Validations listed on the build line cause the specified files to be -added to the top level of the build graph (as if they were specified -on the Ninja command line) whenever the build line is a transitive -dependency of one of the targets specified on the command line or a -default target. - -Validations are added to the build graph regardless of whether the output -files of the build statement are dirty are not, and the dirty state of -the build statement that outputs the file being used as a validation -has no effect on the dirty state of the build statement that requested it. - -A build edge can list another build edge as a validation even if the second -edge depends on the first. - -Validations are designed to handle rules that perform error checking but -don't produce any artifacts needed by the build, for example, static -analysis tools. Marking the static analysis rule as an implicit input -of the main build rule of the source files or of the rules that depend -on the main build rule would slow down the critical path of the build, -but using a validation would allow the build to proceed in parallel with -the static analysis rule once the main build rule is complete. - -Variable expansion -~~~~~~~~~~~~~~~~~~ - -Variables are expanded in paths (in a `build` or `default` statement) -and on the right side of a `name = value` statement. - -When a `name = value` statement is evaluated, its right-hand side is -expanded immediately (according to the below scoping rules), and -from then on `$name` expands to the static string as the result of the -expansion. It is never the case that you'll need to "double-escape" a -value to prevent it from getting expanded twice. - -All variables are expanded immediately as they're encountered in parsing, -with one important exception: variables in `rule` blocks are expanded -when the rule is _used_, not when it is declared. In the following -example, the `demo` rule prints "this is a demo of bar". - ----- -rule demo - command = echo "this is a demo of $foo" - -build out: demo - foo = bar ----- - -[[ref_scope]] -Evaluation and scoping -~~~~~~~~~~~~~~~~~~~~~~ - -Top-level variable declarations are scoped to the file they occur in. - -Rule declarations are also scoped to the file they occur in. -_(Available since Ninja 1.6)_ - -The `subninja` keyword, used to include another `.ninja` file, -introduces a new scope. The included `subninja` file may use the -variables and rules from the parent file, and shadow their values for the file's -scope, but it won't affect values of the variables in the parent. - -To include another `.ninja` file in the current scope, much like a C -`#include` statement, use `include` instead of `subninja`. - -Variable declarations indented in a `build` block are scoped to the -`build` block. The full lookup order for a variable expanded in a -`build` block (or the `rule` is uses) is: - -1. Special built-in variables (`$in`, `$out`). - -2. Build-level variables from the `build` block. - -3. Rule-level variables from the `rule` block (i.e. `$command`). - (Note from the above discussion on expansion that these are - expanded "late", and may make use of in-scope bindings like `$in`.) - -4. File-level variables from the file that the `build` line was in. - -5. Variables from the file that included that file using the - `subninja` keyword. - -[[ref_dyndep]] -Dynamic Dependencies --------------------- - -_Available since Ninja 1.10._ - -Some use cases require implicit dependency information to be dynamically -discovered from source file content _during the build_ in order to build -correctly on the first run (e.g. Fortran module dependencies). This is -unlike <> which are only needed on the -second run and later to rebuild correctly. A build statement may have a -`dyndep` binding naming one of its inputs to specify that dynamic -dependency information must be loaded from the file. For example: - ----- -build out: ... || foo - dyndep = foo -build foo: ... ----- - -This specifies that file `foo` is a dyndep file. Since it is an input, -the build statement for `out` can never be executed before `foo` is built. -As soon as `foo` is finished Ninja will read it to load dynamically -discovered dependency information for `out`. This may include additional -implicit inputs and/or outputs. Ninja will update the build graph -accordingly and the build will proceed as if the information was known -originally. - -Dyndep file reference -~~~~~~~~~~~~~~~~~~~~~ - -Files specified by `dyndep` bindings use the same <> -as <> and have the following layout. - -1. A version number in the form `[.][]`: -+ ----- -ninja_dyndep_version = 1 ----- -+ -Currently the version number must always be `1` or `1.0` but may have -an arbitrary suffix. - -2. One or more build statements of the form: -+ ----- -build out | imp-outs... : dyndep | imp-ins... ----- -+ -Every statement must specify exactly one explicit output and must use -the rule name `dyndep`. The `| imp-outs...` and `| imp-ins...` portions -are optional. - -3. An optional `restat` <> on each build statement. - -The build statements in a dyndep file must have a one-to-one correspondence -to build statements in the <> that name the -dyndep file in a `dyndep` binding. No dyndep build statement may be omitted -and no extra build statements may be specified. - -Dyndep Examples -~~~~~~~~~~~~~~~ - -Fortran Modules -^^^^^^^^^^^^^^^ - -Consider a Fortran source file `foo.f90` that provides a module -`foo.mod` (an implicit output of compilation) and another source file -`bar.f90` that uses the module (an implicit input of compilation). This -implicit dependency must be discovered before we compile either source -in order to ensure that `bar.f90` never compiles before `foo.f90`, and -that `bar.f90` recompiles when `foo.mod` changes. We can achieve this -as follows: - ----- -rule f95 - command = f95 -o $out -c $in -rule fscan - command = fscan -o $out $in - -build foobar.dd: fscan foo.f90 bar.f90 - -build foo.o: f95 foo.f90 || foobar.dd - dyndep = foobar.dd -build bar.o: f95 bar.f90 || foobar.dd - dyndep = foobar.dd ----- - -In this example the order-only dependencies ensure that `foobar.dd` is -generated before either source compiles. The hypothetical `fscan` tool -scans the source files, assumes each will be compiled to a `.o` of the -same name, and writes `foobar.dd` with content such as: - ----- -ninja_dyndep_version = 1 -build foo.o | foo.mod: dyndep -build bar.o: dyndep | foo.mod ----- - -Ninja will load this file to add `foo.mod` as an implicit output of -`foo.o` and implicit input of `bar.o`. This ensures that the Fortran -sources are always compiled in the proper order and recompiled when -needed. - -Tarball Extraction -^^^^^^^^^^^^^^^^^^ - -Consider a tarball `foo.tar` that we want to extract. The extraction time -can be recorded with a `foo.tar.stamp` file so that extraction repeats if -the tarball changes, but we also would like to re-extract if any of the -outputs is missing. However, the list of outputs depends on the content -of the tarball and cannot be spelled out explicitly in the ninja build file. -We can achieve this as follows: - ----- -rule untar - command = tar xf $in && touch $out -rule scantar - command = scantar --stamp=$stamp --dd=$out $in -build foo.tar.dd: scantar foo.tar - stamp = foo.tar.stamp -build foo.tar.stamp: untar foo.tar || foo.tar.dd - dyndep = foo.tar.dd ----- - -In this example the order-only dependency ensures that `foo.tar.dd` is -built before the tarball extracts. The hypothetical `scantar` tool -will read the tarball (e.g. via `tar tf`) and write `foo.tar.dd` with -content such as: - ----- -ninja_dyndep_version = 1 -build foo.tar.stamp | file1.txt file2.txt : dyndep - restat = 1 ----- - -Ninja will load this file to add `file1.txt` and `file2.txt` as implicit -outputs of `foo.tar.stamp`, and to mark the build statement for `restat`. -On future builds, if any implicit output is missing the tarball will be -extracted again. The `restat` binding tells Ninja to tolerate the fact -that the implicit outputs may not have modification times newer than -the tarball itself (avoiding re-extraction on every build). diff --git a/doc/style.css b/doc/style.css deleted file mode 100644 index 363e272b24..0000000000 --- a/doc/style.css +++ /dev/null @@ -1,55 +0,0 @@ -:root { - color-scheme: light dark; -} - -body { - margin: 5ex 10ex; - max-width: 80ex; - line-height: 1.5; - font-family: sans-serif; -} - -h1, h2, h3 { - font-weight: normal; -} - -pre, code { - font-family: x, monospace; -} - -pre { - padding: 1ex; - background: #eee; - border: solid 1px #ddd; - min-width: 0; - font-size: 90%; -} -@media (prefers-color-scheme: dark) { - pre { - background: #333; - border: solid 1px #444; - } -} - -code { - color: #007; -} -@media (prefers-color-scheme: dark) { - code { - color: #a7cec8; - } -} - -div.chapter { - margin-top: 4em; - border-top: solid 2px black; -} -@media (prefers-color-scheme: dark) { - div.chapter { - border-top: solid 2px white; - } -} - -p { - margin-top: 0; -} diff --git a/misc/output_test.py b/misc/output_test.py index c1f9f2579d..f48968bc9a 100755 --- a/misc/output_test.py +++ b/misc/output_test.py @@ -228,6 +228,71 @@ def test_tool_inputs(self) -> None: out2 ''') + self.assertEqual(run(plan, flags='-t inputs --dependency-order out3'), +'''in2 +in1 +out1 +out2 +implicit +order_only +''') + + # Verify that results are shell-escaped by default, unless --no-shell-escape + # is used. Also verify that phony outputs are never part of the results. + quote = '"' if platform.system() == "Windows" else "'" + + plan = ''' +rule cat + command = cat $in $out +build out1 : cat in1 +build out$ 2 : cat out1 +build out$ 3 : phony out$ 2 +build all: phony out$ 3 +''' + + # Quoting changes the order of results when sorting alphabetically. + self.assertEqual(run(plan, flags='-t inputs all'), +f'''{quote}out 2{quote} +in1 +out1 +''') + + self.assertEqual(run(plan, flags='-t inputs --no-shell-escape all'), +'''in1 +out 2 +out1 +''') + + # But not when doing dependency order. + self.assertEqual( + run( + plan, + flags='-t inputs --dependency-order all' + ), + f'''in1 +out1 +{quote}out 2{quote} +''') + + self.assertEqual( + run( + plan, + flags='-t inputs --dependency-order --no-shell-escape all' + ), + f'''in1 +out1 +out 2 +''') + + self.assertEqual( + run( + plan, + flags='-t inputs --dependency-order --no-shell-escape --print0 all' + ), + f'''in1\0out1\0out 2\0''' + ) + + def test_explain_output(self): b = BuildDir('''\ build .FORCE: phony diff --git a/src/build.cc b/src/build.cc index d9f6f8b839..01f31a9faf 100644 --- a/src/build.cc +++ b/src/build.cc @@ -526,7 +526,7 @@ void Plan::ComputeCriticalPath() { for (Edge* edge : sorted_edges) edge->set_critical_path_weight(EdgeWeightHeuristic(edge)); - // Second propagate / increment weidghts from + // Second propagate / increment weights from // children to parents. Scan the list // in reverse order to do so. for (auto reverse_it = sorted_edges.rbegin(); diff --git a/src/build_test.cc b/src/build_test.cc index c84190a040..7675aceecf 100644 --- a/src/build_test.cc +++ b/src/build_test.cc @@ -1852,7 +1852,7 @@ TEST_F(BuildWithLogTest, RestatSingleDependentOutputDirty) { // out2 and out3 will be built even though "in" is not touched when built. // Then, since out2 is rebuilt, out4 should be rebuilt -- the restat on the // "true" rule should not lead to the "touch" edge writing out2 and out3 being - // cleard. + // cleared. command_runner_.commands_ran_.clear(); state_.Reset(); EXPECT_TRUE(builder_.AddTarget("out4", &err)); @@ -3261,7 +3261,7 @@ TEST_F(BuildWithDepsLogTest, RestatMissingDepfileDepslog) { // Touch 'header.in', blank dependencies log (create a different one). // Building header.h triggers 'restat' outputs cleanup. - // Validate that out is rebuilt netherless, as deps are missing. + // Validate that out is rebuilt nevertheless, as deps are missing. fs_.Tick(); fs_.Create("header.in", ""); diff --git a/src/graph.cc b/src/graph.cc index 143eabdfb4..f04ffb47c8 100644 --- a/src/graph.cc +++ b/src/graph.cc @@ -496,28 +496,6 @@ std::string EdgeEnv::MakePathList(const Node* const* const span, return result; } -void Edge::CollectInputs(bool shell_escape, - std::vector* out) const { - for (std::vector::const_iterator it = inputs_.begin(); - it != inputs_.end(); ++it) { - std::string path = (*it)->PathDecanonicalized(); - if (shell_escape) { - std::string unescaped; - unescaped.swap(path); -#ifdef _WIN32 - GetWin32EscapedString(unescaped, &path); -#else - GetShellEscapedString(unescaped, &path); -#endif - } -#if __cplusplus >= 201103L - out->push_back(std::move(path)); -#else - out->push_back(path); -#endif - } -} - std::string Edge::EvaluateCommand(const bool incl_rsp_file) const { string command = GetBinding("command"); if (incl_rsp_file) { @@ -779,3 +757,47 @@ vector::iterator ImplicitDepLoader::PreallocateSpace(Edge* edge, edge->implicit_deps_ += count; return edge->inputs_.end() - edge->order_only_deps_ - count; } + +void InputsCollector::VisitNode(const Node* node) { + const Edge* edge = node->in_edge(); + + if (!edge) // A source file. + return; + + // Add inputs of the producing edge to the result, + // except if they are themselves produced by a phony + // edge. + for (const Node* input : edge->inputs_) { + if (!visited_nodes_.insert(input).second) + continue; + + VisitNode(input); + + const Edge* input_edge = input->in_edge(); + if (!(input_edge && input_edge->is_phony())) { + inputs_.push_back(input); + } + } +} + +std::vector InputsCollector::GetInputsAsStrings( + bool shell_escape) const { + std::vector result; + result.reserve(inputs_.size()); + + for (const Node* input : inputs_) { + std::string unescaped = input->PathDecanonicalized(); + if (shell_escape) { + std::string path; +#ifdef _WIN32 + GetWin32EscapedString(unescaped, &path); +#else + GetShellEscapedString(unescaped, &path); +#endif + result.push_back(std::move(path)); + } else { + result.push_back(std::move(unescaped)); + } + } + return result; +} diff --git a/src/graph.h b/src/graph.h index 314c44296a..806260e5d7 100644 --- a/src/graph.h +++ b/src/graph.h @@ -201,9 +201,6 @@ struct Edge { void Dump(const char* prefix="") const; - // Append all edge explicit inputs to |*out|. Possibly with shell escaping. - void CollectInputs(bool shell_escape, std::vector* out) const; - // critical_path_weight is the priority during build scheduling. The // "critical path" between this edge's inputs and any target node is // the path which maximises the sum oof weights along that path. @@ -425,4 +422,41 @@ class EdgePriorityQueue: } }; +/// A class used to collect the transitive set of inputs from a given set +/// of starting nodes. Used to implement the `inputs` tool. +/// +/// When collecting inputs, the outputs of phony edges are always ignored +/// from the result, but are followed by the dependency walk. +/// +/// Usage is: +/// - Create instance. +/// - Call VisitNode() for each root node to collect inputs from. +/// - Call inputs() to retrieve the list of input node pointers. +/// - Call GetInputsAsStrings() to retrieve the list of inputs as a string +/// vector. +/// +struct InputsCollector { + /// Visit a single @arg node during this collection. + void VisitNode(const Node* node); + + /// Retrieve list of visited input nodes. A dependency always appears + /// before its dependents in the result, but final order depends on the + /// order of the VisitNode() calls performed before this. + const std::vector& inputs() const { return inputs_; } + + /// Same as inputs(), but returns the list of visited nodes as a list of + /// strings, with optional shell escaping. + std::vector GetInputsAsStrings(bool shell_escape = false) const; + + /// Reset collector state. + void Reset() { + inputs_.clear(); + visited_nodes_.clear(); + } + + private: + std::vector inputs_; + std::set visited_nodes_; +}; + #endif // NINJA_GRAPH_H_ diff --git a/src/graph_test.cc b/src/graph_test.cc index f909b906fd..6c654eeb32 100644 --- a/src/graph_test.cc +++ b/src/graph_test.cc @@ -215,28 +215,90 @@ TEST_F(GraphTest, RootNodes) { } } -TEST_F(GraphTest, CollectInputs) { +TEST_F(GraphTest, InputsCollector) { + // Build plan for the following graph: + // + // in1 + // |___________ + // | | + // === === + // | | + // out1 mid1 + // | ____|_____ + // | | | + // | === ======= + // | | | | + // | out2 out3 out4 + // | | | + // =======phony====== + // | + // all + // + ASSERT_NO_FATAL_FAILURE(AssertParse(&state_, + "build out1: cat in1\n" + "build mid1: cat in1\n" + "build out2: cat mid1\n" + "build out3 out4: cat mid1\n" + "build all: phony out1 out2 out3\n")); + + InputsCollector collector; + + // Start visit from out1, this should add in1 to the inputs. + collector.Reset(); + collector.VisitNode(GetNode("out1")); + auto inputs = collector.GetInputsAsStrings(); + ASSERT_EQ(1u, inputs.size()); + EXPECT_EQ("in1", inputs[0]); + + // Add a visit from out2, this should add mid1. + collector.VisitNode(GetNode("out2")); + inputs = collector.GetInputsAsStrings(); + ASSERT_EQ(2u, inputs.size()); + EXPECT_EQ("in1", inputs[0]); + EXPECT_EQ("mid1", inputs[1]); + + // Another visit from all, this should add out1, out2 and out3, + // but not out4. + collector.VisitNode(GetNode("all")); + inputs = collector.GetInputsAsStrings(); + ASSERT_EQ(5u, inputs.size()); + EXPECT_EQ("in1", inputs[0]); + EXPECT_EQ("mid1", inputs[1]); + EXPECT_EQ("out1", inputs[2]); + EXPECT_EQ("out2", inputs[3]); + EXPECT_EQ("out3", inputs[4]); + + collector.Reset(); + + // Starting directly from all, will add out1 before mid1 compared + // to the previous example above. + collector.VisitNode(GetNode("all")); + inputs = collector.GetInputsAsStrings(); + ASSERT_EQ(5u, inputs.size()); + EXPECT_EQ("in1", inputs[0]); + EXPECT_EQ("out1", inputs[1]); + EXPECT_EQ("mid1", inputs[2]); + EXPECT_EQ("out2", inputs[3]); + EXPECT_EQ("out3", inputs[4]); +} + +TEST_F(GraphTest, InputsCollectorWithEscapes) { ASSERT_NO_FATAL_FAILURE(AssertParse( &state_, "build out$ 1: cat in1 in2 in$ with$ space | implicit || order_only\n")); - std::vector inputs; - Edge* edge = GetNode("out 1")->in_edge(); - - // Test without shell escaping. - inputs.clear(); - edge->CollectInputs(false, &inputs); - EXPECT_EQ(5u, inputs.size()); + InputsCollector collector; + collector.VisitNode(GetNode("out 1")); + auto inputs = collector.GetInputsAsStrings(); + ASSERT_EQ(5u, inputs.size()); EXPECT_EQ("in1", inputs[0]); EXPECT_EQ("in2", inputs[1]); EXPECT_EQ("in with space", inputs[2]); EXPECT_EQ("implicit", inputs[3]); EXPECT_EQ("order_only", inputs[4]); - // Test with shell escaping. - inputs.clear(); - edge->CollectInputs(true, &inputs); - EXPECT_EQ(5u, inputs.size()); + inputs = collector.GetInputsAsStrings(true); + ASSERT_EQ(5u, inputs.size()); EXPECT_EQ("in1", inputs[0]); EXPECT_EQ("in2", inputs[1]); #ifdef _WIN32 diff --git a/src/json.h b/src/json.h index f39c759236..3e5cf7817c 100644 --- a/src/json.h +++ b/src/json.h @@ -17,7 +17,7 @@ #include -// Encode a string in JSON format without encolsing quotes +// Encode a string in JSON format without enclosing quotes std::string EncodeJSONString(const std::string& in); // Print a string in JSON format to stdout without enclosing quotes diff --git a/src/ninja.cc b/src/ninja.cc index 2902359f15..7885bb3682 100644 --- a/src/ninja.cc +++ b/src/ninja.cc @@ -154,7 +154,7 @@ struct NinjaMain : public BuildLogUser { bool RebuildManifest(const char* input_file, string* err, Status* status); /// For each edge, lookup in build log how long it took last time, - /// and record that in the edge itself. It will be used for ETA predicton. + /// and record that in the edge itself. It will be used for ETA prediction. void ParsePreviousElapsedTimes(); /// Build the targets listed on the command line. @@ -761,43 +761,50 @@ int NinjaMain::ToolCommands(const Options* options, int argc, char* argv[]) { return 0; } -void CollectInputs(Edge* edge, std::set* seen, - std::vector* result) { - if (!edge) - return; - if (!seen->insert(edge).second) - return; - - for (vector::iterator in = edge->inputs_.begin(); - in != edge->inputs_.end(); ++in) - CollectInputs((*in)->in_edge(), seen, result); - - if (!edge->is_phony()) { - edge->CollectInputs(true, result); - } -} - int NinjaMain::ToolInputs(const Options* options, int argc, char* argv[]) { // The inputs tool uses getopt, and expects argv[0] to contain the name of // the tool, i.e. "inputs". argc++; argv--; + + bool print0 = false; + bool shell_escape = true; + bool dependency_order = false; + optind = 1; int opt; const option kLongOptions[] = { { "help", no_argument, NULL, 'h' }, + { "no-shell-escape", no_argument, NULL, 'E' }, + { "print0", no_argument, NULL, '0' }, + { "dependency-order", no_argument, NULL, + 'd' }, { NULL, 0, NULL, 0 } }; - while ((opt = getopt_long(argc, argv, "h", kLongOptions, NULL)) != -1) { + while ((opt = getopt_long(argc, argv, "h0Ed", kLongOptions, NULL)) != -1) { switch (opt) { + case 'd': + dependency_order = true; + break; + case 'E': + shell_escape = false; + break; + case '0': + print0 = true; + break; case 'h': default: // clang-format off printf( "Usage '-t inputs [options] [targets]\n" "\n" -"List all inputs used for a set of targets. Note that this includes\n" -"explicit, implicit and order-only inputs, but not validation ones.\n\n" +"List all inputs used for a set of targets, sorted in dependency order.\n" +"Note that by default, results are shell escaped, and sorted alphabetically,\n" +"and never include validation target paths.\n\n" "Options:\n" -" -h, --help Print this message.\n"); +" -h, --help Print this message.\n" +" -0, --print0 Use \\0, instead of \\n as a line terminator.\n" +" -E, --no-shell-escape Do not shell escape the result.\n" +" -d, --dependency-order Sort results by dependency order.\n" + ); // clang-format on return 1; } @@ -805,25 +812,31 @@ int NinjaMain::ToolInputs(const Options* options, int argc, char* argv[]) { argv += optind; argc -= optind; - vector nodes; - string err; + std::vector nodes; + std::string err; if (!CollectTargetsFromArgs(argc, argv, &nodes, &err)) { Error("%s", err.c_str()); return 1; } - std::set seen; - std::vector result; - for (vector::iterator in = nodes.begin(); in != nodes.end(); ++in) - CollectInputs((*in)->in_edge(), &seen, &result); + InputsCollector collector; + for (const Node* node : nodes) + collector.VisitNode(node); - // Make output deterministic by sorting then removing duplicates. - std::sort(result.begin(), result.end()); - result.erase(std::unique(result.begin(), result.end()), result.end()); - - for (size_t n = 0; n < result.size(); ++n) - puts(result[n].c_str()); + std::vector inputs = collector.GetInputsAsStrings(shell_escape); + if (!dependency_order) + std::sort(inputs.begin(), inputs.end()); + if (print0) { + for (const std::string& input : inputs) { + fwrite(input.c_str(), input.size(), 1, stdout); + fputc('\0', stdout); + } + fflush(stdout); + } else { + for (const std::string& input : inputs) + puts(input.c_str()); + } return 0; } diff --git a/steps/hello-world-graph/libninja.dylib b/steps/hello-world-graph/libninja.dylib new file mode 100755 index 0000000000..3a64d56b6b Binary files /dev/null and b/steps/hello-world-graph/libninja.dylib differ