Initial documentation for Environments #17096
Conversation
stuhood
force-pushed
the
stuhood/environment-docs-draft
branch
from
d25991b
to
3021ae4
Compare
stuhood
force-pushed
the
stuhood/environment-docs-draft
branch
2 times, most recently
from
18e19bd
to
709a11f
Compare
stuhood
force-pushed
the
stuhood/environment-docs-draft
branch
from
709a11f
to
905fecb
Compare
stuhood
force-pushed
the
stuhood/environment-docs-draft
branch
from
905fecb
to
8c12c51
Compare
| _TODO: Like https://github.com/pantsbuild/pants/issues/15764, but for tests._ | ||
|
|
||
| _TODO: Give an example of using `environment=` vs `runtime_environment=` to use docker only for test execution, but not for building of thirdparty dependencies by using PEX to cross-build. This will require exposing options out of PEX to override (?) the target platform, and figuring out how that doesn't break `check` is an open question._ |
There was a problem hiding this comment.
So: I'm pretty sure that we should avoid stabilizing environments until we have figured out exactly how to implement a cross-build like this. Many other very useful workflows are enabled, but this one in particular feels like it requires a bit more design work.
This is additionally covered by #8384.
|
|
||
| > 🚧 Environment compatibility | ||
| > | ||
| > Currently, there is no static validation that a target's environment is compatible with its dependencies' environments -- only the implicit validation of the goals that you run successfully against those targets (`check`, `lint`, `test`, `package`, etc). |
There was a problem hiding this comment.
Do we provide static validation of runtime configurations when we're not using environments? If not, then this is probably likely to be more confusing than illuminating.
There was a problem hiding this comment.
We do for resolves, interpreter_constraints, etc. So yea, sortof.
|
|
||
| Environment targets have fields (target arguments) which correspond to options which are marked "environment-aware". When an option is environment-aware, the value of the option that will be used in an environment can be overridden by setting the corresponding field value on the environment target for that environment. If an environment target does not set a value, it defaults to the value which is set globally via options values. | ||
|
|
||
| For example, the [`[python-bootstrap].search_path` option](doc:reference-python-bootstrap#search_path) is environment-aware, which is indicated in its help. It can be overridden for a particular environment by a corresponding environment target field, such as [the one on `local_environment`](doc:reference-local_environment#codepython_bootstrap_search_pathcode). |
There was a problem hiding this comment.
It would probably help to have a BUILD file example where you set this, and then have a comment in it saying "this overrides the option [python-bootstrap].search_path
People tend to really benefit from examples
|
|
||
| ## Consuming environments | ||
|
|
||
| To declare which environment they should build with, many target types (but particularly "root" targets like tests or binaries) have an `environment=` field: for example, [`python_tests(environment=..)`](doc:reference-python_tests#codeenvironmentcode). |
There was a problem hiding this comment.
Is this sentence going to soon be stale?
There was a problem hiding this comment.
Unclear: we'll learn more during the alpha and rcs I expect.
stuhood
force-pushed
the
stuhood/environment-docs-draft
branch
from
8c12c51
to
3521354
Compare
|
Applied review feedback, but haven't addressed the TODOs yet. |
|
|
||
| To declare which environment they should build with, many target types (but particularly "root" targets like tests or binaries) have an `environment=` field: for example, [`python_tests(environment=..)`](doc:reference-python_tests#codeenvironmentcode). | ||
|
|
||
| The `environment=` field may either: |
There was a problem hiding this comment.
Are target field names referred to with the trailing equal sign else where (besides this PR)? It feels like a new (i.e. inconsistent) thing to me..
There was a problem hiding this comment.
I guess that it is a convention that I'm trying to start.
I'm not really sure that end users know what a "field" is otherwise... most users probably think of the arguments to targets as ... arguments.
There was a problem hiding this comment.
Perhaps we could have a glossary page listing terminology and syntax for how we typically refer to them, such as target field names always being on the form of field_name=, if we also do that in messages from pants that would make it more clear with fewer words in many cases I believe.
[ci skip-rust] [ci skip-build-wheels]
# Rust tests and lints will be skipped. Delete if not intended. [ci skip-rust] # Building wheels and fs_util will be skipped. Delete if not intended. [ci skip-build-wheels]
stuhood
force-pushed
the
stuhood/environment-docs-draft
branch
from
3521354
to
ff9a75b
Compare
|
Ok folks: I think that this is ready to go. Please take another look. |
stuhood
changed the title
| ```python BUILD | ||
| pex_binary( | ||
| name="main", | ||
| environment="python_bullseye", |
There was a problem hiding this comment.
This should show the pants.toml imo. Generally, I recommend maybe adding -tgt to the target name for all these env targets in this page. It's way too easy to think that environment="target name" rather than name as defined in pants.toml
Adds initial documentation for the Environments feature designed and implemented in #7735 and #13682.
This initial version is meant to capture what will be possible in the
2.15.xrelease, but it will/should contain some references to future work (some of which should block stabilizing environments).Fixes #13682, and fixes #16393.
[ci skip-rust]
[ci skip-build-wheels]