github.phpd.cn/thought-machine/please@v12.2.0+incompatible/docs/faq.html (about) 1 2 <h1>FAQ</h1> 3 4 <h3>Can I run it on my computer?</h3> 5 6 <p>If you're running Linux or OSX, definitely; we actively support both those platforms.<br/> 7 Installing Please on either is as easy as <code>curl https://get.please.build | bash</code>. 8 Further dependencies shouldn't be necessary after that, assuming you have what you need for 9 the languages you want to work on (e.g. you'll need a JDK to use Please for Java).</p> 10 11 <p>To compile it, one needs Go installed, plus a few other things for various other 12 builtin tools. On Linux we primarily support Ubuntu; 13 <a href="https://www.ubuntu.com/desktop/1710">Artful</a> is the easiest to get it working on, but 14 <a href="http://releases.ubuntu.com/16.04/">Xenial</a> is supported for most features too. 15 See <a href="https://github.com/thought-machine/please/blob/master/tools/images/ubuntu">tools/images/ubuntu</a> 16 for information and a Dockerfile for setting up a recommended environment.</p> 17 18 <p>To build on OSX, you will similarly need to add some extra packages; we recommend using 19 <a href="https://brew.sh">Homebrew</a> to add at least <code>go</code> and <code>python3</code>. 20 <code>unittest-cpp</code> and <code>nasm</code> will be needed for Please's C++ tests.</p> 21 22 <p>It has been built on FreeBSD before, so it should be technically possible; this hasn't 23 been tested for some time though.</p> 24 25 <p>Windows is unfortunately not supported natively, since it's just too different from the 26 Unix environment Please is designed for. It might well be possible to make it work using 27 Cygwin or MinGW / MSYS, or the recent Ubuntu on Windows development though. We aren't 28 doing this work ourselves because we don't have any Windows machines, but we're 29 happy to accept PRs in that direction.</p> 30 31 32 <h3>What's the licence?</h3> 33 34 <p><a href="http://www.apache.org/licenses/">Apache 2.0</a></p> 35 36 37 <h3>Why use Please instead of go build / Maven / Gradle?</h3> 38 39 <p>Cross-language support is a big advantage; we have four main languages in use at Thought Machine 40 (Javascript, Python, Java and Go) plus several smaller pieces (some C++ and Thrax grammars) and 41 having to invoke different compilers and/or test tools for each one would be extremely tiresome.</p> 42 43 <p>Please can also integrate many different kinds of build steps; for example a code generation 44 step using <code>go generate</code> or <code>protoc</code> can be invoked dynamically without 45 having to check the resulting code into the repository.</p> 46 47 <p>We've tried other tools (notably Gradle and Buck) internally and ultimately decided that 48 we could build something that would either better fit our needs, be considerably faster, 49 or both.</p> 50 51 52 <h3>Why use Please instead of Bazel, Buck or Pants?</h3> 53 54 <p>All four of these systems are quite closely related in the scheme of things, being inspired by 55 (or in Bazel's case, a direct open sourcing of) Google's Blaze.</p> 56 57 <p>Several of us had worked at Google and used Blaze extensively there; we were excited about it being 58 open sourced as Bazel but by then we were already using Please internally. It's a great system but 59 we have slightly different goals, specifically we're aiming Please at being lighter weight and 60 pushing the boundaries of what can be done within the BUILD language. Since Please is written in 61 Go there's no runtime dependency on the JVM. 62 </p> 63 64 <p>We actually used Buck for some months internally before deciding to write Please and before it 65 was capable of building our repo. We preferred it to other options available, but again we're 66 focused on different goals; Please is easier to extend to new languages, has a bunch of features 67 that we specifically wanted (e.g. test containerisation) and has a stronger focus on BUILD 68 language correctness. Conversely we have much less support for mobile development.</p> 69 70 <p>We're least familiar with Pants; one of our developers briefly tried it and while we liked 71 many aspects we didn't think it was the ideal fit for us at the time.</p> 72 73 74 <h3>What inspired the design of Please?</h3> 75 76 <p>Originally Blaze, since a number of us had used it at Google. More recently we'd used Buck 77 internally so many things superficially resemble that for compatibility reasons 78 (e.g. <code>python_binary</code> instead of <code>py_binary</code> etc).</p> 79 80 <p>Some of the advanced features are based on things we would have liked to do with Blaze, for example 81 being able to defer creation of some build rules until they actually need to be built. This is 82 only really of interest for spectacularly large trees of targets or especially esoteric use 83 cases though.</p> 84 85 <p>Mostly, of course, it was inspired by our fearless leader Paul, specifically the point when 86 he told us "you absolutely cannot write your own build system". After that it was 87 really inevitable...</p> 88 89 90 <h3>Why is it so fast?</h3> 91 92 <p>Firstly, all the rules explicitly declare their dependencies, so Please can aggressively 93 parallelise build rules wherever possible. It can also cache & reuse previous outputs when 94 they haven't changed, and it hashes all input files to make sure it's correct.</p> 95 96 <p>Also BUILD files encourage you to break projects into smaller components, which can then 97 be compiled in parallel. It's still possible to define a project with a single BUILD file 98 in the traditional Java way that one would use in Gradle etc, and this works fine for 99 smaller projects, but for larger ones parallelising the compilation can be a big advantage.</p> 100 101 <p>There are no separate steps inside Please; parsing BUILD files, building targets and running 102 tests can all happen simultaneously, so there's no down time waiting for the last thing to 103 compile before the tests begin. The parsing process is also very fast due to having an 104 in-process Python interpreter.</p> 105 106 <p>It being written in Go and being an entirely native binary means great performance and fast 107 startup times; internally it's also highly parallelised and can take full advantage of the 108 underlying hardware.</p> 109 110 <p>Finally, the rules themselves are optimised in various ways; for example, the construction of 111 the final .jar from a <code>java_binary</code> is an efficient concatenation of other .jar 112 files without any recompression. Similarly the output .pex from a <code>python_binary</code> 113 is built up piecemeal throughout the <code>python_library</code> rules and assembled at the end 114 so we don't have to recompress an entire zip file every time you change one .py file.</p> 115 116 117 <h3>How do you parse the BUILD files? What format are they?</h3> 118 119 <p>The currently-unnamed BUILD language is a restricted subset of Python; see 120 <a href="language.html">here</a> for more details, documentation and a formal grammar.</p> 121 122 <p>This provides a nice balance between an elegant and powerful language, but also one that can 123 be interpreted more easily than Python itself, and that is reasonably familiar to many developers.</p> 124 125 <p>One downside to this is that the BUILD files are a little hard to automatically edit or 126 update compared to a data format like XML, Yaml or JSON. We think this is worth the tradeoff 127 for giving the developer more power and (in our opinion) a significantly nicer format.<br/> 128 A couple of Please features can help with updating BUILD files; see <a href="commands.html#gc">plz gc</a> 129 and <a href="commands.html#hash">plz hash --update</a> for more info.</p> 130 131 <p>We suggest investigating <a href="https://github.com/bazelbuild/buildifier">buildifier</a> 132 if you'd like a pretty-printer / autoformatter for them.</p> 133 134 135 <h3>Okay, but what exactly are you using to parse the files?</h3> 136 137 <p>The built-in parser is an internal pure Go implementation. It's evolved through several implementations 138 over time; ultimately this provides maximum control and performance (because we are not subject to 139 Python's GIL, or cgo calling overhead).</p> 140 141 142 <h3>How does Please build itself? Do I need Please to build Please?</h3> 143 144 <p>Please bootstraps itself using <code>go build</code> to build a temporary version of itself, 145 which is then used to rebuild itself using its own BUILD rules. This requires a little 146 duplication between the initial bootstrap script and the BUILD rules but obviously we 147 can't rely on anyone building it already having a version of it installed.</p> 148 149 <p>Fortunately the process is pretty fast since Go is fast to compile.</p> 150 151 152 <h3>Why write it in Go?</h3> 153 154 <p>We excluded most other languages that any of us were familiar with through a process 155 of elimination; JVM languages were ruled out from a concern about startup overhead, 156 we were concerned about Python's threading performance for an inherently parallel system 157 and felt C++ was too fiddly and lacked a strong standard library. Rust was still pre-1.0 158 at the time (although that didn't take long, as it turned out) so we felt it was a bit 159 early to leap into that.</p> 160 161 <p>It also turned out to be a really useful way of learning the language; the project is 162 about the right size to explore it properly and sufficiently self-contained not to 163 affect other parts of our repo until we were sure Go was a language we wanted to do more of.</p> 164 165 <p>We're very happy with the results; the performance of native binaries is excellent, 166 the language was easy to become productive with and has great support for all the things 167 we needed to do with it. Our early concerns (e.g. the classic "no generics!") 168 turned out to be a lot less problematic than we expected.</p> 169 170 <p>An alternative explanation is that the original high-level design meeting for Please was 171 an impromptu discussion in a pub one Friday evening, where we thought it would be a neat 172 language to try despite none of us having any real experience with it.</p> 173 174 175 <h3>Is this the primary repo, or do you have a secret internal version too?</h3> 176 177 <p>This is the only repository; all development is done here. Initially we had an internally 178 hosted repo but transferred the project to Github in preparation for open sourcing it. 179 180 <p>We've got some build rules in our internal repo that aren't built into Please yet. 181 We intend to open source as we can, but the ones left aren't easy to genericise 182 for various reasons.</p> 183 184 <p>There are some additional rules available at 185 <a href="https://github.com/thought-machine/pleasings">https://github.com/thought-machine/pleasings</a>, 186 which we either do not want to guarantee compatibility for, are still experimental, or are 187 sufficiently esoteric that we don't want the build process for Please to require them.</p> 188 189 190 <h3>How does the versioning scheme work? What are the compatibility guarantees?</h3> 191 192 <p>We are using <a href="http://semver.org">semantic versioning</a> so essentially: 193 <ul> 194 <li>Changes to the major version number mean you might have to make an active change 195 to your BUILD files or project config.</li> 196 <li>Changes to the minor version number indicate additional features that shouldn't 197 require any changes on your part.</li> 198 <li>Changes to the patch version number are bugfixes.</li> 199 </ul> 200 </p> 201 202 <p>These rules apply to the "public parts" of the project; specifically the command-line interface and flags, 203 the config file format and the BUILD file format and builtins are essentially the API 204 and so we take significantly more care about compatibility around those.<br/> 205 The interface to the various sub-tools invoked by Please we consider an implementation 206 detail and those might change more aggressively (although in practice they rarely do).</p> 207 208 <p>Things whose behaviour is not explicitly specified might change with less notice, 209 because of course you shouldn't have been relying on it anyway. This includes the exact 210 hash generation method - if it becomes necessary to change that for a bugfix it may force 211 apparently unnecessary rebuilds after an update. We try to avoid that as much as possible 212 since it's aggravating (for us too!) but since it doesn't affect eventual correctness 213 it can change in minor releases.</p> 214 215 <p>The versions don't apply to the code interfaces themselves, since we don't expect 216 this to see wide use as a library. If some part of it becomes popular in that way we'll 217 likely split it out to a separate repository and version it separately.</p> 218 219 220 <h3>What does it look like when I'm running it?</h3> 221 222 <p>Like this:</p> 223 224 <asciinema-player src="https://please.build/plz-recording.json"></asciinema-player> 225 226 <p>The appearance is somewhat inspired by Buck, although we have put some of our own 227 spin on it as well.</p> 228 229 <h3>What do the colours in the console output mean?</h3> 230 231 <p>They change based on the type of rule that's being built:</p> 232 233 <ul> 234 <li>Yellow: Go</li> 235 <li>Green: Python</li> 236 <li>Red: Java</li> 237 <li>Blue: Javascript</li> 238 <li>Cyan: Parsing a BUILD file</li> 239 <li>Magenta: Third party dependencies</li> 240 <li>White: Anything else.</li> 241 </ul> 242 243 <p>Libraries are normal weight, binaries (including tests) are bold.</p> 244 245 <p>There is absolutely no significance to the choice of colours beyond arbitrary choice 246 when that code was originally written.</p> 247 248 249 <h3>Why's it called Please?</h3> 250 251 <p>Because we liked the idea of sounding polite when typing "plz build", "plz test", etc.<br/> 252 Also we chose the domain name before almost anything else (priorities!).</p>