github.com/sercand/please@v13.4.0+incompatible/docs/basics.html

    <h1>Please basics</h1>

    <p>If you're familiar with Blaze / Bazel, Buck or Pants you will probably find Please very familiar.
      Otherwise, don't worry, it's not very complicated...</p>

    <h2>BUILD files</h2>
    <p>Please targets are defined in files named BUILD. These are analogous to Makefiles in that they define
      buildable targets for that directory. Fortunately, they do so in a rather nicer syntax.<br/>
      We refer to a directory containing a BUILD file as a <em>package</em>.
    </p>

    <h2>Build targets</h2>
    <p>Each BUILD file can contain a number of <em>build targets</em>. These are units of buildable code
      which can be reused by other build targets. An example is probably worth 1000 words at this point:
      <pre><code>
	  <span class="build-rule">python_library</span>(
	      name = 'my_library',
	      srcs = ['file1.py', 'file2.py'],
	  )

	  <span class="build-rule">python_binary</span>(
	      name = 'my_binary',
	      main = 'my_main.py',
	      deps = [':my_library'],
	  )

	  <span class="build-rule">python_test</span>(
	      name = 'my_library_test',
	      srcs = ['my_library_test.py'],
	      deps = [':my_library'],
	  )
      </code></pre>
      This snippet defines three build targets; a build target is simply a thing that can be built
      by Please and typically appear as a single object in the build file (as the
      <code>python_library</code>, <code>python_binary</code> and <code>python_test</code> are above).
      <ul>
	<li><code>my_library</code> is simply a collection of <code>file1.py</code> and <code>file2.py</code>.<br/>
	  For some languages these might be compiled, for Python of course they're simply made available for other rules.</li>
	<li><code>my_binary</code> creates a deployable Python binary with an entry point in <code>my_main.py</code>.<br/>
	  It also defines a <em>dependency</em> on <code>my_library</code> since it will use it internally.</li>
	<li><code>my_library_test</code> defines a test on <code>my_library</code>. Tests are run by Please and their results
	  are aggregated.</li>
      </ul>
      This illustrates the core points of Please; every rule clearly defines its inputs - its own sources and its dependencies -
      and since these are known Please can be aggressive about parallelising, caching and reusing build artifacts.
    </p>

    <h2>Okay, great, so how do I actually use them?</h2>

    <p>Let's assume the build rules given above are defined in a file in your repo named package/BUILD. You can do the following:
      <ul>
	<li><code>plz build //package:my_library</code> builds the library. This isn't drastically useful on its own, of course...</li>
	<li><code>plz build //package:my_binary</code> builds the binary and all needed libraries that it depends on. That produces a single output file which you could copy
	  to another machine.</li>
	<li><code>plz run //package:my_binary</code> builds and runs the binary immediately.</li>
	<li><code>plz test //package:my_library_test</code> builds and runs the test and shows you the results.</li>
      </ul>
    </p>

    <h2>Build labels</h2>

    <p>That brings us to the topic of <em>build labels</em>, which are identifiers of build targets. As you've just seen,
      these are of the form <code>//package:target</code>, where <code>package</code> is the path from the repo root to that package,
      and <code>target</code> is the name of the target within that package.<br/>
      This is the most common form to identify targets absolutely, but there is also a convenient shorthand where we omit
      the part before the colon (as you saw earlier as well) to refer to a target within the current package.</p>

    <p>The convention is to use <code>lower_case_with_underscores</code> for both package names and target names.<br/>
      This is not just for looks; in many languages (eg. Python) the file path appears within the source files,
      and so it's important to choose something that's a valid lexical identifier.</p>

    <p>There are also some special pseudo-labels:
      <ul>
        <li><code>//mypackage:all</code> refers to all targets in 'mypackage'.</li>
        <li><code>//mypackage/...</code> refers to all targets in 'mypackage' and anywhere beneath it in the filesystem.</li>
      </ul>
      Build targets can't use these as dependencies; these are primarily for using on the command
      line or in the visibility specification for a target.
    </p>

    <h2>What now?</h2>

    <p>Jump in and get started! See the <a href="lexicon.html">please lexicon</a> if you want to see the set of built-in
      build rules for other languages.</p>

    <p>If that all sounds a bit easy so far, try the <a href="intermediate.html">intermediate topics</a> and start
      learning how to program the system and create your own build rules.</p>