begriffs open source - cmsis-freertos/blob - Test/litani/doc/src/man/litani-add-job.scdoc

   1 litani-add-job(1) "" "Litani Build System"
   2
   3 ; Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
   4
   5 ; Licensed under the Apache License, Version 2.0 (the "License").
   6 ; You may not use this file except in compliance with the License.
   7 ; A copy of the License is located at
   8
   9 ;     http://www.apache.org/licenses/LICENSE-2.0
  10
  11 ; or in the "license" file accompanying this file. This file is distributed
  12 ; on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
  13 ; express or implied. See the License for the specific language governing
  14 ; permissions and limitations under the License.
  15
  16
  17 # NAME
  18
  19 litani add-job - Add a single command with its dependencies
  20
  21 # SYNOPSIS
  22
  23 *litani add-job --command* _C_ *--pipeline-name* _P_ *--ci-stage*
  24 <_build_|_test_|_report_>
  25         \[*--inputs* _F_ [_F_ ...]]
  26         \[*--outputs* _F_ [_F_ ...]]
  27         \[*--phony-outputs* [_F_ ...]]
  28         \[*--description* _D_]
  29         \[*--tags* _T_ [_T_ ...]]
  30         \[*--cwd* _D_]
  31         \[*--ok-returns* _RC_ [_RC_ ...]]
  32         \[*--ignore-returns* _RC_ [_RC_ ...]]
  33         \[*--timeout* _N_]
  34         \[*--timeout-ok*]
  35         \[*--timeout-ignore*]
  36         \[*--interleave-stdout-stderr*]
  37         \[*--outcome-table* _F.json_]
  38         \[*--stdout-file* _F_]
  39         \[*--stderr-file* _F_]
  40         \[*--pool* _P_]
  41         \[*--profile-memory*]
  42         \[*--profile-memory-interval* _N_]
  43
  44
  45 # DESCRIPTION
  46
  47 This program adds a job to an existing Litani run. The run must have been
  48 previously created with *litani-init(1)*; you may add as many jobs as you need before
  49 running them with *litani-run-build(1)*.
  50
  51 A _job_ is a command that is part of a dependency graph. Litani runs the command
  52 if any of the job's inputs were out-of-date; once the inputs have been made
  53 up-to-date, Litani runs the job, which thereby makes the job's outputs
  54 up-to-date.
  55
  56 By repeatedly running *litani add-job*, you build up a dependency graph where
  57 jobs are connected by their inputs and outputs. Running *litani run-build* makes
  58 Litani run all of the jobs in the dependency graph that are needed to bring all
  59 inputs and outputs up-to-date.
  60
  61 Many of the flags to this command give you platform-portable control on various
  62 aspects of the program: timeouts, dealing with return codes, output streams, and
  63 more.
  64
  65
  66 # MULTIPROCESS SAFETY
  67
  68 It is safe to run multiple invocations of *litani add-job* in parallel.
  69 Having a configure script that can run multiple invocations of *litani
  70 add-job* from a thread pool (or similar) is recommended to decrease
  71 configure times.
  72
  73
  74 # OPTIONS
  75
  76 *--command* _CMD_
  77         The command that Litani will execute to emit the output files (if any) from
  78         the input files, once the input files are up-to-date. Litani invokes _CMD_
  79         through a subshell, so wildcards and shell expansions are supported and
  80         special characters must be escaped.
  81
  82 *--inputs* _F_ [_F_ ...]
  83         A list of inputs that this job depends on. Litani interprets each _F_ as a file:
  84         - If every _F_ exists and has an older timestamp than all of this job's
  85           outputs, then Litani will not run this job.
  86         - If some of the _F_ are newer than any of this job's outputs, then those
  87           outputs are called 'out-of-date'. In this case, Litani will run all of the
  88           jobs whose outputs include every _F_ that is out of date before running this
  89           job.
  90         - If option 2 applies, but there is no job whose output includes the
  91           out-of-date files, then the build will fail.
  92
  93 *--outputs* _F_ [_F_ ...]
  94         A list of outputs that this job emits. Litani interprets each _F_ as a file,
  95         and expects that the command will write a file with that name upon completion.
  96         If a job _J_ has _F_ as an output, but does not actually write a file called
  97         _F_, then _J_ will run unconditionally because _F_ will always be considered
  98         out of date. Furthermore, all jobs whose inputs include _F_, and all their
  99         descendants, will also always run.
 100
 101 *--phony-outputs* [_OUT_ ...]
 102         Do not print a warning if this job has not written the named _OUT_ files by
 103         the time it finishes running. If you do not specify any _OUT_ files, Litani
 104         will not warn when _any_ output specified to the *--outputs* flag does not
 105         exist when the job has finished running.
 106
 107         This is useful when you want to create a dependency ordering between two jobs,
 108         but the first job does not write any output files that the second job can
 109         depend on. To achieve this, you could pass *--outputs phony-file* when adding
 110         the first job, and *--inputs phony-file* when adding the second job. However,
 111         Litani will print a warning if the first job exits without writing a file
 112         called _phony-file_. To suppress the warning, instead pass *--phony-outputs
 113         phony-file* when adding the first job. Doing this obviates the need to use
 114         touchfiles for dependency ordering, which is how this must be done when using
 115         a traditional build system like *make(1)*.
 116
 117 *--description* _D_
 118         A human-readable description for this job. This flag is optional but highly
 119         recommended, as it makes the HTML dashboard much easier to navigate.
 120
 121 *--tags* _TAG_ [_TAG_ ...]
 122         A list of tags for this job. Litani does not interpret tags (although the HTML
 123         dashboard generator does use some of them). Each tag can be in whatever format
 124         you prefer, e.g. a plain string, key-value pair, or even arbitrary JSON. A
 125         job's list of tags is included in its _run.json_ and is intended to help with
 126         analyzing run data.
 127
 128 *--pipeline-name* _P_
 129         The 'pipeline' that this job is part of. A pipeline is a subgraph of the
 130         overall build, representing a single 'end-to-end' set of related jobs. A job's
 131         pipeline does not affect how it is scheduled to run, but is used for grouping
 132         related jobs in the HTML dashboard.
 133
 134 *--ci-stage* <_build_|_test_|_report_>
 135         The 'CI stage' that this job is part of. A CI stage is a subgraph of the
 136         overall build, representing a set of jobs that should complete before Litani
 137         moves onto the next stage. A job's CI stage does not affect how it is
 138         scheduled to run, but it is used for grouping related jobs in the HTML dashboard.
 139
 140 *--cwd* _DIR_
 141         The directory that this job should execute in.
 142
 143 *--ok-returns* _RC_ [_RC_ ...]
 144         Set the job outcome to _success_ if the command exits with a return code of
 145         _RC_. By default, a job is only considered successful if it returns with _0_.
 146         You can also use the *--outcome-table* option for fine-grained control over
 147         job outcomes.
 148
 149 *--ignore-returns* _RC_ [_RC_ ...]
 150         Set the job outcome to _fail_ignore_ if the command exits with a return code
 151         of _RC_. This means that jobs that depend on this one will still run as if
 152         this job had passed, but the pipeline that contains this job will fail after
 153         it completes.  This is useful when you want to generate a report even when a
 154         command fails; you specify the report as a dependency of the command, and use
 155         *--ignore-returns* to ensure that the report command runs even if the job
 156         fails. You can also use the *--outcome-table* option for fine-grained control
 157         over job outcomes.
 158
 159 *--timeout* _N_
 160         How many seconds this job should be allowed to run for. If the timeout is
 161         reached, then the command is killed with _SIGTERM_ followed by _SIGKILL_ (see
 162         *signal*(3)) and the _timeout_reached_ key of the job's record is set to _true_.
 163         By default, the job also fails if the timeout is reached, though this behavior
 164         can be modified using *--timeout-ok*, *--timeout-ignore*, and *--outcome-table*.
 165
 166 *--timeout-ok*
 167         Set the job outcome to _success_ if it reaches the timeout specified in the
 168         *--timeout* flag.
 169
 170 *--timeout-ignore*
 171         Set the job outcome to _fail_ignore_ if it reaches the timeout specified in the
 172         *--timeout* flag. This means that jobs that depend on this one will still run
 173         as if this job had passed, but the pipeline that contains this job will fail
 174         after it completes.
 175
 176 *--outcome-table* _F_
 177         Use the JSON-formatted outcome table _F_ to determine the outcome (_success_,
 178         _fail_, _fail-ignored_) of this job. Using outcome tables gives finer-grained
 179         control over outcomes than using the _--_..._-ok_ and _--_..._-ignore_ flags:
 180         in particular, it is possible to specify an action other than _success_ if the
 181         underlying *command* returns 0. This can be used, for example, to define
 182         negative tests. The schema for JSON outcome tables is specified in
 183         *litani-outcome-table.json(5)*.
 184
 185 *--interleave-stdout-stderr*
 186         Use a single pipe for the job's stdout and stderr. Similar to redirecting
 187         stderr to stdout using _2>&1 >..._. The job's _stdout_ list in the _run.json_
 188         file will contain lines of output from both stdout and stderr, while the value
 189         of _stderr_ will be _null_.
 190
 191 *--stdout-file* _F_
 192         Redirect the command's stdout to _F_. Litani will still retain a copy of the
 193         output in the _stdout_ field of the _run.json_ file. This flag is a useful
 194         alternative to using shell redirection (_>_).
 195
 196 *--stderr-file* _F_
 197         Redirect the command's stderr to _F_. Litani will still retain a copy of the
 198         output in the _stderr_ field of the _run.json_ file. This flag is a useful
 199         alternative to using shell redirection (_2>_).
 200
 201 *--pool* _P_
 202         Place this job in the pool named _P_. This pool must have been declared using
 203         the *--pools* flag of *litani init*. If pool _P_ has a depth of _D_, that
 204         means that a maximum of _D_ jobs whose pool is _P_ will be running in
 205         parallel (though there may be other jobs in other pools that are also running
 206         at the same time).
 207
 208 *--profile-memory*
 209         Turn on memory profiling for this job. The memory used by the command will be
 210         recorded in the _memory_trace_ field of _run.json_.
 211
 212         The memory usage will also be included on a graph on the HTML dashboard if
 213         this job's tags include a "stats group". For each string _G_, all jobs that
 214         are tagged with "_stats-group:G_" and that have enabled memory profiling will
 215         be included on a graph comparing memory usage amongst those jobs. Different
 216         values for _G_ are intended to group different types of jobs. For example, you
 217         might tag all the compilation jobs with _stats-group:compilation_ and all the
 218         test jobs with _stats-group:test_. This will result in two graphs on the HTML
 219         dasahboard, each one depicting the memory usage of the compilation and test
 220         jobs respectively.
 221
 222 *--profile-memory-interval* _N_
 223         Profiles the memory usage of this job every _N_ seconds. Has no effect unless
 224         *--profile-memory* is also passed.
 225
 226
 227 # ENVIRONMENT VARIABLES
 228
 229 *LITANI_JOB_ID*
 230         Litani passes the job's unique ID to the command through this environment variable.
 231         The unique id is the _job\_id_ field in the *litani-run.json(5)* representation.