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
Or, if you prefer, grab one of the tarballs off our
releases page
and extract it yourself; it typically lives in ~/.please.
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.
There are various commands available to interact with Please, the
most obvious & useful ones initially are plz build and plz test
to build things & run tests respectively. See plz --help or the
documentation for more comprehensive
information.
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.9+ installed to build Please although once
built it can target any version from 1.5+ onwards.
Optional dependencies for various tests include Python, Java, 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_ubuntu
Documentation
- Quickstart
- Commands & command-line arguments
- Built-in rules
- BUILD language reference
- Custom build rules
- Config reference
- FAQ
Status
Please is released & we consider it stable; we follow semver for releases, so major versions indicate potentially breaking changes to the BUILD language, command line or other behaviour. We try to minimise this where possible.
We're very happy to accept pull requests & feature requests, and bugs if it's not working for you. We don't always have time for everything since Please is only part-time work for us, but we'll do our best.
Directories
¶
| Path | Synopsis |
|---|---|
|
build
Package build houses the core functionality for actually building targets.
|
Package build houses the core functionality for actually building targets. |
|
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 connections to other plz processes.
|
Package follow implements remote connections to other plz processes. |
|
fs
Package fs provides various filesystem helpers.
|
Package fs provides various filesystem helpers. |
|
gc
Package gc implements "garbage collection" logic for Please, which is an attempt to identify targets in the repo that are no longer needed.
|
Package gc implements "garbage collection" logic for Please, which is an attempt to identify targets in the repo that are no longer needed. |
|
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. |
|
metrics
Package metrics contains support for reporting metrics to an external server, currently a Prometheus pushgateway.
|
Package metrics contains support for reporting metrics to an external server, currently a Prometheus pushgateway. |
|
parse
Package parse implements parsing of the BUILD files via an embedded Python interpreter.
|
Package parse implements parsing of the BUILD files via an embedded Python interpreter. |
|
parse/args
Package main implements a simple binary to print out builtin rules.
|
Package main implements a simple binary to print out builtin rules. |
|
parse/asp
Package asp implements an experimental BUILD-language parser.
|
Package asp implements an experimental BUILD-language parser. |
|
parse/asp/fuzz
Package fuzz implements a fuzzing entry point for asp using go-fuzz.
|
Package fuzz implements a fuzzing entry point for asp using go-fuzz. |
|
parse/asp/main
Package main implements a compiler for the builtin build rules, which is used at bootstrap time.
|
Package main implements a compiler for the builtin build rules, which is used at bootstrap time. |
|
query
Package query implements a simple query language for Please.
|
Package query implements a simple query language for Please. |
|
run
Package run implements the "plz run" command.
|
Package run implements the "plz run" command. |
|
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). |
|
update
Package update contains code for Please auto-updating itself.
|
Package update contains code for Please auto-updating itself. |
|
utils
Package utils contains various utility functions and whatnot.
|
Package utils contains various utility functions and whatnot. |
|
watch
Package watch provides a filesystem watcher that is used to rebuild affected targets.
|
Package watch provides a filesystem watcher that is used to rebuild affected targets. |
|
test
|
|
|
go_rules/asm
Package asm implements a simple test of Go assembly.
|
Package asm implements a simple test of Go assembly. |
|
go_rules/asm_binary
Package asm implements a simple binary using Go assembly.
|
Package asm implements a simple binary using Go assembly. |
|
go_rules/importpath
Package importpath is used to implement a test on Go import paths.
|
Package importpath is used to implement a test on Go import paths. |
|
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/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. |
|
cache/server
Package server contains core functionality for our cache servers; storing & retrieving files etc.
|
Package server contains core functionality for our cache servers; storing & retrieving files etc. |
|
jarcat
Package main implements jarcat, a program to efficiently concatenate .zip files.
|
Package main implements jarcat, a program to efficiently concatenate .zip files. |
|
jarcat/tar
Package tar implements a tarball writer for Please.
|
Package tar implements a tarball writer for Please. |
|
jarcat/unzip
Package unzip implements unzipping for jarcat.
|
Package unzip implements unzipping for jarcat. |
|
jarcat/zip
Package zip implements functions for jarcat that manipulate .zip files.
|
Package zip implements functions for jarcat that manipulate .zip files. |
|
please_diff_graphs
package main implements plz_diff_graphs, a small utility to take the JSON representation of two build graphs (as output from 'plz query graph') and produce a list of targets that have changed between the two.
|
package main implements plz_diff_graphs, a small utility to take the JSON representation of two build graphs (as output from 'plz query graph') and produce a list of targets that have changed between the two. |
|
please_diff_graphs/diff
Package diff contains the implementation of the graph differ.
|
Package diff contains the implementation of the graph differ. |
|
please_go_filter
Package main implements please_go_filter, a tool for filtering go source files.
|
Package main implements please_go_filter, a tool for filtering go source files. |
|
please_go_test/gotest
Package gotest contains utilities used by plz_go_test.
|
Package gotest contains utilities used by plz_go_test. |
|
please_maven
Package main implements please_maven, a command-line tool to find dependencies from a remote Maven repo (typically Maven Central, but can be others).
|
Package main implements please_maven, a command-line tool to find dependencies from a remote Maven repo (typically Maven Central, but can be others). |
|
please_pex
Package main implements please_pex, which builds runnable Python zip files for us.
|
Package main implements please_pex, which builds runnable Python zip files for us. |
|
please_pex/pex
Package pex implements construction of .pex files in Go.
|
Package pex implements construction of .pex files in Go. |
|
release_signer
Package main implements an OpenPGP-compatible signer for our releases.
|
Package main implements an OpenPGP-compatible signer for our releases. |