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>