Ninja file syntax learning

ninja File grammar learning

ninja Is essentially a configuration file , There are no branches , Loop flow control .

grammar

Basic concepts

• edge( edge ):build sentence , You can specify goals (target) Output (output)、 The rules (rule) With the input (input)
• target( The goal is ): The compilation process requires poor students' goals , from build The statement specifies
• output( Output ):build The first half of the statement , yes target Another form of address for
• input( Input ):build The second half of the statement , Used to produce output File or target , Another name is dependency
• rule( The rules ): By designation command With some built-in variables , Decide how to generate output from input
• pool： A group of rule or edge, By specifying its depth, The upper limit of parallelism can be controlled
• scope( Scope )： Action range of variable , Yes rule And build The block level of the statement , There are also file levels .

keyword

• build： Define a edge
• rule： Define a rule
• pool： Define a pool
• default： Specify the default one or more target
• include： Add one ninja File to current scope
• subninja： Add one ninja file , Its scope Different from the current file .
• phony： A built-in special rule , Specifies the name of a non file target

Variable

There are two kinds of variables , Built in variables and custom variables . Both can go through var = str Method definition of , adopt $var or ${var} Method reference of . The only variable type is string .

There are only two built-in variables ：

• builddir : Specify the output directory of some files
• ninja_required_version : Appoint ninja Minimum version of the command

rule
rule name
    command = echo ${in} > ${out}
    var = str

One rule It is through ${in} List of targets entered , Generate ${out} List of output targets
The target is usually a file . For example , There is a built-in special rule phony, You can specify a non file destination .
In addition to being able to customize variables , Include command , ,rule There are also the following variables ：

• command： Define the variables necessary for a rule , Specify the command actually executed
• description：command Explanation , Will replace command In none -v When printing
• generator： After designation , This article rule The generated file will not be cleaned up by default
• in： Space split input list
• in_newline： Newline delimited input list .
• out： Space split output list
• depfile： To specify a Makefile File as an additional explicit dependency .
• deps： Appoint gcc or mscv Method dependency processing
• msvc_deps_prefile： stay deps = msvc Under the circumstances , Specify what needs to be removed msvc Output prefix .
• restat： stay command After execution , If output Timestamp unchanged , It is deemed not to be implemented
• rspfile,rspfile_content： At the same time specified , In execution command front , hold rspfile_content write in rspfile file , Delete after successful execution .

build edge

build foo : phony bar
    var = str

Shaped like the above , Namely build Code block , It is also a part of the compilation process edge. among ,foo Namely output,bar Namely input,: The first position in the back phony Namely rule,var It's a custom variable . stay build In block , Also can be rule Block variables （ make carbon copies ）.
build Examples of complex situations , The code is as follows ：

Gcc = gcc #  Global variables 

# rule
rule name # name yes rule name 
    command = ${Gcc} ${in} > ${out}  #  Carry out orders 
    var = str  #  local variable 
# Edge
# output0 output1  display output 
# output2 output3  Implicit output 
# rule_name  Rule name 
build output0 output1 | output2 output3: rule_name $  
        input0 input1 $      #  Display dependency 
        | input2 input3 $    #  Implicit dependency 
        || input4 input5     # order-only rely on   not essential 
    var0 = str0 
    var1 = str1

among , At the end of the line $ It's the escape character , There is no real new line ; output0 and output1 yes Show （explicit） Output , It will appear in ${out} In the list ; Appear in the | hinder output2 and output3 yes Implicit （implicit） Output , Will not appear in ${out} In the list ; rule_name yes Rule name ; input0 and input1 yes Display dependency （ Input ）, It will appear in ${in} In the list ; Appear in the | hinder input2 and input3 yes Implicit dependency , Will not appear in ${in} In the list ; Appear in the || hinder input4 and input5 yes Implicit order-only rely on , Will not appear in ${in} In the list .
So-called order-only rely on , Literally , It refers to the dependency required only in sequence . At first compilation , It behaves the same as other dependencies ; When you compile again , If input4 or input5 There is a lack of ,ninja Will update them , But will not implement this edge, to update output0 and output1. order-only Dependence , Not really dependent , It's something or nothing 、 Just need to be in the present edge It was just executed before .

pool

pool The meaning of , It is to limit some very hardware resource consuming edge At the same time

pool example
    depth = 2

rule echo_var
    command = echo ${var} >> ${out}
    pool = example

build a : echo_var
    var = a

build b : echo_var
    var = b

build c : echo_var
    var = c

Above code , adopt pool = example, stay rule or build Specify the corresponding edge Of pool by example. because example Of depth = 2, therefore a、b、c Three target Only up to 2 Can be generated at the same time .
at present ,ninja There is only one built-in pool, be known as console. This pool Of depth be equal to 1, Can only be executed at the same time 1 individual edge. It is characterized by , You can directly access stdin、stdout、stderr Three special stream.

A simple ninja example

//test.h
#include<stdio.h>

void print_ninja()
{
    
    printf("this is a ninja_test!\n");
}

//test.c
#include"test.h"

int main(int argc, char *argv[])
{
    
    print_ninja();
    return 0;
}

build.ninja
ninja_required_version = 1.5

GCC = gcc 
cflags = -Wall 

rule rule1 
    command = $GCC -c $cflags -MD -MF $out.d $in -o $out
    description =  compile  $in  Become  $out
    depfile = $out.d
    deps = gcc

build test.o : rule1 test.c

rule link
  command = $GCC $DEFINES $INCLUDES $cflags $in -o $out
  description =  link  $in  Become  $out
build test : link test.o


#  compile all, Is to do tasks build test
build all: phony test 

#  What is compiled by default ( Separate operation ninja)
default all

Terminal print execution ninja, It appears in the directory test.o,test,.ninja_deps,.ninja_log
perform ./test, Successful implementation .

ninja Use

ninja Supported parameters , Use ninja -help You can see ：

--version  #  Print version information 
-v         #  Show all command lines in the build （ This is very useful for the actual build command check ）

-C DIR     #  Before performing the operation , Switch to `DIR` Catalog 
-f FILE    #  To develop `FILE` Input file for building . The default file is `build.ninja`. Such as  ./ninja -f demo.ninja

-j N       #  Parallel execution  N  Homework . Default N=3（ Need corresponding CPU Support ）. Such as  ./ninja -j 2 all
-k N       #  Continue to build until N Until jobs fail . Default N=1
-l N       #  If the average load is greater than N, Do not start a new job 
-n         #  Rehearse （dry run）( Do not execute orders , Regard it as successful . Such as  ./ninja -n -t clean)

-d MODE    #  Turn on debugging mode  ( use  -d list  List all the patterns )
-t TOOL    #  Execute a sub tool ( use  -t list  List all subcommand tools ). Such as  ./ninja -t query all
-w FLAG    #  Control the alarm level 

ninja -d list：

debugging modes:
  stats        print operation counts/timing info  Print Statistics 
  explain      explain what caused a command to execute  Explain why the command is executed 
  keepdepfile  don't delete depfiles after they're read by ninja  Read depfile after , Don't delete it 
  keeprsp      don't delete @response files on success  Read @response after , Don't delete it 
  nostatcache  don't batch stat() calls per directory and cache them  Do not batch process each directory stat() Call and cache them 
multiple modes can be enabled via -d FOO -d BAR  Multi mode calls can be followed by several -d

ninja -t list ( Integrate graphviz Wait for some useful tools for development )

ninja subtools:

    browse        #  Browse the dependency graph in the browser .（ The default will be  8080  Port starts a based on python Of http service ）
    clean         #  Clear the files generated by the build 
    commands      #  List all the commands needed to rebuild and set goals 
    deps          #  Display stored in deps Dependencies in logs 
    graph         #  Generate  graphviz dot  file .
                      Such as  ninja -t graph all |dot -Tpng -o graph.png
    inputs        #  Show all of the target （ recursive ） Input 
    path          #  Find the dependency path between two targets 
    paths         #  Find all dependency paths between two targets 
    query         #  Show a path inputs/outputs
    targets       #  adopt DAG in rule or depth list target
    compdb        # dump JSON Compatible database to standard output 
    recompact     #  Recompact ninja Internal data structure 

Examples of tool use ：

1. Display dependency ： ninja -t deps
2. Show execute command ： ninja -t commands test
3. Show target ： ninja -t targets all
4. Draw dependency graph ：ninja -t graph
   • Turn picture ： ninja -t graph | dot -Tpng -o test.png