README
¶
Please 
Please is a cross-language build system with an emphasis on high performance, extensibility and reproduceability. It supports a number of popular languages and can automate nearly any aspect of your build process.
See http://please.build for more information.
Currently Linux (tested on Ubuntu) and OSX are actively supported, and FreeBSD is known to work with a little setup (see FAQ for details).
Getting Started
The easiest way to install it on your own machine is to run:
curl -s https://get.please.build | bash
In order for it to run you will need a Python interpreter available.
You can use either PyPy or CPython with cffi; on Linux Please will
attempt to download a portable version of PyPy if a system one isn't
available, on OSX installation is fairly straightforward with Homebrew,
simply run brew install pypy.
Alternatively, you've likely got CPython installed already, and installing
cffi is as simple as sudo pip install "cffi>=1.5.0".
Then you simply run plz init at the root of your project to set up
a default config and you're good to start adding BUILD files.
See the website for more instructions about
how to write them.
Building Please
To build Please yourself, run ./bootstrap.sh in the repo root.
This will set up the minimal environment needed to build Please,
build it once manually and then rebuild it again using itself.
You'll need to have Go 1.8+ installed to build Please (we use some
new standard library features like context) although once built it
can target Go 1.4+.
Similarly to the instructions above, you'll need a python interpreter. Having PyPy, python2 and python3 installed will allow you to build all the possible engines & therefore packages etc, but just python2 is enough for the build to succeed, as long as you have cffi installed as mentioned above.
You'll need to have dependencies for the various helper programs
of Please installed in order to build it. At the moment the minimal
set are Python (which you'll likely have anyway) and Java 7 or above.
Optional dependencies for various tests include unittest++
(sudo apt-get install libunittest++-dev), clang, gold and docker - none
of those are required to build components so their tests will be excluded
if they aren't available.
If you'd rather not worry about installing the dependencies, we provide
a prebuilt Docker image based on Ubuntu which is capable of building
the whole thing for you:
docker run -it thoughtmachine/please
Contributors
The core contributors so far are:
Progress has been slightly hindered by our fearless leader Paul who continually insists that we should "get on with our work" and "stop messing around with the build system". But he's not actually fired us for spending time on this which he has our thanks for.
Directories
¶
| Path | Synopsis |
|---|---|
|
build
Package build houses the core functionality for actually building targets.
|
Package build houses the core functionality for actually building targets. |
|
cache/cluster
Package cluster contains functions for dealing with a cluster of plz cache nodes.
|
Package cluster contains functions for dealing with a cluster of plz cache nodes. |
|
cli
Package cli contains helper functions related to flag parsing and logging.
|
Package cli contains helper functions related to flag parsing and logging. |
|
export
Package export handles exporting parts of the repo to other directories.
|
Package export handles exporting parts of the repo to other directories. |
|
follow
Package follow implements remote communication between plz instances.
|
Package follow implements remote communication between plz instances. |
|
help
Package help prints help messages about parts of plz.
|
Package help prints help messages about parts of plz. |
|
help/config
Package main implements a parser for our config structure that emits help topics based on its struct tags.
|
Package main implements a parser for our config structure that emits help topics based on its struct tags. |
|
parse
Package responsible for parsing build files and constructing build targets & the graph.
|
Package responsible for parsing build files and constructing build targets & the graph. |
|
query
Package query implements a simple query language for Please.
|
Package query implements a simple query language for Please. |
|
tool
Package tool implements running Please's sub-tools (via "plz tool jarcat" etc).
|
Package tool implements running Please's sub-tools (via "plz tool jarcat" etc). |
|
utils
Package utils contains various utility functions and whatnot.
|
Package utils contains various utility functions and whatnot. |
|
third_party
|
|
|
go/zip
Package zip provides support for reading and writing ZIP archives.
|
Package zip provides support for reading and writing ZIP archives. |
|
tools
|
|
|
cache_cleaner
Package main implements a small program to clean directory cache.
|
Package main implements a small program to clean directory cache. |
|
jarcat/tar
Package tar implements a tarball writer for Please.
|
Package tar implements a tarball writer for Please. |
|
please_go_test
Package buildgo contains utilities used by plz_go_test.
|
Package buildgo contains utilities used by plz_go_test. |