Please Plugins
Plugins are a way to extend Please with build rules for additional languages or technologies. The quickest way to get
started is by running plz init plugin [go|python|java]
. The full list of available plugins
can be found here.
Plugins are configured in your .plzconfig
file. For example, to load the
python
plugin, add the following to your .plzconfig
file:
[Plugin "python"]
Target = //plugins:python
DefaultInterpreter = python3 # Optional config
Where Target = //plugins:python
is the plugin_repo()
target for your plugin. For example:
plugin_repo(
name = "python",
revision = "v0.1.0",
)
There are some first-class plugins that are supported and maintained by the Please team. These are listed below.
C/C++ rules
c_binary
c_binary(name, srcs, hdrs, private_hdrs, compiler_flags, linker_flags, deps, visibility, pkg_config_libs, pkg_config_cflags, test_only, static, includes, defines, labels, optional_outs)
Builds a binary from a collection of C rules.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C source files to compile. | |
hdrs | list | Header files. | |
private_hdrs | list | Header files that are available only to this rule and not exported to dependent rules. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker. | |
deps | list | Dependent rules. | |
visibility | list | Visibility declaration for this rule. | |
pkg_config_libs | list | Libraries to declare a dependency on using pkg-config | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags` | |
test_only | bool | If True, this rule can only be used by tests. | |
static | bool | If True, the binary will be linked statically. | |
includes | list | List of include directories to be added to the compiler's path. | |
defines | list or dict | List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes. | |
labels | list | ||
optional_outs | list | Name of optional outputs. |
c_embed_binary
c_embed_binary(name, src, deps, visibility, test_only)
Build rule to embed an arbitrary binary file into a C library.
You can depend on the output of this as though it were a c_library rule.
There are five functions available to access the data once compiled, all of which are
prefixed with the file's basename:
filename_start(): returns a const char* pointing to the beginning of the data.
filename_end(): returns a const char* pointing to the end of the data.
filename_size(): returns the length of the data in bytes.
filename_start_nc(): returns a char* pointing to the beginning of the data.
This is a convenience wrapper using const_cast, you should not
mutate the contents of the returned pointer.
filename_end_nc(): returns a char* pointing to the end of the data.
Again, don't mutate the contents of the pointer.
You don't own the contents of any of these pointers so don't try to delete them :)
Argument | Required | Type | |
---|---|---|---|
name | yes | str | filename_start(): returns a const char* pointing to the beginning of the data. filename_end(): returns a const char* pointing to the end of the data. filename_size(): returns the length of the data in bytes. filename_start_nc(): returns a char* pointing to the beginning of the data. This is a convenience wrapper using const_cast, you should not mutate the contents of the returned pointer. filename_end_nc(): returns a char* pointing to the end of the data. Again, don't mutate the contents of the pointer. You don't own the contents of any of these pointers so don't try to delete them :) Args: |
src | yes | str | Source file to embed. |
deps | list | Dependencies. | |
visibility | list | Rule visibility. | |
test_only | bool | If True, is only available to test rules. |
c_library
c_library(name, srcs, hdrs, private_hdrs, deps, out, optional_outs, visibility, test_only, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, includes, defines, alwayslink, labels)
Generate a C library target.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C source files to compile. | |
hdrs | list | Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important. | |
private_hdrs | list | Header files that are available only to this rule and not exported to dependent rules. | |
deps | list | Dependent rules. | |
out | str | Name of the output library. Defaults to lib<name>.a (or just <name>.a if name already begins with 'lib'). | |
optional_outs | list | Name of optional outputs. | |
visibility | list | Visibility declaration for this rule. | |
test_only | bool | If True, is only available to other test rules. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker; these will not be used here but will be picked up by a c_binary or c_test rule. | |
pkg_config_libs | list | Libraries to declare a dependency on using pkg-config. Again, the ldflags will be picked up by cc_binary or cc_test rules. | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags`. | |
includes | list | List of include directories to be added to the compiler's path. | |
defines | list or dict | List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes. | |
alwayslink | bool | If True, any binaries / tests using this library will link in all symbols, even if they don't directly reference them. This is useful for e.g. having static members that register themselves at construction time. | |
labels | list | Labels to attach to this rule. |
c_object
c_object(name, src, hdrs, private_hdrs, out, optional_outs, test_only, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, includes, defines, alwayslink, visibility, deps, labels)
Generate a C object file from a single source.
N.B. This is fairly low-level; for most use cases c_library should be preferred.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
src | yes | str | C or C++ source file to compile. This can be another rule, but if so it must have exactly one output. |
hdrs | list | Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important. | |
private_hdrs | list | Header files that are available only to this rule and not exported to dependent rules. | |
out | str | Name of the output file. Defaults to name + .o. | |
optional_outs | list | Name of optional outputs. | |
test_only | bool | If True, is only available to other test rules. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker; these will not be used here but will be picked up by a c_binary or c_test rule. | |
pkg_config_libs | list | Libraries to declare a dependency on using pkg-config. Again, the ldflags will be picked up by cc_binary or cc_test rules. | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags`. Again, the ldflags will be picked up by cc_binary or cc_test rules. | |
includes | list | List of include directories to be added to the compiler's path. | |
defines | list or dict | List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes. | |
alwayslink | bool | If True, any binaries / tests using this library will link in all symbols, even if they don't directly reference them. This is useful for e.g. having static members that register themselves at construction time. |
|
visibility | list | Visibility declaration for this rule. | |
deps | list | Dependent rules. | |
labels | list |
c_shared_object
c_shared_object(name, srcs, hdrs, out, compiler_flags, linker_flags, deps, visibility, test_only, pkg_config_libs, pkg_config_cflags, includes, labels, optional_outs)
Generates a C shared object (.so) with its dependencies linked in.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C or C++ source files to compile. | |
hdrs | list | Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important. | |
out | str | Name of the output .so. Defaults to name + .so. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker. | |
deps | list | Dependent rules. | |
visibility | list | Visibility declaration for this rule. | |
test_only | bool | If True, is only available to other test rules. | |
pkg_config_libs | list | Libraries to declare a dependency on using pkg-config | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags` | |
includes | list | Include directories to be added to the compiler's lookup path. | |
labels | list | ||
optional_outs | list | Name of optional outputs. |
c_static_library
c_static_library(name, srcs, hdrs, compiler_flags, linker_flags, deps, out, visibility, test_only, pkg_config_libs, pkg_config_cflags, labels, optional_outs)
Generates a C static library (.a).
This is essentially just a collection of other c_library rules into a single archive.
Optionally this rule can have sources of its own, but it's quite reasonable just to use
it as a collection of other rules.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C or C++ source files to compile. | |
hdrs | list | Header files. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker. | |
deps | list | Dependent rules. | |
out | str | Name of the output library. Defaults to lib<name>.a (or just <name>.a if name already begins with 'lib'). | |
visibility | list | Visibility declaration for this rule. | |
test_only | bool | If True, is only available to other test rules. | |
pkg_config_libs | list | Libraries to declare a dependency on using pkg-config | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags` | |
labels | list | ||
optional_outs | list | Name of optional outputs. |
c_test
c_test(name, srcs, hdrs, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, deps, worker, data, visibility, flags, labels, flaky, test_outputs, size, timeout, sandbox)
Defines a C test target.
Note that you must supply your own main() and test framework (ala cc_test when
write_main=False).
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C or C++ source files to compile. | |
hdrs | list | Header files. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker. | |
pkg_config_libs | list | Libraries to declare a dependency on using pkg-config | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags` | |
deps | list | Dependent rules. | |
worker | str | ||
data | list or dict | Runtime data files for this test. | |
visibility | list | Visibility declaration for this rule. | |
flags | str | Flags to pass to the compiler. | |
labels | list | Labels to attach to this test. | |
flaky | bool or int | If true the test will be marked as flaky and automatically retried. | |
test_outputs | list | Extra test output files to generate from this test. | |
size | str | Test size (enormous, large, medium or small). | |
timeout | int | Length of time in seconds to allow the test to run for before killing it. | |
sandbox | bool | Sandbox the test on Linux to restrict access to namespaces such as network. |
cc_binary
cc_binary(name, srcs, hdrs, private_hdrs, compiler_flags, linker_flags, deps, visibility, pkg_config_libs, includes, defines, pkg_config_cflags, test_only, static, linkstatic, labels, optional_outs)
Builds a binary from a collection of C++ rules.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C or C++ source files to compile. | |
hdrs | list | Header files. | |
private_hdrs | list | Header files that are available only to this rule and not exported to dependent rules. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker. | |
deps | list | Dependent rules. | |
visibility | list | Visibility declaration for this rule. | |
pkg_config_libs | list | Libraries to declare a dependency on using `pkg-config --libs` | |
includes | list | List of include directories to be added to the compiler's path. | |
defines | list or dict | List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes. | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags` | |
test_only | bool | If True, this rule can only be used by tests. | |
static | bool | If True, the binary will be linked statically. | |
linkstatic | bool | Only provided for Bazel compatibility. Has no actual effect since we always link roughly equivalently to their "mostly-static" mode. | |
labels | list | Labels to attach to this rule. | |
optional_outs | list | Name of optional outputs. |
cc_embed_binary
cc_embed_binary(name, src, deps, visibility, test_only, namespace)
Build rule to embed an arbitrary binary file into a C++ library.
You can depend on the output of this as though it were a cc_library rule.
There are five functions available to access the data once compiled, all of which are
prefixed with the file's basename:
filename_start(): returns a const char* pointing to the beginning of the data.
filename_end(): returns a const char* pointing to the end of the data.
filename_size(): returns the length of the data in bytes.
filename_start_nc(): returns a char* pointing to the beginning of the data.
This is a convenience wrapper using const_cast, you should not
mutate the contents of the returned pointer.
filename_end_nc(): returns a char* pointing to the end of the data.
Again, don't mutate the contents of the pointer.
You don't own the contents of any of these pointers so don't try to delete them :)
Argument | Required | Type | |
---|---|---|---|
name | yes | str | filename_start(): returns a const char* pointing to the beginning of the data. filename_end(): returns a const char* pointing to the end of the data. filename_size(): returns the length of the data in bytes. filename_start_nc(): returns a char* pointing to the beginning of the data. This is a convenience wrapper using const_cast, you should not mutate the contents of the returned pointer. filename_end_nc(): returns a char* pointing to the end of the data. Again, don't mutate the contents of the pointer. You don't own the contents of any of these pointers so don't try to delete them :) Args: |
src | yes | str | Source file to embed. |
deps | list | Dependencies. | |
visibility | list | Rule visibility. | |
test_only | bool | If True, is only available to test rules. | |
namespace | str | Allows specifying the namespace the symbols will be available in. |
cc_library
cc_library(name, srcs, hdrs, private_hdrs, deps, out, optional_outs, visibility, test_only, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, includes, defines, alwayslink, linkstatic, textual_hdrs, labels)
Generate a C++ library target.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C++ source files to compile. | |
hdrs | list | Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important. | |
private_hdrs | list | Header files that are available only to this rule and not exported to dependent rules. | |
deps | list | Dependent rules. | |
out | str | Name of the output library. Defaults to lib<name>.a (or just <name>.a if name already begins with 'lib'). | |
optional_outs | list | Name of optional outputs. | |
visibility | list | Visibility declaration for this rule. | |
test_only | bool | If True, is only available to other test rules. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker; these will not be used here but will be picked up by a cc_binary or cc_test rule. | |
pkg_config_libs | list | Libraries to declare a dependency on using `pkg-config --libs`. Again, the ldflags will be picked up by cc_binary or cc_test rules. | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags`. Again, the ldflags will be picked up by cc_binary or cc_test rules. | |
includes | list | List of include directories to be added to the compiler's path. | |
defines | list or dict | List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes. | |
alwayslink | bool | If True, any binaries / tests using this library will link in all symbols, even if they don't directly reference them. This is useful for e.g. having static members that register themselves at construction time. | |
linkstatic | bool | Only provided for Bazel compatibility. Has no actual effect. | |
textual_hdrs | list | Also provided for Bazel compatibility. Effectively works the same as hdrs for now. | |
labels | list | Labels to attach to this rule. |
cc_module
cc_module(name, srcs, hdrs, interfaces, private_hdrs, deps, visibility, test_only, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, includes, defines, alwayslink, labels, optional_outs)
Generate a C++ module.
This is still experimental. Currently it has only been tested with clang; support for GCC
will be added later once versions of GCC supporting modules are more conveniently available.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C++ source files to compile. | |
hdrs | list | Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important. | |
interfaces | list | Module interface files. Again, these are treated differently to `srcs` in terms of compilation so the distinction is important. | |
private_hdrs | list | Header files that are available only to this rule and not exported to dependent rules. | |
deps | list | Dependent rules. | |
visibility | list | Visibility declaration for this rule. | |
test_only | bool | If True, is only available to other test rules. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker; these will not be used here but will be picked up by a cc_binary or cc_test rule. | |
pkg_config_libs | list | Libraries to declare a dependency on using `pkg-config --libs`. Again, the ldflags will be picked up by cc_binary or cc_test rules. | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags`. Again, the ldflags will be picked up by cc_binary or cc_test rules. | |
includes | list | List of include directories to be added to the compiler's path. | |
defines | list or dict | List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes. | |
alwayslink | bool | If True, any binaries / tests using this library will link in all symbols, even if they don't directly reference them. This is useful for e.g. having static members that register themselves at construction time. | |
labels | list | Labels to attach to this rule. | |
optional_outs | list | Name of optional outputs. |
cc_object
cc_object(name, src, hdrs, private_hdrs, out, optional_outs, test_only, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, includes, defines, alwayslink, visibility, deps, labels)
Generate a C or C++ object file from a single source.
N.B. This is fairly low-level; for most use cases cc_library should be preferred.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
src | yes | str | C or C++ source file to compile. This can be another rule, but if so it must have exactly one output. |
hdrs | list | Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important. | |
private_hdrs | list | Header files that are available only to this rule and not exported to dependent rules. | |
out | str | Name of the output file. Defaults to name + .o. | |
optional_outs | list | Name of optional outputs. | |
test_only | bool | If True, is only available to other test rules. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker; these will not be used here but will be picked up by a cc_binary or cc_test rule. | |
pkg_config_libs | list | Libraries to declare a dependency on using `pkg-config --libs`. Again, the ldflags will be picked up by cc_binary or cc_test rules. | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags`. Again, the ldflags will be picked up by cc_binary or cc_test rules. | |
includes | list | List of include directories to be added to the compiler's path. | |
defines | list or dict | List of tokens to define in the preprocessor. Alternatively can be a dict of name -> value to define, in which case values are surrounded by quotes. | |
alwayslink | bool | If True, any binaries / tests using this library will link in all symbols, even if they don't directly reference them. This is useful for e.g. having static members that register themselves at construction time. | |
visibility | list | Visibility declaration for this rule. | |
deps | list | Dependent rules. | |
labels | list | Labels to attach to this rule. |
cc_shared_object
cc_shared_object(name, srcs, hdrs, out, optional_outs, compiler_flags, linker_flags, deps, visibility, test_only, pkg_config_libs, pkg_config_cflags, includes, labels)
Generates a C++ shared object (.so) with its dependencies linked in.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C or C++ source files to compile. | |
hdrs | list | Header files. These will be made available to dependent rules, so the distinction between srcs and hdrs is important. | |
out | str | Name of the output .so. Defaults to lib<name>.so (or just <name>.so if name already begins with 'lib'). | |
optional_outs | list | Name of optional outputs. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker. | |
deps | list | Dependent rules. | |
visibility | list | Visibility declaration for this rule. | |
test_only | bool | If True, is only available to other test rules. | |
pkg_config_libs | list | Libraries to declare a dependency on using `pkg-config --libs` | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags` | |
includes | list | Include directories to be added to the compiler's lookup path. | |
labels | list | Labels to attach to this rule. |
cc_static_library
cc_static_library(name, srcs, hdrs, compiler_flags, out, optional_outs, linker_flags, deps, visibility, test_only, pkg_config_libs, pkg_config_cflags, labels)
Generates a C++ static library (.a).
This is essentially just a collection of other cc_library rules into a single archive.
Optionally this rule can have sources of its own, but it's quite reasonable just to use
it as a collection of other rules.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C or C++ source files to compile. | |
hdrs | list | Header files. | |
compiler_flags | list | Flags to pass to the compiler. | |
out | str | Name of the output library. Defaults to lib<name>.a (or just <name>.a if name already begins with 'lib'). | |
optional_outs | list | Name of optional outputs. | |
linker_flags | list | Flags to pass to the linker. | |
deps | list | Dependent rules. | |
visibility | list | Visibility declaration for this rule. | |
test_only | bool | If True, is only available to other test rules. | |
pkg_config_libs | list | Libraries to declare a dependency on using `pkg-config --libs` | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags` | |
labels | list | Labels to attach to this rule. |
cc_test
cc_test(name, srcs, hdrs, compiler_flags, linker_flags, pkg_config_libs, pkg_config_cflags, deps, worker, data, visibility, flags, labels, flaky, test_outputs, size, timeout, sandbox, write_main, linkstatic)
Defines a C++ test.
We template in a main file so you don't have to supply your own.
(Later we might allow that to be configured to help support other unit test frameworks).
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | C or C++ source files to compile. | |
hdrs | list | Header files. | |
compiler_flags | list | Flags to pass to the compiler. | |
linker_flags | list | Flags to pass to the linker. | |
pkg_config_libs | list | Libraries to declare a dependency on using `pkg-config --libs` | |
pkg_config_cflags | list | Libraries to declare a dependency on using `pkg-config --cflags` | |
deps | list | Dependent rules. | |
worker | str | Reference to worker script, A persistent worker process that is used to set up the test. | |
data | list or dict | Runtime data files for this test. | |
visibility | list | Visibility declaration for this rule. | |
flags | str | Flags to pass to the compiler. | |
labels | list | Labels to attach to this test. | |
flaky | bool or int | If true the test will be marked as flaky and automatically retried. | |
test_outputs | list | Extra test output files to generate from this test. | |
size | str | Test size (enormous, large, medium or small). | |
timeout | int | Length of time in seconds to allow the test to run for before killing it. | |
sandbox | bool | Sandbox the test on Linux to restrict access to namespaces such as network. | |
write_main | bool | Deprecated, has no effect. See `plz help testmain` for more information about how to define a default dependency for the test main. | |
linkstatic | bool | Only provided for Bazel compatibility. Has no actual effect since we always link roughly equivalently to their "mostly-static" mode. |
[Plugin "cc"]
-
DefaultDbgCFlags (string)
The default c compiler flags when compiling for debug
If set, DefaultDbgCFlags is inherited from the host repo.
Defaults to
--std=c99 -g3 -pipe -DDEBUG -Wall -Werror
-
DsymTool (string)
Set this to dsymutil or equivalent on MacOS to use this tool to generate xcode symbol information for debug builds.
If set, DsymTool is inherited from the host repo.
-
PkgConfigPath (string)
A path to the systems package configs
If set, PkgConfigPath is inherited from the host repo.
-
CoverageTool (string)
The path or build target for the C coverage analysis tool
If set, CoverageTool is inherited from the host repo.
Defaults to
gcov
-
CCTool (string)
The path or build label for the C compiler
If set, CCTool is inherited from the host repo.
Defaults to
gcc
-
LDTool (string)
If set, LDTool is inherited from the host repo.
Defaults to
ld
-
ARTool (string)
If set, ARTool is inherited from the host repo.
Defaults to
ar
-
TestMain (string)
A build label with c/c++ source code to use run tests.
If set, TestMain is inherited from the host repo.
Defaults to
//unittest-pp:main
-
AsmTool (string)
The tool to use for assembling assembly code
If set, AsmTool is inherited from the host repo.
Defaults to
nasm
-
DefaultNamespace (string)
The default namespace to compile c++ code in
-
Coverage (bool)
Whether to build with coverage
If set, Coverage is inherited from the host repo.
Defaults to
true
-
CPPTool (string)
The path or build label for the C++ compiler
If set, CPPTool is inherited from the host repo.
Defaults to
g++
-
DefaultOptCFlags (string)
The default c compiler flags when compiling for release
If set, DefaultOptCFlags is inherited from the host repo.
Defaults to
--std=c99 -O3 -pipe -DNDEBUG -Wall -Werror
-
DefaultLdFlags (string)
The default set of flags to apply when linking
If set, DefaultLdFlags is inherited from the host repo.
Defaults to
-lpthread -ldl
-
DefaultOptCppFlags (string)
The default c++ compiler flags when compiling for release
If set, DefaultOptCppFlags is inherited from the host repo.
Defaults to
--std=c++11 -O3 -pipe -DNDEBUG -Wall -Werror
-
DefaultDbgCppFlags (string)
The default c++ compiler flags when compiling for debug
If set, DefaultDbgCppFlags is inherited from the host repo.
Defaults to
--std=c++11 -g3 -pipe -DDEBUG -Wall -Werror
Go rules
cgo_library
cgo_library(name, srcs, resources, go_srcs, c_srcs, hdrs, package, compiler_flags, linker_flags, pkg_config, subdir, deps, labels, visibility, test_only, import_path)
Generates a Go library which can be reused by other rules.
Note that by its nature this is something of a hybrid of Go and C rules. It can depend
on C / C++ rules, given the limitations of cgo (i.e. you will have to interact with them
through a C interface, although the objects themselves can contain C++). As mentioned
below, you will likely be better off wrapping your dependencies into a cc_static_library
rule and depending on that rather than depending directly on cc_library rules.
Note also that this does not honour Go's syntactic comments; you have to explicitly
specify which Go files are cgo vs. which are not, as well as C headers & sources and
any required cflags or ldflags.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
srcs | list | Go source files to compile that have 'import "C"' declarations in them. | |
resources | list | Files to embed in the library using //go:embed directives. | |
go_srcs | list | Any Go source files that do *not* have 'import "C"' declarations. | |
c_srcs | list | Any C source files to include. | |
hdrs | list | Any C header files to include. | |
package | str | ||
compiler_flags | list | List of compiler flags to be passed when compiling the C code. | |
linker_flags | list | List of linker flags to be passed when linking a Go binary. | |
pkg_config | list | List of packages to pass to pkg-config. | |
subdir | str | Subdirectory that source files are in. Required if they're not in the current directory. | |
deps | list | Dependencies. Note that if you intend to depend on cc_library rules, you will likely be better off wrapping them into a cc_static_library and depending on that. | |
labels | list | Labels for this rule. | |
visibility | list | Visibility specification | |
test_only | bool | If True, is only visible to test rules. | |
import_path | str | If set, this will override the import path of the generated go package. |
cgo_test
cgo_test(name, srcs, data, deps, visibility, flags, sandbox, timeout, flaky, test_outputs, labels, size, static)
Defines a Go test rule over a cgo_library.
If the library you are testing is a cgo_library, you must use this instead of go_test.
It's ok to depend on a cgo_library though as long as it's not the same package
as your test; in that (any any other case of testing a go_library) you must use go_test.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
srcs | yes | list | Go source files to compile. |
data | list | Runtime data files for the test. | |
deps | list | Dependencies | |
visibility | list | Visibility specification | |
flags | str | Flags to apply to the test invocation. | |
sandbox | bool | Sandbox the test on Linux to restrict access to namespaces such as network. | |
timeout | int | Timeout in seconds to allow the test to run for. | |
flaky | bool or int | True to mark the test as flaky, or an integer to specify how many reruns. | |
test_outputs | list | Extra test output files to generate from this test. | |
labels | list | Labels for this rule. | |
size | str | Test size (enormous, large, medium or small). | |
static | bool | If True, passes flags to the linker to try to force fully static linking. (specifically `-linkmode external -extldflags static`). Typically this increases size & link time a little but in return the binary has absolutely no external dependencies. It may not be easy to make cgo tests work when linked statically; depending on your toolchain it may not be possible or may fail. |
go_benchmark
go_benchmark(name, srcs, resources, data, deps, visibility, sandbox, cgo, filter_srcs, external, timeout, labels, static, definitions, test_only)
Defines a Go test suite that will be run as a benchmark.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
srcs | yes | list | Go source files to compile. |
resources | list | Files to embed in the library using //go:embed directives. | |
data | list or dict | Runtime data files for the test. | |
deps | list | Dependencies | |
visibility | list | Visibility specification | |
sandbox | bool | Sandbox the test on Linux to restrict access to namespaces such as network. | |
cgo | bool | True if this test depends on a cgo_library. | |
filter_srcs | bool | If True, filters source files through Go's standard build constraints. | |
external | bool | True if this test is external to the library it's testing, i.e. it uses the feature of Go that allows it to be in the same directory with a _test suffix. | |
timeout | int | Timeout in seconds to allow the test to run for. | |
labels | list | Labels for this rule. | |
static | bool | If True, passes flags to the linker to try to force fully static linking. (specifically `-linkmode external -extldflags static`). Typically this increases size & link time a little but in return the binary has absolutely no external dependencies. Note that it may have negative consequences if the binary contains any cgo (including net/http DNS lookup code potentially). | |
definitions | str or list or dict | If set to a string, defines importpath.name=value when calling the Go linker. If set to a list, pass each value as a definition to the linker. If set to a dict, each key/value pair is used to contruct the list of definitions passed to the linker. | |
test_only | If True, is only visible to test rules. |
go_binary
go_binary(name, srcs, resources, asm_srcs, out, deps, data, visibility, labels, test_only, static, filter_srcs, definitions, stamp, strip)
Compiles a Go binary.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
srcs | list | Go source files, one of which contains the main function. | |
resources | list | Files to embed in the library using //go:embed directives. | |
asm_srcs | list | Assembly source files. | |
out | str | Name of the output file to create. Defaults to the same as `name`. | |
deps | list | Dependencies | |
data | list or dict | Runtime dependencies of this rule. | |
visibility | list | Visibility specification | |
labels | list | Labels for this rule. | |
test_only | bool | If True, is only visible to test rules. | |
static | bool | If True, passes flags to the linker to try to force fully static linking. (specifically `-linkmode external -extldflags static`). Typically this increases size & link time a little but in return the binary has absolutely no external dependencies. Note that it may have negative consequences if the binary contains any cgo (including net/http DNS lookup code potentially). | |
filter_srcs | bool | If True, filters source files through Go's standard build constraints. | |
definitions | str or list or dict | If set to a string, defines importpath.name=value when calling the Go linker. If set to a list, pass each value as a definition to the linker. If set to a dict, each key/value pair is used to contruct the list of definitions passed to the linker. | |
stamp | bool | Allows this rule to gain access to information about SCM revision etc via env vars. These can be useful to pass into `definitions`. | |
strip | bool | Determines whether the binary will be stripped of debug symbols or not. By default the value of the strip_binaries plugin configuration option is used; if this is not set, whether or not the binary is stripped depends on the build mode. |
go_library
go_library(name, srcs, resources, asm_srcs, hdrs, deps, visibility, test_only, complete, cover, filter_srcs, import_path, labels, package, pgo_file)
Generates a Go library which can be reused by other rules.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
srcs | yes | list | Go source files to compile. |
resources | list | Files to embed in the library using //go:embed directives. | |
asm_srcs | list | Source files to assemble with `go tool assemble`. | |
hdrs | list | Header files needed for assembly. Has no effect if asm_srcs is not given. | |
deps | list | Dependencies | |
visibility | list | Visibility specification | |
test_only | bool | If True, is only visible to test rules. | |
complete | bool | Indicates whether the library is complete or not (ie. buildable with `go tool build -complete`). In nearly all cases this is True (the main exception being for cgo). | |
cover | bool | Indicates whether this library should be considered for coverage annotations. Libraries are only annotated when using `plz cover` (or `plz build -c cover`), but if this is false they never will be. Can be useful for e.g. third-party code that you never want to be instrumented. | |
filter_srcs | bool | If True, filters source files through Go's standard build constraints. | |
import_path | str | If set, this will override the import path of the generated go package. | |
labels | list | Labels for this rule. | |
package | str | The package as it would appear at the top of the go source files. Defaults to name. | |
pgo_file | str | The CPU profile to supply for profile-guided optimisation. |
go_mod_download
go_mod_download(name, module, version, test_only, visibility, strip, licences, hashes, labels, deps, patch)
Downloads a third-party Go module using `go mod download`
This rule is typically used in conjunction with go_module() to resolve cyclic dependencies between modules. This rule
can be passed to go_module() via the download param which enables multiple go_module() rules to compile parts of the
whole module. It can also be useful to download from a fork of a module where the import path doesn't match the
repo path.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
module | yes | str | The module to download |
version | yes | str | The version of the module. |
test_only | bool | If true this rule will only be visible to tests. | |
visibility | list | Visibility specification | |
strip | list | List of paths to strip from the target after downloading but before building it. | |
licences | list | Licences this rule is subject to. | |
hashes | list | List of hashes to verify the downloaded sources against. | |
labels | list | Labels to apply to this rule. | |
deps | list | Dependencies | |
patch | list |
go_module
go_module(name, module, version, download, deps, exported_deps, visibility, test_only, binary, install, labels, hashes, licences, linker_flags, strip, env, patch, build_tags)
Defines a dependency on a third-party Go module.
Note that unlike a normal `go get` call, this does *not* install transitive dependencies.
You will need to add those as separate rules; `go list -f '{{.Deps}}' <package>` can be
useful to discover what they should be.
This rule is different to go_repo() in that it compiles the whole go module in one build action. This can lead to
issues when modules are cyclically dependent on each other. For this reason, go_repo is recommended over go_module().
Argument | Required | Type | |
---|---|---|---|
name | str | Name of the rule | |
module | yes | str | The module to compile |
version | str | The version of the module. | |
download | str | Can be provided instead of version to manage downloading the module separately. This must be a rule that has a single output containing the go sources of the module. Usually this will be a go_mod_download() rule however it doesn't have to be. This can be used for a number of purposes but primarily it is for resolving cyclic dependencies between modules. | |
deps | list | Dependencies | |
exported_deps | list | Dependencies to make available to anything using this rule. | |
visibility | list | Visibility specification | |
test_only | bool | If true this rule will only be visible to tests. | |
binary | bool | True if the output of the rule is a binary. | |
install | list | Only install listed (sub)packages. If the dict form is used, each key should correspond to a target in 'get', with the value defining the list of packages to install for that target. Specify the empty string as an element in the list to install a target's root package. | |
labels | list | Additional labels to apply to this rule. | |
hashes | list | List of hashes to verify the downloaded sources against. | |
licences | list | Licences this rule is subject to. | |
linker_flags | list | Any additional linker flags to apply. Linker flags defined in the module itself will automatically be collected so this is typically not necessary. | |
strip | list | List of paths to strip from the target after downloading but before building it. | |
env | dict | Any env variables to set during build time. This can be useful to set CGO_CFLAGS etc. to control aspects of compilation. | |
patch | list or str | ||
build_tags | list | Any build tags to apply to the build context. |
go_repo
go_repo(module, version, download, name, install, requirements, licences, patch, visibility, deps, build_tags, third_party_path, strip, labels)
Adds a third party go module to the build graph as a subrepo. This is designed to be closer to how the `go.mod`
file works, requiring only the module name and version to be specified. Unlike go_module, each package is compiled
individually, and dependencies between packages are inferred by convention.
This build definition is designed to replace go_module(), requiring less toil to keep up to date, and improving
incrementalism and minimalism by compiling each package, rather than the whole module.
By convention, modules will be registered in subrepos of the same name, replacing forward slashes with
underscores, e.g. `github.com/stretchr/testify` becomes `github.com_stretchr_testify`. Assuming `go_repo` is
being used in the standard third party package, `//third_party/go`, the import path
`github.com/stretchr/testify/assert` is then always resolved to the build label
`///third_party/go/github.com_stretchr_testify//assert`. Similarly, binary targets are also generated for any "main"
package, which can be ran with `plz run` or used as tools e.g. to generate protobuf files.
To avoid cumbersome build labels, you may optionally pass a list of go package wildcards to the install argument of
this build definition. For example, passing in `name = "testify"`, and `install = ["assert"]`, you may depend on
`//third_party/go:testify`, instead of the individual packages within, e.g.
`///third_party/go/github.com_stretchr_testify//assert`
Argument | Required | Type | |
---|---|---|---|
module | yes | str | The name of the module |
version | str | The version of the module to download, if not providing the download parameter | |
download | str | A build rule to download the module, usually a go_mod_download(). | |
name | str | The name of the returned rule. Defaults to the module name with forward slashes replaced with underscores. | |
install | list | Optional list of package wildcards to return from this rule. This can be useful to avoid cumbersome labels when depending on this module. | |
requirements | list | A list of requirements of this module that are not defined in its go.mod file | |
licences | list | The licence of this module to be checked against the allowed licences configured in Please. | |
patch | list | Any patch files to apply to the downloaded module. | |
visibility | list | The visibility for the returned "install" rule. Doesn't affect the subrepo at all. | |
deps | list | Any deps on other rule kinds that provide packages, for example go_module(). This can be used to migrate to go_repo incrementally, one module at a time. | |
build_tags | list | Build tags to pass to the Go compiler. | |
third_party_path | str | Optional path of third_party directory. | |
strip | list | A list of directories to strip from the repo | |
labels | list | Labels for this rule. |
go_stdlib
go_stdlib(name, tags, labels, visibility)
Defines compilation of the Go standard library.
This is idiomatically configured in //third_party/go and set as the gostdlib config value for the Go plugin.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
tags | list | Go build tags (e.g. 'osusergo' or 'netgo' are relevant to the stdlib) | |
labels | list | Additional labels for this rule | |
visibility | list | Visibility of this rule |
go_system_toolchain
go_system_toolchain(name, cmd, architectures, tags, install_std, labels, visibility)
Defines a Go toolchain that's installed on the local system.
This is similar to using simply `go` as your gotool, but from 1.20 onwards it's necessary in order to
compile the standard library.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
cmd | str | Command to run to locate it (usually just 'go') | |
architectures | list | Architectures to build the standard library for | |
tags | list | Build tags to pass when installing the standard library. | |
install_std | bool | Whether we should build the standard library. On by default. | |
labels | list | Labels for this rule. | |
visibility | list | Visibility of this rule |
go_test
go_test(name, srcs, resources, data, deps, worker, visibility, flags, sandbox, cgo, filter_srcs, external, timeout, flaky, test_outputs, labels, size, static, definitions, env)
Defines a Go test rule.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
srcs | yes | list | Go source files to compile. |
resources | list | Files to embed in the library using //go:embed directives. | |
data | list or dict | Runtime data files for the test. | |
deps | list | Dependencies | |
worker | str | ||
visibility | list | Visibility specification | |
flags | str | Flags to apply to the test invocation. | |
sandbox | bool | Sandbox the test on Linux to restrict access to namespaces such as network. | |
cgo | bool | True if this test depends on a cgo_library. | |
filter_srcs | bool | If True, filters source files through Go's standard build constraints. | |
external | bool | True if this test is external to the library it's testing, i.e. it uses the feature of Go that allows it to be in the same directory with a _test suffix. | |
timeout | int | Timeout in seconds to allow the test to run for. | |
flaky | bool or int | True to mark the test as flaky, or an integer to specify how many reruns. | |
test_outputs | list | Extra test output files to generate from this test. | |
labels | list | Labels for this rule. | |
size | str | Test size (enormous, large, medium or small). | |
static | bool | If True, passes flags to the linker to try to force fully static linking. (specifically `-linkmode external -extldflags static`). Typically this increases size & link time a little but in return the binary has absolutely no external dependencies. Note that it may have negative consequences if the binary contains any cgo (including net/http DNS lookup code potentially). | |
definitions | str or list or dict | If set to a string, defines importpath.name=value when calling the Go linker. If set to a list, pass each value as a definition to the linker. If set to a dict, each key/value pair is used to contruct the list of definitions passed to the linker. | |
env | dict | Additional environment variables to set for the test |
go_test_main
go_test_main(name, srcs, test_package, test_only, external, deps, visibility, benchmark, cover, labels)
Outputs the main file for a Go test.
This essentially does the test discovery and templates out the entry point from it. Note that
it only generates the main; you will likely need to arrange for compilation of the inputs via
a separate go_library rule.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | yes | list | Source .go files that define the tests. |
test_package | str | This is the import path of the package to be tested. Defaults to the import path of the current directory. | |
test_only | bool | If True, can only be consumed by tests (or other test_only rules). | |
external | |||
deps | list | Any additional dependencies | |
visibility | list | Visibility of the rule. | |
benchmark | bool | If True, it will run benchmarks instead of tests. | |
cover | bool | Indicates whether this library should be considered for coverage annotations. Libraries are only annotated when using `plz cover` (or `plz build -c cover`), but if this is false they never will be. Can be useful for e.g. third-party code that you never want to be instrumented. | |
labels | list | Any labels to apply to this rule. |
go_toolchain
go_toolchain(name, url, version, hashes, labels, visibility, architectures, strip_srcs, tags, install_std)
Downloads Go and exposes :<name>|go and :<name>|gofmt as entry points. To use this rule add the
following to your .plzconfig:
[go]
GoTool = //.../<name>|go
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
url | str or dict | The URL used to download Go. Can be a single string or a dictionary mapping GOOS-GOARCH to URLs i.e. linux-amd64: 'https://...'. Either provide url or version, but not both. | |
version | str | The version of Go to download. Go will be downloaded from https://golang.org/dl/... and the rule will use the current platforms GOOS and GOARCH setting. Either provide url or version, but not both. | |
hashes | list | A list of possible hashes for the downloaded archive. Optional. | |
labels | list | Labels for this rule. | |
visibility | list | Visibility specification. Defaults to public. | |
architectures | list | Any additional architectures to install in go architecture format e.g. linux_amd64. This rule will automatically install the arch provided through --arch. This is only useful if you want to manually cross-compile parts of the repo but not others. | |
strip_srcs | bool | Whether to strip sources from the SDK which can reduce the size of the cached artifacts and improve performance, especially for remote execution. | |
tags | list | Build tags to pass when installing the standard library. | |
install_std | Whether we should install the standard library. This is required for go 1.20+. If not set, Please will do whatever is appropriate based on the Go version. |
merge_cgo_obj
merge_cgo_obj(name, a_rule, o_rule, visibility, test_only, tag, linker_flags, deps, exported_deps, provides, package, labels)
Argument | Required | Type | |
---|---|---|---|
name | yes | ||
a_rule | yes | ||
o_rule | |||
visibility | |||
test_only | |||
tag | |||
linker_flags | list | ||
deps | |||
exported_deps | |||
provides | |||
package | |||
labels | list |
[Plugin "go"]
-
CppCoverage (bool)
Whether to build C components with coverage
Defaults to
false
-
SplitDebugInfo (optional bool)
Split debug info for binaries into a separate, optional output.
-
FeatureFlags (repeatable optional string)
Flags to enable in-development features, or toggle breaking changes
If set, FeatureFlags is inherited from the host repo.
-
ArTool (string)
Path to the ar archiving tool to use
If set, ArTool is inherited from the host repo.
Defaults to
ar
-
GoTool (string)
A file path or build label for the go tool to use
If set, GoTool is inherited from the host repo.
Defaults to
go
-
Race (optional bool)
Compile for the Go race detector
If set, Race is inherited from the host repo.
Defaults to
false
-
TestRootCompat (bool)
Changes the test working directory to be the package to be more inline with how go test works
Defaults to
false
-
StripTool (string)
Tool to use to strip debug info. This is temporary and will be removed later!
If set, StripTool is inherited from the host repo.
Defaults to
eu-strip
-
BuildTags (repeatable optional string)
Build tags to pass to the Go compiler
-
GoCoverTool (optional string)
A file path or build label for the go cover tool to use. If not set, go_tool will be used to find it.
If set, GoCoverTool is inherited from the host repo.
-
Stdlib (optional string)
The build label for a go_stdlib target used to re-compile the standard library for different architectures and build modes.
If set, Stdlib is inherited from the host repo.
-
RequireLicences (bool)
If set, the licences field on go_module and go_repo will be mandatory
If set, RequireLicences is inherited from the host repo.
Defaults to
false
-
ValidateModuleVersion (bool)
If set, the values of go_mod_download's module and version parameters will be validated.
Defaults to
false
-
GoCompileTool (optional string)
A file path or build label for the go compile tool to use. If not set, go_tool will be used to find it.
If set, GoCompileTool is inherited from the host repo.
-
LegacyImports (bool)
Reverts back to the pre-v17 behavior of Please where packages could be imported as {dirname}/{package} rather than just {dirname}
Defaults to
False
-
Coverageredesign (bool)
Support Go 1.20's coverage redesign. This option now has no effect and will be removed in a future major version of the go-rules plugin.
If set, Coverageredesign is inherited from the host repo.
Defaults to
true
-
Buildmode (optional string)
The Go build mode to target (see `go help buildmode` for info)
-
CgoEnabled (optional bool)
If set, cgo will be enabled at build time.
If set, CgoEnabled is inherited from the host repo.
Defaults to
false
-
DelveTool (string)
The path to the delve tool used when debugging Go targets
If set, DelveTool is inherited from the host repo.
Defaults to
dlv
-
DefaultStatic (bool)
Whether to link binaries statically by default
If set, DefaultStatic is inherited from the host repo.
Defaults to
false
-
StripBinaries (optional bool)
Whether to strip generated Go binaries by default. This overrides the behaviour implied by the build mode - for example, building in dbg mode with this option set to true will still cause Go binaries to be stripped.
If set, StripBinaries is inherited from the host repo.
-
PkgInfo (bool)
Generate pkg info for Go targets
Defaults to
true
-
GoLinkTool (optional string)
A file path or build label for the go link tool to use. If not set, go_tool will be used to find it.
If set, GoLinkTool is inherited from the host repo.
-
PleaseGoTool (string)
A path or build label for the please_go tool, an internal tool used to help build Go code
If set, PleaseGoTool is inherited from the host repo.
Defaults to
//tools:please_go
-
CFlags (repeatable optional string)
Any additional C flags to pass to the C compiler when compling cgo rules
If set, CFlags is inherited from the host repo.
-
ModFile (optional string)
A built target for a go.mod, which can help avoid the need to pass modules via requirements to go_repo.
-
ImportPath (optional string)
The base import path when compiling first party Go code. This usually is set to the module name in go.mod.
-
CcTool (optional string)
The C compiler to use with cgo rules
If set, CcTool is inherited from the host repo.
Defaults to
cc
-
LdFlags (repeatable optional string)
Any additional linker flags to pass to the linker when linking cgo libraries
If set, LdFlags is inherited from the host repo.
Go proto rules
go_grpc_language
go_grpc_language()
Argument | Required | Type |
---|
go_grpc_library
go_grpc_library(name, srcs, deps, visibility, labels, test_only, root_dir, protoc_flags, additional_context)
Defines a rule for a go grpc library.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | yes | list | Input .proto files. |
deps | list | Dependencies (other grpc_library or proto_library rules) | |
visibility | list | Visibility specification for the rule. | |
labels | list | List of labels to apply to this rule. | |
test_only | bool | If True, this rule can only be used by test rules. | |
root_dir | str | The directory that the protos are compiled relative to. Useful if your proto files have import statements that are not relative to the repo root. | |
protoc_flags | list | Additional flags to pass to protoc. | |
additional_context | dict | This is unused. It will error if set |
go_proto_language
go_proto_language()
Argument | Required | Type |
---|
go_proto_library
go_proto_library(name, srcs, deps, visibility, labels, test_only, root_dir, protoc_flags, additional_context)
Compile a .proto file to generate code for golang.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | yes | list | Input .proto files. |
deps | list | Dependencies (other grpc_library or proto_library rules) | |
visibility | list | Visibility specification for the rule. | |
labels | list | List of labels to apply to this rule. | |
test_only | bool | If True, this rule can only be used by test rules. | |
root_dir | str | The directory that the protos are compiled relative to. Useful if your proto files have import statements that are not relative to the repo root. | |
protoc_flags | list | Additional flags to pass to protoc. | |
additional_context | dict | This is unused. It will error if set |
[Plugin "go_proto"]
-
GrpcPlugin (string)
Defaults to
grpc_go_plugin
-
ProtoDep (string)
Defaults to
//third_party/go:protobuf
-
GrpcDep (string)
Defaults to
//third_party/go:grpc
-
ProtoPlugin (string)
Defaults to
grpc_go_plugin
Java rules
java_binary
java_binary(name, main_class, out, srcs, deps, data, visibility, jvm_args, labels, self_executable, manifest, toolchain)
Compiles a .jar from a set of Java libraries.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
main_class | str | Main class to set in the manifest. | |
out | str | Name of output .jar file. Defaults to name + .jar. | |
srcs | list | Source files to compile. | |
deps | list | Dependencies of this rule. | |
data | list | Runtime data for this rule. | |
visibility | list | Visibility declaration of this rule. | |
jvm_args | str | Arguments to pass to the JVM in the run script. | |
labels | list | any labels to apply to this rule. | |
self_executable | bool | True to make the jar self executable. | |
manifest | str | Manifest file to put into the jar. Can't be passed at the same time as main_class. | |
toolchain | str | A label identifying a java_toolchain rule which will be used to build this Java binary. |
java_library
java_library(name, srcs, src_dir, resources, resources_root, deps, modular, exported_deps, visibility, test_only, javac_flags, labels, toolchain)
Compiles Java source to a .jar which can be collected by other rules.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | Java source files to compile for this library | |
src_dir | str | Directory containing Java source files to compile. | |
resources | list | Resources to include in the .jar file | |
resources_root | str | Root directory to treat resources relative to; ie. if we are in //project/main/resources and resources_root is project/main then the resources in the .jar will be in the subdirectory 'resources'. | |
deps | list | Dependencies of this rule. | |
modular | bool | Whether the produced file should be modular. Only supported with java 9+. | |
exported_deps | list | Exported dependencies, ie. dependencies that other things depending on this rule will also receive when they're compiling. This is quite important for Java; any dependency that forms part of the public API for your classes should be an exported dependency. | |
visibility | list | Visibility declaration of this rule. | |
test_only | bool | If True, this rule can only be depended on by tests. | |
javac_flags | list | List of flags passed to javac. | |
labels | list | Additional labels to apply to this rule. | |
toolchain | str | A label identifying a java_toolchain rule which will be used to build this java library. |
java_module
java_module(name, srcs, src_dir, resources, resources_root, deps, visibility, test_only, javac_flags, toolchain)
Compiles Java source to a modular .jar which can be collected by other rules.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | list | Java source files to compile for this library | |
src_dir | str | Directory containing Java source files to compile. | |
resources | list | Resources to include in the .jar file | |
resources_root | str | Root directory to treat resources relative to; ie. if we are in //project/main/resources and resources_root is project/main then the resources in the .jar will be in the subdirectory 'resources'. | |
deps | list | Dependencies of this rule. | |
visibility | list | Visibility declaration of this rule. | |
test_only | bool | If True, this rule can only be depended on by tests. | |
javac_flags | list | List of flags passed to javac. | |
toolchain | str | A label identifying a java_toolchain rule which will be used to build this java module. |
java_runtime_image
java_runtime_image(name, out, modules, launcher_module, launcher_class, compression, strip_hdrs, strip_man_pages, jlink_args, data, toolchain, visibility, deps)
Assembles a set of modules into an executable java runtime image.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
out | str | Name of the folder that contains the runtime image and the binary contained by it. Defaults to 'name'. | |
modules | yes | list | Modules to be included in the runtime image. |
launcher_module | str | The module to run in the launcher script. Has to be included in 'modules'. If omitted, no launcher script will be created. | |
launcher_class | str | The class within 'launcher_module' to run in the launcher script. Must be specified if 'launcher_module' is specified. | |
compression | int | the compression method to apply to resources. Refer to the jlink documentation for --compress for permitted values. Defaults to 2 (zip). | |
strip_hdrs | bool | Strip header files from runtime image. Defaults to True, since they are usually not needed at run time. | |
strip_man_pages | bool | Strip man pages from runtime image. Defaults to True. | |
jlink_args | str | Additional arguments to pass to jlink. | |
data | list | Deprecated, has no effect. | |
toolchain | str | The build target for a java_toolchain that will be used to build this image. If a toolchain is not defined, this rule falls back to using the jlink tool defined in the plugin configuration. | |
visibility | list | Visibility declaration of this rule. | |
deps | list | Dependencies of this rule. |
java_test
java_test(name, srcs, resources, resources_root, data, deps, labels, visibility, flags, sandbox, timeout, flaky, test_outputs, size, test_package, jvm_args, toolchain)
Defines a Java test.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
srcs | yes | list | Java files containing the tests. |
resources | list | Resources to include in the .jar file | |
resources_root | str | Root directory to treat resources relative to; ie. if we are in //project/main/resources and resources_root is project/main then the resources in the .jar will be in the subdirectory 'resources'. | |
data | list or dict | Runtime data files for this rule. | |
deps | list | Dependencies of this rule. | |
labels | list | Labels to attach to this test. | |
visibility | list | Visibility declaration of this rule. | |
flags | str | Flags to pass to the test invocation. | |
sandbox | bool | Sandbox the test on Linux to restrict access to namespaces such as network. | |
timeout | int | Maximum length of time, in seconds, to allow this test to run for. | |
flaky | bool or int | True to mark this as flaky and automatically rerun. | |
test_outputs | list | Extra test output files to generate from this test. | |
size | str | Test size (enormous, large, medium or small). | |
test_package | str | Java package to scan for test classes to run. | |
jvm_args | str | Arguments to pass to the JVM in the run script. | |
toolchain | str | A label identifying a java_toolchain rule which will be used to run this java test. |
java_toolchain
java_toolchain(name, jdk_url, jdk, hashes, jmod_includes, visibility)
This is an experimental feature and is subject to breaking changes in minor releases.
Defines a toolchain that downloads a JDK that can be used with java languages rules. This can be configured in your
.plzconfig via the config option java.toolchain.
This rule is aliased please_java_toolchain as well. When Bazel compatibility is enabled, this alias must be used
instead.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
jdk_url | str or dict | A URL to an archive containing a JDK distribution. Either this or jdk should be provided. | |
jdk | str | An archive of a jdk distribution or a label of a rule that produces one. Either this or jdk_url should be provided. | |
hashes | list | A list of valid hashes for the produced rule. | |
jmod_includes | dict | Additional files to insert into the JDK's JMOD archive files in the jmod/ directory. Keys are the names of archives without the .jmod extension (e.g. "java.base"), and values are dicts mapping paths within the archive to the files or build targets that provide them. | |
visibility | list | Visibility of this rule. Defaults to PUBLIC. |
maven_jar
maven_jar(name, id, repository, labels, hash, hashes, source_hashes, deps, visibility, filename, sources, licences, native, artifact_type, test_only, binary, classifier, classifier_sources_override)
Fetches a single Java dependency from Maven.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the output rule. |
id | yes | str | Maven id of the artifact (eg. org.junit:junit:4.1.0) |
repository | str or list | Maven repositories to fetch deps from. | |
labels | list | Additional labels to apply to this rule. | |
hash | str | Hash for produced rule. | |
hashes | list | List of hashes downloaded classes jar. | |
source_hashes | list or str | List of hashes for the downloaded sources jar. | |
deps | list | Labels of dependencies, as usual. | |
visibility | list | Visibility label. | |
filename | str | Filename we attempt to download. Defaults to standard Maven name. | |
sources | bool | True to download source jars as well. | |
licences | list | Licences this package is subject to. | |
native | bool | Attempt to download a native jar (i.e. add "-linux-x86_64" etc to the URL). | |
artifact_type | str | Type of artifact to download (defaults to jar but could be e.g. aar). | |
test_only | bool | If True, this target can only be used by tests or other test_only rules. | |
binary | bool | If True, we attempt to fetch and download an executable binary. The output is marked as such. Implies native=True and sources=False. | |
classifier | str | Maven classifier, allows to distinguish artifacts that were built from the same POM but differ in their content. | |
classifier_sources_override | str | Allows to override the classifier used to fetch the source artifact. e.g. logback-core-1.1.3-tests.jar and logback-core-1.1.3-test-sources.jar |
[Plugin "java"]
-
JavacTool (string)
Path to the Javac tool if not using java_toolchain
If set, JavacTool is inherited from the host repo.
Defaults to
javac
-
TargetLevel (string)
The target byte code language level
If set, TargetLevel is inherited from the host repo.
Defaults to
8
-
DefaultTestPackage (optional string)
The default package to find the test entry point in
If set, DefaultTestPackage is inherited from the host repo.
-
SourceLevel (string)
The source level to use
Defaults to
8
-
MavenRepo (repeatable string)
The maven repo to use for maven_jar
Defaults to
[[https://repo1.maven.org/maven2 https://repo.maven.apache.org/maven2]]
-
JavaTool (string)
Path to the Java tool if not using java_toolchain
If set, JavaTool is inherited from the host repo.
Defaults to
java
-
JavacFlags (optional string)
Any additional flags to pass to javac
If set, JavacFlags is inherited from the host repo.
-
JavacTestFlags (optional string)
Any additional flags to pass to javac for tests
If set, JavacTestFlags is inherited from the host repo.
-
JunitRunner (string)
The pass or build label for the junit test runner, a tool that runs .jar files containing junit tests
If set, JunitRunner is inherited from the host repo.
Defaults to
///java//tools:junit_runner
-
Toolchain (optional string)
The build label for the java_toolchain rule. Use this instead of Javac.
If set, Toolchain is inherited from the host repo.
-
RunSelfExecutablesWithJavaTool (string)
Run self-executable JAR files outputted by this plugin's rules with the Java tool (whether standalone or from a java_toolchain)
If set, RunSelfExecutablesWithJavaTool is inherited from the host repo.
Defaults to
False
-
JlinkTool (string)
Path to the jlink tool if not using java_toolchain
If set, JlinkTool is inherited from the host repo.
Defaults to
jlink
-
ReleaseLevel (optional string)
The release byte code level
If set, ReleaseLevel is inherited from the host repo.
-
Home (optional string)
Sets the java home variable
If set, Home is inherited from the host repo.
Proto rules
filter_srcs
filter_srcs(name, srcs, extension)
Argument | Required | Type | |
---|---|---|---|
name | yes | ||
srcs | yes | ||
extension | yes |
grpc_languages
grpc_languages()
Argument | Required | Type |
---|
grpc_library
grpc_library(name, srcs, deps, visibility, languages, labels, test_only, root_dir, protoc_flags)
Defines a rule for a grpc library.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | yes | list | Input .proto files. |
deps | list | Dependencies (other grpc_library or proto_library rules) | |
visibility | list | Visibility specification for the rule. | |
languages | list or dict | List of languages to generate rules for, chosen from the set {cc, py, go, java}. Alternatively, a dict mapping the language name to a definition of how to build it (see proto_language for more details of the values). | |
labels | list | List of labels to apply to this rule. | |
test_only | bool | If True, this rule can only be used by test rules. | |
root_dir | str | The directory that the protos are compiled relative to. Useful if your proto files have import statements that are not relative to the repo root. | |
protoc_flags | list | Additional flags to pass to protoc. |
merge_languages
merge_languages(lhs_dict, rhs_dict)
Argument | Required | Type | |
---|---|---|---|
lhs_dict | yes | ||
rhs_dict | yes |
proto_build_defs
proto_build_defs(name, srcs, proto_languages, visibility)
Argument | Required | Type | |
---|---|---|---|
name | yes | str | The name of this rule |
srcs | yes | str or list | |
proto_languages | yes | dict | A map of proto language types to functions that return the `proto_language()` below. e.g. `{"grpc_language": ["go_grpc_language"], "proto_language": ["go_proto_language"]}` where `go_grpc_language` is a function that has a `return proto_language(...)` |
visibility |
proto_language
proto_language(language, build_def, additional_provides)
Returns the definition of how to build a particular language for proto_library or grpc_library.
This should be wrapped in a function so that the proto_languages() build definition below can
Argument | Required | Type | |
---|---|---|---|
language | yes | str | Name of the language (as we would name it). |
build_def | yes | function | The build definition lambda. Will be called with the same arguments proto_library was called with, except with an additional `tag` parameter which is to be applied to the final build rule. Should return |
additional_provides | list or dict | Any additional tags from the rule generated by func that should be provided by the final proto_library rule. The _{name}#{language} tag will already be provided. Can be a dictionary if the provide key on the `proto_library` should differ from the language rule. In which case, the key will be the key on the proto_library, and the value will be the tag to provide from build_def. |
proto_languages
proto_languages()
Argument | Required | Type |
---|
proto_library
proto_library(name, srcs, deps, visibility, labels, languages, test_only, root_dir, protoc_flags, additional_context)
Compile a .proto file to generated code for various languages.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
srcs | yes | list | Input .proto files. |
deps | list | Dependencies | |
visibility | list | Visibility specification for the rule. | |
labels | list | List of labels to apply to this rule. | |
languages | list or dict | List of languages to generate rules for, chosen from the set {cc, py, go, java, js}. Alternatively, a dict mapping the language name to a definition of how to build it (see proto_language for more details of the values). | |
test_only | bool | If True, can only be used in test rules. | |
root_dir | str | The directory that the protos are compiled relative to. Useful if your proto files have import statements that are not relative to the repo root. | |
protoc_flags | list | Additional flags to pass to protoc. Note that these are inherited by further rules that depend on this one (because in nearly all cases that will be necessary for them to build too). | |
additional_context | dict | Additional language context to be passed to the `proto_language()` build definition. This can be used to provide language specific parameters. |
protoc_binary
protoc_binary(name, url, version, hashes, deps, visibility)
Downloads a precompiled protoc binary.
You will obviously need to choose a version that is available on Github - there aren't
necessarily protoc downloads for every protobuf release.
Argument | Required | Type | |
---|---|---|---|
name | yes | Name of the rule | |
url | str or dict | The URL used to download protoc. Can be a single string or a dictionary mapping HOSTOS-HOSTARCH to URLs i.e. linux-amd64: 'https://...'. Either provide url or version, but not both. | |
version | str | The version of protoc to download (e.g. '3.4.0'). Protoc will be downloaded from https://github.com/protocolbuffers/protobuf/releases/downaload/... and the rule will use the current platforms OS and ARCH setting. Either provide url or version, but not both. | |
hashes | Hashes to verify the download against. | ||
deps | Any other dependencies | ||
visibility | Visibility of the rule. |
protoc_plugins
protoc_plugins(name, build_defs, type, visibility)
Argument | Required | Type | |
---|---|---|---|
name | yes | str | The name of the rule |
build_defs | yes | list | Build rules outputting the .build_defs files that contain the proto_language() definitions. |
type | yes | str | The type of languages to collect. This should match the keys on the `proto_languages` dictionary passed to `proto_build_defs()`. |
visibility |
[Plugin "proto"]
-
LanguageDef (repeatable optional string)
A subinclude target containing a build definition that registers a new language using proto_language()
If set, LanguageDef is inherited from the host repo.
-
ProtocTool (string)
The protoc tool, as either a binary in the PATH or a build label
Defaults to
protoc
-
ProtocFlags (repeatable optional string)
Any additional flags to pass to protoc
Python rules
pip_library
pip_library(name, version, labels, hashes, package_name, test_only, deps, post_install_commands, install_subdirectory, repo, use_pypi, patch, visibility, zip_safe, licences, pip_flags, strip)
Provides a build rule for third-party dependencies to be installed by pip.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the build rule. |
version | yes | str | Specific version of the package to install. |
labels | list | Additional labels to apply to this rule. | |
hashes | list | List of acceptable hashes for this target. | |
package_name | str | Name of the pip package to install. Defaults to the same as 'name'. | |
test_only | bool | If True, can only be used by test rules or other test_only libraries. | |
deps | list | List of rules this library depends on. | |
post_install_commands | list | Commands run after pip install has completed. | |
install_subdirectory | str | Forces the package to install into a subdirectory with this name. | |
repo | str | Allows specifying a custom repo to fetch from. | |
use_pypi | bool | If True, will check PyPI as well for packages. | |
patch | str or list | A patch file or files to be applied after install. | |
visibility | list | Visibility declaration for this rule. | |
zip_safe | bool | Flag to indicate whether a pex including this rule will be zip-safe. | |
licences | list | Licences this rule is subject to. Default attempts to detect from package metadata. | |
pip_flags | str | List of additional flags to pass to pip. | |
strip | list | Files to strip after install. Note that these are done at any level. |
python_binary
python_binary(name, main, srcs, resources, out, deps, data, visibility, test_only, zip_safe, site, strip, interpreter, shebang, labels)
Generates a Python binary target.
This compiles all source files together into a single .pex file which can
be easily copied or deployed. The construction of the .pex is done in parts
by the dependent python_library rules, and this rule simply builds the
metadata for it and concatenates them all together.
This target can be debugged via:
plz debug [-o python.debugger:[pdb|debugpy]] [--port] //:target
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
main | yes | str | Python file which is the entry point and __main__ module. |
srcs | list | List of additional Python source files for this binary. | |
resources | list | List of static resources to include in the .pex. | |
out | str | Name of the output file. Default to name + .pex | |
deps | list | Dependencies of this rule. | |
data | list | Runtime data files for this rule. | |
visibility | list | Visibility specification. | |
test_only | bool | If True, can only be depended on by tests. | |
zip_safe | bool | Allows overriding whether the output is marked zip safe or not. If set to explicitly True or False, the output will be marked appropriately; by default it will be safe unless any of the transitive dependencies are themselves marked as not zip-safe. | |
site | bool | Allows the Python interpreter to import site; conversely if False, it will be started with the -S flag to avoid importing site. | |
strip | bool | Strips source code from the output .pex file, leaving just bytecode. | |
interpreter | str | The Python interpreter to use. Defaults to the value of the Python.DefaultInterpreter setting. | |
shebang | str | Exact shebang to apply to the generated file. By default we will determine something appropriate for the given interpreter. | |
labels | list | Labels to apply to this rule. |
python_library
python_library(name, srcs, resources, deps, visibility, test_only, zip_safe, labels, interpreter, strip)
Generates a Python library target, which collects Python files for use by dependent rules.
Note that each python_library performs some pre-zipping of its inputs before they're combined
in a python_binary or python_test. Hence while it's of course not required that all dependencies
of those rules are python_library rules, it's often a good idea to wrap any large dependencies
in one to improve incrementality (not necessary for pip_library, of course).
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
srcs | list | Python source files for this rule. | |
resources | list | Non-Python files that this rule collects which will be included in the final .pex. The distinction between this and srcs is fairly arbitrary and historical, but semantically quite nice and parallels python_test. | |
deps | list | Dependencies of this rule. | |
visibility | list | Visibility specification. | |
test_only | bool | If True, can only be depended on by tests. | |
zip_safe | bool | Should be set to False if this library can't be safely run inside a .pex (the most obvious reason not is when it contains .so modules). See python_binary for more information. | |
labels | list | Labels to apply to this rule. | |
interpreter | str | The Python interpreter to use. Defaults to the value of the Python.DefaultInterpreter setting. | |
strip | bool | If True, the original sources are stripped and only bytecode is output. |
python_multiversion_wheel
python_multiversion_wheel(name, version, urls, licences, visibility, hashes)
Downloads and combines multiple Python wheels.
Note that python 2 does not support versioned object file names, so this can only work
for one python 2 wheel at a time. For us that's not an issue since we only support 2.7
(and these days that's nearly always what people are using, so often not a big deal).
The wheels are downloaded from the given list of URLs Within those directories, and
combined into a single wheel. Later files will overwrite earlier files however these
common files should be identical if all the wheels are for the same version. The new
files will be the platform specific files.
Argument | Required | Type | |
---|---|---|---|
name | yes | Name of the rule. Also doubles as the name of the package if package_name is not set. | |
version | yes | str | |
urls | yes | list | List of wheels to download. |
licences | list | Licences that this wheel is subject to. | |
visibility | |||
hashes | list | List of hashes to verify the package against. These are applied to all downloads so don't need to be in any specific order. |
python_test
python_test(name, srcs, data, resources, deps, worker, labels, size, flags, visibility, sandbox, timeout, flaky, env, test_outputs, zip_safe, interpreter, site, test_runner)
Generates a Python test target.
This works very similarly to python_binary; it is also a single .pex file
which is run to execute the tests. The tests are run via either unittest, pytest, or behave, depending
on which is set for the test runner, which can be configured either via the python_test_runner
package property or python.testrunner in the config.
This target can be debugged via:
plz debug [-o python.debugger:[pdb|debugpy]] [--port] //:target
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
srcs | yes | list | Source files for this test. |
data | list or dict | Runtime data files for the test. | |
resources | list | Non-Python files to be included in the pex. Note that the distinction vs. srcs is important here; srcs are passed to unittest for it to run and it may or may not be happy if given non-Python files. | |
deps | list | Dependencies of this rule. | |
worker | str | Reference to worker script, A persistent worker process that is used to set up the test. | |
labels | list | Labels for this rule. | |
size | str | Test size (enormous, large, medium or small). | |
flags | str | Flags to apply to the test command. | |
visibility | list | Visibility specification. | |
sandbox | bool | Sandbox the test on Linux to restrict access to namespaces such as network. | |
timeout | int | Maximum time this test is allowed to run for, in seconds. | |
flaky | bool or int | True to mark this test as flaky, or an integer for a number of reruns. | |
env | dict | Environment variables to pass to the test | |
test_outputs | list | Extra test output files to generate from this test. | |
zip_safe | bool | Allows overriding whether the output is marked zip safe or not. If set to explicitly True or False, the output will be marked appropriately; by default it will be safe unless any of the transitive dependencies are themselves marked as not zip-safe. | |
interpreter | str | The Python interpreter to use. Defaults to the value of the Python.DefaultInterpreter setting. | |
site | bool | Allows the Python interpreter to import site; conversely if False, it will be started with the -S flag to avoid importing site. | |
test_runner | str | Specify which Python test runner to use for these tests. One of `unittest`, `pytest`, or a custom test runner entry point. |
python_wheel
python_wheel(name, version, labels, hashes, package_name, outs, post_install_commands, patch, licences, test_only, repo, zip_safe, visibility, deps, name_scheme, strip, binary, entry_points, tool, prereleases, tool_verbosity)
Downloads a Python wheel and extracts it.
This is a lightweight pip-free alternative to pip_library which supports cross-compiling.
Rather than leaning on pip which is difficult to achieve reproducible builds with and
support on different platforms, this rule is a simple wrapper around curl and unzip.
Wheel URLs are resolved in one or both of two ways:
* If `repo` is passed or `wheel_repo` is set in the .plzconfig, URLs are constructed using
`name_scheme` if passed, else `wheel_name_scheme` if set in the .plzconfig, else using some
reasonable defaults defined in _DEFAULT_WHEEL_NAME_SCHEMES.
* If `tool` is passed or `wheel_tool` is set in the .plzconfig, the tool is used to look up
URLs. If `repo` is also passed or `wheel_repo` is also set in the .plzconfig, the URLs
generated from the naming schemes are passed to the resolver tool.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. Also doubles as the name of the package if package_name is not set. |
version | yes | str | Version of the package to install. |
labels | list | Additional labels to apply to this rule. | |
hashes | list | List of hashes to verify the package against. | |
package_name | str | If given, overrides `name` for the name of the package to look for. | |
outs | list | List of output files. Defaults to a directory named the same as `name`. | |
post_install_commands | list | Commands to run after 'install'. | |
patch | str or list | Patch file to apply after install to fix any upstream code that has done bad things. | |
licences | list | Licences that this rule is subject to. | |
test_only | bool | If True, this library can only be used by tests. | |
repo | str | Repository to download wheels from. | |
zip_safe | bool | Flag to indicate whether a pex including this rule will be zip-safe. | |
visibility | list | Visibility declaration. | |
deps | list | Dependencies of this rule. | |
name_scheme | str or list | The templatized wheel naming scheme(s) (available template variables are `url_base`, `package_name`, `initial`, and `version`). | |
strip | list | Files to strip after install. Note that these are done at any level. | |
binary | Whether this wheel should be executable. This assumes that the wheel will contain a __main__ module with a main() function. If this is not the case, then entry_points should be used. | ||
entry_points | Any entry points into this wheel. These relate to the entrypoints.txt in the dist-info of the wheel, which define a module, and function in the format "module.path:function". This parameter can be a string, in which case the rule can be ran directly, or a dictionary, for example `{"protoc", "protoc.__main__:main"}. For the latter, each key can be ran using annotated labels, e.g. `plz run //third_party/python:protobuf|protoc` | ||
tool | str | Tool to locate python wheel file in an index | |
prereleases | bool | ||
tool_verbosity | str |
[Plugin "python"]
-
InterpreterOptions (string)
Any additional flags to pass to the python interpreter
-
TestrunnerBootstrap (string)
-
ModuleDir (string)
The path to the third party python directory, in python import path format e.g. third_party.py3 for //third_party/py3
Defaults to
third_party.python
-
DefaultPipRepo (optional string)
The default repository to look for pip dependencies in
-
WheelTool (optional string)
The tool used to resolve wheels with using the pypi API.
If set, WheelTool is inherited from the host repo.
-
WheelNameScheme (repeatable optional string)
A format string for the wheel repo URL. Format fields url_base, package_name, initial, and version. Initial is the first character of the package name.
-
Verbosity (optional string)
Passes verbosity level to wheel_tool, for example: wheel_tool --verbosity info
Defaults to
info
-
PipFlags (optional string)
Any additional flags to pass to pip
-
PipCompileFlags (optional string)
Flags to pass to pip when compiling
If set, PipCompileFlags is inherited from the host repo.
-
WheelRepo (optional string)
The root URL for the wheel repo
-
Prereleases (bool)
Allow prereleased versions in python_wheel targets
Defaults to
false
-
PipTool (optional string)
The tool to use for pip. Defaults to using python -m pip
If set, PipTool is inherited from the host repo.
-
UsePypi (bool)
Whether to use PyPi as a repository for python_wheel
Defaults to
true
-
DisableVendorFlags (bool)
Disables any vendor specific flags e.g. the --system flag passed to debians fork of pip
If set, DisableVendorFlags is inherited from the host repo.
Defaults to
false
-
DefaultInterpreter (string)
If set, DefaultInterpreter is inherited from the host repo.
Defaults to
python3
-
PexTool (string)
A path or build label for the pex tool, which is used to create .pex files from python sources
If set, PexTool is inherited from the host repo.
Defaults to
//tools:please_pex
-
TestRunner (string)
The test runner to use e.g. unittest or pytest
Defaults to
unittest
-
TestrunnerDeps (string)
A label for a build target containting the dependencies of the test runner
Defaults to
//third_party/python:unittest_bootstrap
-
Debugger (string)
The debugger to use when debugging python binaries
If set, Debugger is inherited from the host repo.
Defaults to
pdb
-
RequireLicences (bool)
If set, the licences field on pip_library and python_wheel will be mandatory
If set, RequireLicences is inherited from the host repo.
Defaults to
false
-
FeatureFlags (repeatable optional string)
Flags to enable in-development features, or toggle breaking changes
If set, FeatureFlags is inherited from the host repo.
Python proto rules
[Plugin "python_proto"]
-
ProtoPlugin (string)
If set, ProtoPlugin is inherited from the host repo.
Defaults to
grpc_python_plugin
-
ProtoDep (string)
If set, ProtoDep is inherited from the host repo.
Defaults to
//third_party/python:protobuf
-
GrpcDep (string)
If set, GrpcDep is inherited from the host repo.
Defaults to
//third_party/python:grpc
Shell rules
rules for creating .sh files
sh_binary
sh_binary(name, main, out, deps, data, visibility, labels)
Generates a shell script binary.
It assumes that unzip is in your path.
The resulting script will contain three things:
1) Code necessary to unzip dependent files.
2) The user defined shell script.
3) The zipfile containing all dependent files.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
main | yes | str or list | The script to execute after all files have been uncompressed |
out | str | Name of the output file to create. Defaults to name + .sh. | |
deps | list | Dependencies of this rule | |
data | list | Runtime data for this rule. | |
visibility | list | Visibility declaration of the rule. | |
labels | list | List of labels. |
sh_cmd
sh_cmd(name, cmd, srcs, data, out, shell, labels, deps, visibility, expand_env_vars, test_only)
Generates a runnable shell script from a command.
This is doable with a genrule with a little effort but it's awkward enough to be nice
to have a builtin.
The command is subject to Please's usual variable expansion at build time. Note that if
you want `plz run` to transparently work and refer to other files, you may need to use
$(out_location ...) instead of $(location ...).
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
cmd | yes | str or dict or list | Command to write into the output script file. The commands are subject to shell expansion during build time by default. If that is to be avoided, set expand_env_vars to False, or escape the variables with \\\$, i.e. \\\${@}. |
srcs | list or dict | Source files. Can be consumed as env variables by the generated command (but are not written into the output in any other way). | |
data | list | Runtime data for this rule. | |
out | str | Name of the output file to create. Defaults to name + .sh. | |
shell | str | Shell to invoke in, by default /bin/sh. | |
labels | list | Labels to apply to this rule. | |
deps | list | Any dependencies for this rule. These can be consumed as env variables in the cmd but are not used in any other way. | |
visibility | list | Visibility declaration of the rule. | |
expand_env_vars | bool | Whether to expand | |
test_only | bool | If True, this rule can only be depended on by tests. |
sh_library
sh_library(name, src, deps, visibility, labels)
Generates a shell script binary, essentially just the given source.
Note that these are individually executable so can only have one source file each.
This is a bit tedious and would be nice to improve sometime.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule. |
src | yes | str | Source file for the rule. |
deps | list | Dependencies of this rule. | |
visibility | list | Visibility declaration of the rule. | |
labels | list | List of labels. |
sh_test
sh_test(name, src, labels, data, deps, worker, size, visibility, flags, flaky, test_outputs, timeout, sandbox)
Generates a shell test. Note that these aren't packaged in a useful way.
Argument | Required | Type | |
---|---|---|---|
name | yes | str | Name of the rule |
src | str | Test script file. | |
labels | list | Labels to apply to this test. | |
data | list or dict | Runtime data for the test. | |
deps | list | Dependencies of this rule | |
worker | str | Reference to worker script, A persistent worker process that is used to set up the test. | |
size | str | Test size (enormous, large, medium or small). | |
visibility | list | Visibility declaration of the rule. | |
flags | str | Flags to apply to the test invocation. | |
flaky | bool or int | True to mark this as flaky and automatically rerun. | |
test_outputs | list | Extra test output files to generate from this test. | |
timeout | int | Maximum length of time, in seconds, to allow this test to run for. | |
sandbox | bool | Sandbox the test on Linux to restrict access to namespaces such as network. |