github.phpd.cn/thought-machine/please@v12.2.0+incompatible/docs/basics.html (about)

     1  
     2      <h1>Please basics</h1>
     3  
     4      <p>If you're familiar with Blaze / Bazel, Buck or Pants you will probably find Please very familiar.
     5        Otherwise, don't worry, it's not very complicated...</p>
     6  
     7      <h2>BUILD files</h2>
     8      <p>Please targets are defined in files named BUILD. These are analogous to Makefiles in that they define
     9        buildable targets for that directory. Fortunately, they do so in a rather nicer syntax.<br/>
    10        We refer to a directory containing a BUILD file as a <em>package</em>.
    11      </p>
    12  
    13      <h2>Build targets</h2>
    14      <p>Each BUILD file can contain a number of <em>build targets</em>. These are units of buildable code
    15        which can be reused by other build targets. An example is probably worth 1000 words at this point:
    16        <pre><code>
    17  	  python_library(
    18  	      name = 'my_library',
    19  	      srcs = ['file1.py', 'file2.py'],
    20  	  )
    21  
    22  	  python_binary(
    23  	      name = 'my_binary',
    24  	      main = 'my_main.py',
    25  	      deps = [':my_library'],
    26  	  )
    27  
    28  	  python_test(
    29  	      name = 'my_library_test',
    30  	      srcs = ['my_library_test.py'],
    31  	      deps = [':my_library'],
    32  	  )
    33        </code></pre>
    34        This snippet defines three build rules:
    35        <ul>
    36  	<li><code>my_library</code> is simply a collection of <code>file1.py</code> and <code>file2.py</code>.<br/>
    37  	  For some languages these might be compiled, for Python of course they're simply made available for other rules.</li>
    38  	<li><code>my_binary</code> creates a deployable Python binary with an entry point in <code>my_main.py</code>.<br/>
    39  	  It also defines a <em>dependency</em> on <code>my_library</code> since it will use it internally.</li>
    40  	<li><code>my_library_test</code> defines a test on <code>my_library</code>. Tests are run by Please and their results
    41  	  are aggregated.</li>
    42        </ul>
    43        This illustrates the core points of Please; every rule clearly defines its inputs - its own sources and its dependencies -
    44        and since these are known Please can be aggressive about parallelising, caching and reusing build artifacts.
    45      </p>
    46  
    47      <h2>Okay, great, so how do I actually use them?</h2>
    48  
    49      <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:
    50        <ul>
    51  	<li><code>plz build //package:my_library</code> builds the library. This isn't drastically useful on its own, of course...</li>
    52  	<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
    53  	  to another machine.</li>
    54  	<li><code>plz run //package:my_binary</code> builds and runs the binary immediately.</li>
    55  	<li><code>plz test //package:my_library_test</code> builds and runs the test and shows you the results.</li>
    56        </ul>
    57      </p>
    58  
    59      <h2>Build labels</h2>
    60  
    61      <p>That brings us to the topic of <em>build labels</em>, which are identifiers of build targets. As you've just seen,
    62        these are of the form <code>//package:target</code>, where <code>package</code> is the path from the repo root to that package,
    63        and <code>target</code> is the name of the target within that package.<br/>
    64        This is the most common form to identify targets absolutely, but there is also a convenient shorthand where we omit
    65        the part before the colon (as you saw earlier as well) to refer to a target within the current package.</p>
    66  
    67      <p>The convention is to use <code>lower_case_with_underscores</code> for both package names and target names.<br/>
    68        This is not just for looks; in many languages (eg. Python) the file path appears within the source files,
    69        and so it's important to choose something that's a valid lexical identifier.</p>
    70  
    71      <p>There are also some special pseudo-labels:
    72        <ul>
    73          <li><code>//mypackage:all</code> refers to all targets in 'mypackage'.</li>
    74          <li><code>//mypackage/...</code> refers to all targets in 'mypackage' and anywhere beneath it in the filesystem.</li>
    75        </ul>
    76        Build targets can't use these as dependencies; these are primarily for using on the command
    77        line or in the visibility specification for a target.
    78      </p>
    79  
    80      <h2>What now?</h2>
    81  
    82      <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
    83        build rules for other languages.</p>
    84  
    85      <p>If that all sounds a bit easy so far, try the <a href="intermediate.html">intermediate topics</a> and start
    86        learning how to program the system and create your own build rules.</p>