github.com/sercand/please@v13.4.0+incompatible/docs/lexicon.html (about) 1 <h1>The Lexicon of Please</h1> 2 3 <p>This is the reference for the complete set of builtin rules & functions.</p> 4 5 <ul> 6 <li><a href="#builtins">Builtin rules and functions</a></li> 7 <li><a href="#cc">C and C++ rules</a></li> 8 <li><a href="#go">Go rules</a></li> 9 <li><a href="#java">Java rules</a></li> 10 <li><a href="#misc">Miscellaneous rules</a></li> 11 <li><a href="#proto">Protocol buffer rules</a></li> 12 <li><a href="#python">Python rules</a></li> 13 <li><a href="#sh">Shell rules</a></li> 14 <li><a href="#subrepo">Subrepo rules</a></li> 15 </ul> 16 17 <h2><a name="builtins">Builtin functions</a></h2> 18 19 <h3><a name="subinclude">subinclude</a></h3> 20 21 <p><pre class="rule"><code>subinclude(target)</code></pre></p> 22 23 <p>Includes the output of a build target as extra rules in this one.</p> 24 25 <p>This is the closest equivalent to <code>import</code> in the BUILD language. It behaves 26 somewhat differently though in that the contents of the subincluded file are added to the 27 globals of the current module so can be called directly.</p> 28 29 <p>The target that you attempt to subinclude is simply a normal build target, with the 30 restriction that it must have exactly one output. The simplest form of this is a single-file 31 <a href="#filegroup">filegroup</a> or <a href="export_file">export_file</a> rule, but 32 it is possible to have more complex rules generating your BUILD definitions.</p> 33 34 <p>For example: 35 36 <pre><code>subinclude('//build_defs:my_build_rules')</code></pre> 37 </p> 38 39 <h3><a name="glob">glob</a></h3> 40 41 <p><pre class="rule"><code>glob(include, exclude=None, hidden=False)</code></pre></p> 42 43 <p>Matches all filenames by a pattern, in a manner reminiscent of shell-style pattern 44 expansion or Python's builtin <a href="https://docs.python.org/3/library/glob.html">glob</a> 45 module.</p> 46 47 <p>Note that the only expansion patterns accepted are <code>*</code> to match an arbitrary 48 number of non-separator characters (i.e. not <code>/</code>), and <code>**</code> to 49 match any number of <b>complete</b> path components.<br/> 50 These are often referred to as "Ant-style" patterns since Ant introduced them.</p> 51 52 <p>It bears noting that you cannot glob generated files, only source files. Also glob will not 53 descend into any directories that contain a BUILD file; this maintains an invariant that 54 each file is owned by exactly one package (or potentially none, but then Please doesn't know 55 or care about them). If you want to pull in files from another package, export them there 56 using a <a href="#filegroup"><code>filegroup</code></a> and depend on that in the package 57 you want it.</p> 58 59 <table> 60 <thead> 61 <tr> 62 <th>Argument</th> 63 <th>Default</th> 64 <th>Type</th> 65 <th></th> 66 </tr> 67 </thead> 68 <tbody> 69 70 <tr> 71 <td>include</td> 72 <td></td> 73 <td>list</td> 74 <td>List of paths to include. Each is globbed separately.</td> 75 </tr> 76 77 <tr> 78 <td>exclude</td> 79 <td>None</td> 80 <td>list</td> 81 <td>List of filenames to exclude from any patterns matched by <code>includes</code>.<br/> 82 These are subject to glob expansion of <code>*</code> themselves, but 83 <code>**</code> is <b>not</b> expanded (although since these are applied to each file found 84 individually, it's not necessary).</td> 85 </tr> 86 87 <tr> 88 <td>hidden</td> 89 <td>False</td> 90 <td>bool</td> 91 <td>Set to True to include hidden files / folders.</td> 92 </tr> 93 94 </tbody> 95 </table> 96 97 <h3><a name="get_labels">get_labels</a></h3> 98 99 <p><pre class="rule"><code>get_labels(target, prefix)</code></pre></p> 100 101 <p>Gets the unique set of labels for a rule and all its transitive dependencies.</p> 102 103 <p>Two formats are accepted for target: the first is a string containing just the target name, 104 which is resolved in the current package. This facilitates calling them from a pre-build 105 function, which is in fact the only time it's safe to call this way.<br/> 106 The other is a full build target, which should be a transitive dependency of the target 107 whose pre/post build function you're in. If the target isn't built when you ask for the 108 labels the build will terminate.<br/> 109 In either case this is only safe to call from a pre / post-build function and should 110 never be called at initial parse time, because at that point you generally don't have 111 the full set of labels available yet.</p> 112 113 <p>Uses for this are normally fairly language-specific. The clearest example is maybe the 114 builtin Python rules, where <code>python_binary</code> and <code>python_test</code> use 115 this to identify if any of their dependencies have marked them as not being zip-safe.</p> 116 117 <table> 118 <thead> 119 <tr> 120 <th>Argument</th> 121 <th>Default</th> 122 <th>Type</th> 123 <th></th> 124 </tr> 125 </thead> 126 <tbody> 127 128 <tr> 129 <td>target</td> 130 <td></td> 131 <td>str</td> 132 <td>Label of the target to get labels for.</td> 133 </tr> 134 135 <tr> 136 <td>prefix</td> 137 <td>None</td> 138 <td>str</td> 139 <td>Filters the returned labels to only ones starting with this prefix.</td> 140 </tr> 141 142 </tbody> 143 </table> 144 145 <h3><a name="has_label">has_label</a></h3> 146 147 <p><pre class="rule"><code>has_label(target, prefix)</code></pre></p> 148 149 <p>Returns True if the target has any matching label that would be returned by get_labels.</p> 150 151 <table> 152 <thead> 153 <tr> 154 <th>Argument</th> 155 <th>Default</th> 156 <th>Type</th> 157 <th></th> 158 </tr> 159 </thead> 160 <tbody> 161 162 <tr> 163 <td>target</td> 164 <td></td> 165 <td>str</td> 166 <td>Label of the target to get labels for.</td> 167 </tr> 168 169 <tr> 170 <td>prefix</td> 171 <td>None</td> 172 <td>str</td> 173 <td>Checks only labels that start with this prefix.</td> 174 </tr> 175 176 </tbody> 177 </table> 178 179 <h3><a name="package">package</a></h3> 180 181 <p><pre class="rule"><code>package(...)</code></pre></p> 182 183 <p>Defines settings affecting the current package - for example, default visibility.</p> 184 185 <p>With this you can override any current value in <code>CONFIG</code> by name for all 186 subsequent targets in the current package. Only existing values can be replaced.</p> 187 188 <p>There are also a couple of special values which aren't normally in <code>CONFIG</code>: 189 <code>default_licences</code> and <code>default_visibility</code>. As the names suggest 190 these set defaults for those attributes for all following targets that don't set them.</p> 191 192 <p>This function must be called <b>before</b> any targets are defined.</p> 193 194 <h3><a name="log">log</a></h3> 195 196 <p><pre class="rule"><code>log.warning(message, [args...])</code></pre></p> 197 198 <p>Logs an arbitrary message at some given level. The available levels, from most quiet 199 to most severe, are: 200 <ul> 201 <li><code>log.debug</code></li> 202 <li><code>log.info</code></li> 203 <li><code>log.notice</code></li> 204 <li><code>log.warning</code></li> 205 <li><code>log.error</code></li> 206 <li><code>log.fatal</code></li> 207 </ul> 208 These correspond to Please's built in messages and are controlled as usual by the 209 <code>-v</code> command-line argument.</p> 210 211 <p>As the name suggests, <code>log.fatal</code> immediately terminates the program with 212 a fatal error. The others have no side effect other than showing the message.</p> 213 214 <p>The message and arguments together are interpolated like Python's normal string 215 interpolation, similar to the builtin <code>logging</code> package.</p> 216 217 <h3><a name="decompose">decompose</a></h3> 218 219 <p><pre class="rule"><code>decompose(label)</code></pre></p> 220 221 <p>Decomposes a build label into the package and name parts.</p> 222 223 <p>Consider carefully when you should use this - command replacements may be more appropriate.<br/> 224 Most rules should be able to accept labels without having to know anything about their structure.</p> 225 226 <p>The input label can be given in either relative or absolute form. It will fail with an error 227 if it's not a structurally valid label.</p> 228 229 <h3><a name="canonicalise">canonicalise</a></h3> 230 231 <p><pre class="rule"><code>canonicalise(label)</code></pre></p> 232 233 <p>Converts the given build label to its full form.</p> 234 235 <p>For example: 236 <ul> 237 <li><code>//package:target</code> -> <code>//package:target</code></li> 238 <li><code>//package</code> -> <code>//package:package</code></li> 239 <li><code>:target</code> -> <code>//current_package:target</code></li> 240 </ul> 241 </p> 242 243 244 <h2><a name="cc">C and C++ rules</a></h2> 245 246 <p>Rules to build C and C++ targets.</p> 247 <p>The process of building C or C++ code is fairly complex so while these rules do their best 248 to keep things reasonably simple, there's a lot of scope for things going wrong.</p> 249 <p>There is very little difference between the <code>c_</code> and <code>cc_</code> variants 250 of each rule, in nearly all cases they simply use different tools and flags in the 251 <a href="config.html#cpp">relevant config section</a>.</p> 252 253 {{ template "lexicon_entry.html" .Named "c_library" }} 254 {{ template "lexicon_entry.html" .Named "c_static_library" }} 255 {{ template "lexicon_entry.html" .Named "c_shared_object" }} 256 {{ template "lexicon_entry.html" .Named "c_binary" }} 257 {{ template "lexicon_entry.html" .Named "c_test" }} 258 {{ template "lexicon_entry.html" .Named "c_embed_binary" }} 259 260 261 <h2><a name="go">Go rules</a></h2> 262 263 <p>Rules to build Go code.</p> 264 <p>Go has a strong built-in concept of packages so while it's not 100% required to strictly 265 keep to 1 package per dir as in classic Go, it's still probably a good idea to match Please 266 rules to Go packages.</p> 267 268 {{ template "lexicon_entry.html" .Named "go_library" }} 269 {{ template "lexicon_entry.html" .Named "cgo_library" }} 270 {{ template "lexicon_entry.html" .Named "go_binary" }} 271 {{ template "lexicon_entry.html" .Named "go_test" }} 272 {{ template "lexicon_entry.html" .Named "cgo_test" }} 273 {{ template "lexicon_entry.html" .Named "go_get" }} 274 275 276 <h2><a name="java">Java rules</a></h2> 277 278 <p>Built-in rules to compile Java code.</p> 279 280 {{ template "lexicon_entry.html" .Named "java_library" }} 281 {{ template "lexicon_entry.html" .Named "java_module" }} 282 {{ template "lexicon_entry.html" .Named "java_binary" }} 283 {{ template "lexicon_entry.html" .Named "java_runtime_image" }} 284 {{ template "lexicon_entry.html" .Named "java_test" }} 285 {{ template "lexicon_entry.html" .Named "maven_jar" }} 286 {{ template "lexicon_entry.html" .Named "maven_jars" }} 287 288 289 <h2><a name="misc">Misc rules</a></h2> 290 291 <p>Miscellaneous rules that aren't language-specific.</p> 292 293 {{ template "lexicon_entry.html" .Named "genrule" }} 294 {{ template "lexicon_entry.html" .Named "gentest" }} 295 {{ template "lexicon_entry.html" .Named "export_file" }} 296 {{ template "lexicon_entry.html" .Named "filegroup" }} 297 {{ template "lexicon_entry.html" .Named "hash_filegroup" }} 298 {{ template "lexicon_entry.html" .Named "system_library" }} 299 {{ template "lexicon_entry.html" .Named "remote_file" }} 300 {{ template "lexicon_entry.html" .Named "tarball" }} 301 302 <h3><a name="git_branch">git_branch</a></h3> 303 304 <p><pre class="rule"><code>git_branch(<span class="optional">short:bool=True</span>)</code></pre></p> 305 306 <p>Calls <code>git symbolic-ref -q HEAD</code> and returns the 307 corresponding git branch. If <code>short</code> is false, show the full 308 symbolic ref for a branch.</p> 309 310 <table> 311 <thead> 312 <tr> 313 <th>Argument</th> 314 <th>Default</th> 315 <th>Type</th> 316 <th></th> 317 </tr> 318 </thead> 319 <tbody> 320 321 <tr> 322 <td>short</td> 323 <td>True</td> 324 <td>bool</td> 325 <td>Uses the shortened symbolic ref for a branch.</td> 326 </tr> 327 328 </tbody> 329 </table> 330 331 <h3><a name="git_commit">git_commit</a></h3> 332 333 <p><pre class="rule"><code>git_commit()</code></pre></p> 334 335 <p>Calls <code>git rev-parse HEAD</code> and returns the corresponding git 336 commit SHA. To return a shortened commit 337 use <code>git_commit()[0:8]</code>.</p> 338 339 <h3><a name="git_show">git_show</a></h3> 340 341 <p><pre class="rule"><code>git_show(<span class="optional">format:str</span>)</code></pre></p> 342 343 <p>Calls <code>git show -s --format={format}</code> and returns the 344 result. <code>format</code> is limited to a subset of values accepted 345 by <code>git show</code>.</p> 346 347 <table> 348 <thead> 349 <tr> 350 <th>Argument</th> 351 <th>Default</th> 352 <th>Type</th> 353 <th></th> 354 </tr> 355 </thead> 356 <tbody> 357 358 <tr> 359 <td>format</td> 360 <td></td> 361 <td>str</td> 362 <td>String format passed to <code>git show</code>.</td> 363 </tr> 364 365 </tbody> 366 </table> 367 368 <p>Supported format verbs are limited to: 369 <ul> 370 <li><code>%H</code> commit hash</li> 371 <li><code>%T</code> tree hash</li> 372 <li><code>%P</code> parent hashes</li> 373 <li><code>%an</code> author name</li> 374 <li><code>%ae</code> author email</li> 375 <li><code>%at</code> author date, UNIX timestamp</li> 376 <li><code>%cn</code> committer name</li> 377 <li><code>%ce</code> committer email</li> 378 <li><code>%ct</code> committer date, UNIX timestamp</li> 379 <li><code>%D</code> ref names</li> 380 <li><code>%e</code> encoding</li> 381 <li><code>%s</code> subject of commit message</li> 382 <li><code>%f</code> sanitized subject line, suitable for a filename</li> 383 <li><code>%b</code> body of commit message</li> 384 <li><code>%B</code> raw body (unwrapped subject and body)</li> 385 <li><code>%N</code> commit notes</li> 386 <li><code>%GG</code> raw verification message from GPG for a signed commit</li> 387 <li><code>%G?</code> show "G" for a good (valid) signature, "B" for a bad signature, "U" for a good signature with unknown validity, "X" for a good signature that has expired, "Y" for a good signature made by an expired key, "R" for a good signature made by a revoked key, "E" if the signature cannot be checked (e.g. missing key) and "N" for no signature</li> 388 <li><code>%GS</code> show the name of the signer for a signed commit</li> 389 <li><code>%GK</code> show the key used to sign a signed commit</li> 390 <li><code>%n</code> newline</li> 391 <li><code>%%</code> a raw %</li> 392 </ul> 393 </p> 394 395 396 <h3><a name="git_state">git_state</a></h3> 397 398 <p><pre class="rule"><code>git_state(<span class="optional">clean_label:str="clean", dirty_label:str="dirty"</span>)</code></pre></p> 399 400 <p>Calls <code>git status --porcelain</code> and returns the 401 corresponding string. If the repository is clean, the string set 402 in <code>clean_label</code> is returned. If the repository is dirty, the 403 string set in <code>dirty_label</code> is returned.</p> 404 405 <table> 406 <thead> 407 <tr> 408 <th>Argument</th> 409 <th>Default</th> 410 <th>Type</th> 411 <th></th> 412 </tr> 413 </thead> 414 <tbody> 415 416 <tr> 417 <td>clean_label</td> 418 <td>clean</td> 419 <td>str</td> 420 <td>String returned if the repository is clean.</td> 421 </tr> 422 423 <tr> 424 <td>dirty_label</td> 425 <td>dirty</td> 426 <td>str</td> 427 <td>String returned if the repository is dirty.</td> 428 </tr> 429 430 </tbody> 431 </table> 432 433 434 <h2><a name="proto">Proto rules</a></h2> 435 436 <p>Build rules for compiling protocol buffers & gRPC service stubs.</p> 437 <p>Note that these are some of the most complex of our built-in build rules, 438 because of their cross-language nature. Each proto_library rule declares a set of 439 sub-rules to run protoc & the appropriate java_library, go_library rules etc. Users 440 shouldn't worry about those sub-rules and just declare a dependency directly on 441 the proto_library rule to get its appropriate outputs.</p> 442 443 {{ template "lexicon_entry.html" .Named "proto_library" }} 444 {{ template "lexicon_entry.html" .Named "grpc_library" }} 445 446 447 <h2><a name="python">Python rules</a></h2> 448 449 <p>Rules to build Python code.</p> 450 <p>The output artifacts for Python rules are .zip files similar to 451 <a href="https://github.com/pantsbuild/pex">.pex</a> files (and are suffixed as such).</p> 452 <p>This combines all the in-repo dependencies into a single file that can be deployed and run 453 on any system that has a suitable Python interpreter. Please optimises this process to 454 improve incrementality and includes some hooks to make running from a zipfile as transparent 455 as possible; nonetheless certain file-based operations may not work since there is not a 456 real file system available. If necessary various Python rules can be annotated with 457 <code>zip_safe</code> to control this; if a binary is zip-unsafe it will extract itself before 458 running.</p> 459 460 {{ template "lexicon_entry.html" .Named "python_library" }} 461 {{ template "lexicon_entry.html" .Named "python_binary" }} 462 {{ template "lexicon_entry.html" .Named "python_test" }} 463 {{ template "lexicon_entry.html" .Named "pip_library" }} 464 {{ template "lexicon_entry.html" .Named "python_wheel" }} 465 466 467 <h2><a name="sh">Shell rules</a></h2> 468 469 <p>Rules to 'build' shell scripts.</p> 470 <p>Note that these do pretty much nothing beyond collecting the files. In future we might 471 implement something more advanced (ala .sar files or whatever).</p> 472 473 {{ template "lexicon_entry.html" .Named "sh_library" }} 474 {{ template "lexicon_entry.html" .Named "sh_binary" }} 475 {{ template "lexicon_entry.html" .Named "sh_cmd" }} 476 {{ template "lexicon_entry.html" .Named "sh_test" }} 477 478 479 <h2><a name="subrepo">Subrepo rules</a></h2> 480 481 <p>Rules for defining subrepos. See <a href="subrepos.html">the docs</a> for more information 482 on subrepos in general.</p> 483 484 {{ template "lexicon_entry.html" .Named "http_archive" }} 485 {{ template "lexicon_entry.html" .Named "new_http_archive" }}