-
-
Notifications
You must be signed in to change notification settings - Fork 636
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Initial documentation for Environments #17096
Initial documentation for Environments #17096
Conversation
d25991b
to
3021ae4
Compare
18e19bd
to
709a11f
Compare
709a11f
to
905fecb
Compare
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note the following:
- The subsystem/options namespace is called
environments-preview
(notenvironments
) - The specifier field is called
_environment
(notenvironment
)
|
||
> 🚧 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We do for resolve
s, interpreter_constraints
, etc. So yea, sortof.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks! Probably would be good to update options.md
too to mention "environment specific options"
|
||
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this sentence going to soon be stale?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Unclear: we'll learn more during the alpha and rcs I expect.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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]
3521354
to
ff9a75b
Compare
Ok folks: I think that this is ready to go. Please take another look. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm. thanks for this comprehensive write up. :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks!
```python BUILD | ||
pex_binary( | ||
name="main", | ||
environment="python_bullseye", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.x
release, 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]