8000 README improvements (#239) · discord/rules_python@f46e953 · GitHub
[go: up one dir, main page]
Skip to content {"props":{"docsUrl":"https://docs.github.com/get-started/accessibility/keyboard-shortcuts"}}

Commit f46e953

Browse files
brandjonbrandjon
authored
README improvements (bazel-contrib#239)
Follow-up to bazel-contrib#237. Moves development workflow info to CONTRIBUTING.md. Fixes the instructions for how to use the Bazel Federation.
1 parent 5aa465d commit f46e953

File tree

3 files changed

+82
-48
lines changed

3 files changed

+82
-48
lines changed

‎CONTRIBUTING.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,43 @@ use GitHub pull requests for this purpose. Consult [GitHub Help] for more
2222
information on using pull requests.
2323

2424
[GitHub Help]: https://help.github.com/articles/about-pull-requests/
25+
26+
## Generated files
27+
28+
Some checked-in files are generated and need to be updated when a new PR is
29+
merged.
30+
31+
### Documentation
32+
33+
To regenerate the content under the `docs/` directory, run this script in the
34+
repository root:
35+
36+
```shell
37+
./update_docs.sh
38+
```
39+
40+
This needs to be done whenever the docstrings in the corresponding .bzl files
41+
are changed; see `docs/BUILD`.
42+
43+
### Precompiled tools
44+
45+
The packaging rules depend on two precompiled binaries, `tools/piptool.par` and
46+
`tools/whltool.par`. We need these to be precompiled because they are invoked
47+
during `WORKSPACE` evaluation, before Bazel itself is able to build anything
48+
from source. The .par files can be regenerated by running this script in the
49+
repository root:
50+
51+
```shell
52+
# You can pass --nodocker if Docker is not available on your system.
53+
./update_tools.sh
54+
```
55+
56+
This needs to be done whenever the corresponding sources in the `packaging/`
57+
directory are updated.
58+
59+
Since these are binary files and therefore unreviewable, for security
60+
reasons<sup>1</sup> we will regenerate the .par files for you when merging your
61+
pull request.
62+
63+
<sup>1</sup> See "[Reflections on Trusting Trust](https://en.wikipedia.org/wiki/Backdoor_(computing)#Compiler_backdoors)".
64+

‎README.md

Lines changed: 38 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -31,21 +31,44 @@ The packaging rules (`pip_import`, etc.) are less stable. We may make breaking
3131
changes as they evolve. There are no guarantees for rules underneath the
3232
`experimental/` directory.
3333

34+
See the [How to contribute](CONTRIBUTING.md) page for information on our
35+
devlopment workflow.
36+
3437
## Getting started
3538

3639
To import rules_python in your project, you first need to add it to your
3740
`WORKSPACE` file. If you are using the [Bazel
38-
Federation](https://github.com/bazelbuild/bazel-federation), you will want to
39-
copy the boilerplate in the rules_python release's notes, under the "WORKSPACE
40-
setup" heading. This will look something like the following:
41+
Federation](https://github.com/bazelbuild/bazel-federation), you just need to
42+
[import the Federation](https://github.com/bazelbuild/bazel-federation#example-workspace)
43+
and call the rules_python setup methods:
4144

4245
```python
4346
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
47+
48+
http_archive(
49+
name = "bazel_federation",
50+
url = "https://github.com/bazelbuild/bazel-federation/releases/download/0.0.1/bazel_federation-0.0.1.tar.gz",
51+
sha256 = "506dfbfd74ade486ac077113f48d16835fdf6e343e1d4741552b450cfc2efb53",
52+
)
53+
54+
load("@bazel_federation//:repositories.bzl", "rules_python_deps")
55+
56+
rules_python_deps()
57+
load("@bazel_federation//setup:rules_python.bzl", "rules_python_setup")
58+
rules_python_setup(use_pip=True)
59+
```
60+
61+
Note the `use_pip` argument: rules_python may be imported either with or
62+
without support for the packaging rules.
63+
64+
If you are not using the Federation, you can simply import rules_python
65+
directly and call its initialization methods as follows:
66+
67+
```python
4468
http_archive(
4569
name = "rules_python",
46-
# NOT VALID: Replace with actual version and SHA.
47-
url = "https://github.com/bazelbuild/rules_python/releases/download/<RELEASE>/rules_python-<RELEASE>.tar.gz",
48-
sha256 = "<SHA>",
70+
url = "https://github.com/bazelbuild/rules_python/releases/download/0.0.1/rules_python-0.0.1.tar.gz",
71+
sha256 = "aa96a691d3a8177f3215b14b0edc9641787abaaa30363a080165d06ab65e1161",
4972
)
5073
load("@rules_python//python:repositories.bzl", "py_repositories")
5174
py_repositories()
@@ -54,32 +77,32 @@ load("@rules_python//python:pip.bzl", "pip_repositories")
5477
pip_repositories()
5578
```
5679

57-
Otherwise, you may import rules_python in a standalone way by copying the
58-
following:
80+
To depend on a particular unreleased version (not recommended), you can
81+
use `git_repository` instead of `http_archive`:
5982

6083
```python
6184
load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
85+
6286
git_repository(
6387
name = "rules_python",
6488
remote = "https://github.com/bazelbuild/rules_python.git",
6589
# NOT VALID: Replace with actual Git commit SHA.
6690
commit = "{HEAD}",
6791
)
68-
load("@rules_python//python:repositories.bzl", "py_repositories")
69-
py_repositories()
70-
# Only needed if using the packaging rules.
71-
load("@rules_python//python:pip.bzl", "pip_repositories")
72-
pip_repositories()
92+
93+
# Then load and call py_repositories() and possibly pip_repositories() as
94+
# above.
7395
```
7496

75-
Either way, you can then load the core rules in your `BUILD` files with:
97+
Once you've imported the rule set into your WORKSPACE using any of these
98+
methods, you can then load the core rules in your `BUILD` files with:
7699

77100
``` python
78101
load("@rules_python//python:defs.bzl", "py_binary")
79102

80103
py_binary(
81104
name = "main",
82-
...
105+
srcs = ["main.py"],
83106
)
84107
```
85108

@@ -168,36 +191,3 @@ started](#Getting-started) above.
168191
Note that Starlark-defined bundled symbols underneath
169192
`@bazel_tools//tools/python` are also deprecated. These are not yet rewritten
170193
by buildifier.
171-
172-
## Development
173-
174-
### Documentation
175-
176-
The content underneath `docs/` is generated. To update the documentation,
177-
simply run this in the root of the repository:
178-
179-
```shell
180-
./update_docs.sh
181-
```
182-
183-
### Precompiled .par files
184-
185-
The `piptool.par` and `whltool.par` files underneath `tools/` are compiled
186-
versions of the Python scripts under the `packaging/` directory. We need to
187-
check in built artifacts because they are executed during `WORKSPACE`
188-
evaluation, before Bazel itself is able to build anything from source.
189-
190-
The .par files need to be regenerated whenever their sources are updated. This
191-
can be done by running
192-
193-
```shell
194-
# You can pass --nodocker if Docker is not available on your system.
195-
./update_tools.sh
196-
```
197-
198-
from the repository root. However, since these files contain compiled code,
199-
we do not accept commits that modify them from untrusted sources.<sup>1</sup>
200-
If you submit a pull request that modifies the sources and we accept the
201-
changes, we will regenerate these files for you before merging.
202-
203-
<sup>1</sup> See "[Reflections on Trusting Trust](https://en.wikipedia.org/wiki/Backdoor_(computing)#Compiler_backdoors)".

‎WORKSPACE

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@ workspace(name = "rules_python")
1616

1717
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
1818

19+
# Load our production dependencies using the federation, except that instead of
20+
# calling rules_python() (which would define the @rules_python repo), we just
21+
# call rules_python_deps().
22+
1923
http_archive(
2024
name = "bazel_federation",
2125
url = "https://github.com/bazelbuild/bazel-federation/releases/download/0.0.1/bazel_federation-0.0.1.tar.gz",

0 commit comments

Comments
 (0)
0