github.phpd.cn/thought-machine/please@v12.2.0+incompatible/docs/intermediate.html

    <h1>Intermediate Please</h1>

    <p>Okay, you've read the <a href="basics.html">basics</a>, so what's next?</p>

    <h2>BUILD file format</h2>
    <p>We didn't talk much about the actual format of BUILD files last time, but an astute observer may
      have noticed that the rule invocations look rather like Python. This is not coincidence; BUILD files
      are interpreted as a (slightly) restricted subset of Python.</p>

    <p>So what can you do with them? Well, let's say you want to translate your documentation to a bunch of languages:
      <pre><code>
	  for language in ['en_NZ', 'en_GB', 'it_IT', 'es_MX', 'el_GR']:
	      genrule(
	          name = 'txt_documentation_' + language,
	          srcs = ['docs.txt'],
	          outs = ['docs_%s.txt' % language],
	          cmd = 'cat $SRC | $(exe //tools:translate_tool) --language %s > $OUT' % language,
	      )

	      genrule(
	          name = 'documentation_' + language,
	          srcs = [':txt_documentation_' + language],
                  outs = ['docs_%s.html' % language],
                  cmd = '$(exe //tools:html_doc_tool) --src $SRC --out $OUT',
	          visibility = ['PUBLIC'],
          )
      </code></pre>

      Obviously this would be a bit repetitive if you redefined the rules separately for each language. Instead, we can take
      advantage of the build language to genericise them across languages; for each language we translate it and then
      format it as HTML.
    </p>

    <h2>Custom build rules</h2>

    <p>While the above is perfectly readable, having to define two rules each time is a bit tedious;
      maybe we'd rather define one rule to perform the translation & HTML conversion in one pass.

      <b>docs/documentation_rules.build_defs:</b><br/>
      <pre><code>
	  def create_html_docs(name, language, srcs, visibility=None):
	      """Converts documentation to the given language and then to HTML."""
	      genrule(
	          name = '_%s_%s#translate' % (name, language),
	          srcs=srcs,
                  outs = ['_%s_%s_translated.txt' % (name, language)],
	          cmd = 'cat $SRC | $(exe //tools:translate_tool) --language %s > $OUT' % language,
	      )
	      genrule(
	          name = '%s_%s' % (name, language),
	          srcs = [':_%s_%s#translate' % (name, language)],
                  outs = ['%s_%s.html' % (name, language)],
                  cmd = '$(exe //tools:html_doc_tool) --src $SRC --out $OUT',
	          visibility = ['PUBLIC'],
              )
      </code></pre>
      <b>docs/BUILD:</b><br/>
      <pre><code>
	  include_defs('//docs/documentation_rules.build_defs')
	  for language in ['en_NZ', 'en_GB', 'it_IT', 'es_MX', 'el_GR']:
	      create_html_docs(
	          name = 'docs',
	          language = language,
	          srcs = ['docs.txt'],
                  visibility = ['PUBLIC'],
              )
      </code></pre>
    </p>

    <p>This example is getting a little strained, but serves to illustrate how you can create something that acts
      like a single build rule, but internally creates multiple steps to produce the final result. Since the BUILD
      files are essentially Python it's as simple as defining a function.</p>

    <p>Note the microformat of defining 'internal' private rules with a leading underscore and trailing hashtag;
      in the interactive build mode those will be omitted to make it appear to users as though they're building
      the rule they defined by name, even though internally it's split into multiple rules.</p>

    <h2>Transitive dependencies</h2>

    <p>Writing some rules requires that the transitive set of dependencies are available when they're built.</p>

    <p>For example, consider <code>cc_binary</code>; all your <code>cc_library</code> rules have created a bunch of .o files,
      but each of those only has its own set of symbols. The final binary rule must link all of them together to produce
      a working executable.</p>

    <p>Fortunately, this is pretty easy in Please. You can apply <code>needs_transitive_deps = True</code> to a
      <code>genrule</code> to make them all available at build time. This is easy to do but of course shouldn't be taken
      lightly since it will slow the rule down (needs more time to prepare sources) and may harm incrementality.<br/>
      The typical pattern is that <code>_library</code> rules don't need this but <code>_binary</code> and <code>_test</code>
      rules do, although this is somewhat dependent on the language.</p>

    <h2>gentest</h2>

    <p><code>gentest</code> is similar to <code>genrule</code> but defines a target that runs an arbitrary test. The
      <code>test_cmd</code> attribute defines the command to run; this is often simply <code>$(exe :rule_name)</code>
      to run its own output.</p>

    <p>The protocol for tests to follow is pretty simple; the test command should return zero on success or nonzero
      for failure (Unix FTW). The test should also write either a file called <code>test.results</code> or multiple files
      into a directory named the same; these are parsed as one of the formats Please understands (currently either
      xUnit XML or Go's test output format). Optionally a test can be marked with <code>no_test_output = True</code>
      to indicate that it writes no files, in which case its return value is the only indicator of success.</p>

    <h2>Labels</h2>

    <p>Rules, particularly the various <code>_test</code> rules can have an optional set of <em>labels</em> associated with
      them. These are essentially just a set of tags that can be used to filter them when run via <code>plz test</code>,
      for example <code>plz test ... --include py</code> will run all your tests labelled with 'py',
      and <code>plz test ... --exclude slow</code> will run all your tests except those labelled with 'slow'.</p>

    <p>The syntax looks like:
      <pre><code>
        go_test(
            name = 'my_test',
            srcs = ['my_test.go'],
            labels = ['slow', 'integration'],
        )
      </code></pre>
    </p>

    <p>There is one special label, <code>manual</code> which always excludes tests from autodetection when being run with
      <code>plz test //mypackage:all</code> or <code>plz test //mypackage/...</code>. This is often useful to disable tests
      from general usage if needed (for example, if a test starts failing, you can disable it while investigating).</p>

    <h2>Flaky tests</h2>

    <p>Tests can be marked as <em>flaky</em> which causes them to be automatically re-run several times. They are considered
      to pass if any one run passes.</p>

    <p>The syntax looks like:
      <pre><code>
        go_test(
            name = 'my_test',
            srcs = ['my_test.go'],
            flaky = True,
        )
      </code></pre>
      By default they are run three times, you can alter this on a per-test basis by passing an integer instead of a boolean.
    </p>

    <p>The <code>--max_flakes</code> flag can be used to cap the number of re-runs allowed on a single invocation.</p>

    <h2>Containerised tests</h2>

    <p>Tests can also be marked as <em>containerised</em> so they are isolated within a container for the duration of their run.
      One main advantage of this is for integration tests that need to open ports and start servers, which are then insulated
      from port clashes against one another.</p>

    <p>Within the container the test will have access only to the data it's declared it needs at runtime, so you will have
      to be correct about declaring all such dependencies (but of course one would do that anyway...).</p>

    <p>The syntax looks like:
      <pre><code>
        go_test(
            name = 'my_test',
            srcs = ['my_test.go'],
            container = True,
        )
      </code></pre>
    </p>

    <p>Currently we support Docker as a container format, we plan to support rkt containers in a future release.</p>

    <h2>build_rule</h2>

    <p><code>build_rule</code> is the fundamental unit all other build rules are built from. We discussed <code>genrule</code>
      just now which is very similar; <code>build_rule</code> allows control over more esoteric features of the system.</p>

    <p>The difference between <code>genrule</code> and <code>build_rule</code> from a user's perspective is pretty arbitrary;
      conventionally we use <code>genrule</code> in build files for defining arbitrary build transformations and
      <code>build_rule</code> for defining other rules, but there's no particularly principled reason for this.</p>

    <h2>What else?</h2>

    <p>If you're still curious about what more can be done, try <a href="advanced.html">the advanced stuff</a>.</p>