conan-io / conan-io/docs

Improve documentation regarding custom `scope` in `EnvVars` and `env` argument of `self.run`

Open
#2,710 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
125
Forks
382
Avg merge
22h 39m
Merged PRs (30d)
21

Description

In https://docs.conan.io/en/1.51/reference/conanfile/tools/env/envvars.html#creating-environment-files, it is explained how to aggregate calls of scripts in `conanbuild` script with `scope="build"`, or in `conanrun` script with `scope="run"`.

Actually in https://github.com/conan-io/conan-center-index/pull/12598, I wanted to inject some variables in a specific scope without polluting `build` or `run` scopes, then refer to it in `self.run`. And the documentation is not very clear, I had to make some extrapolations based on documentation, and finally get a working solution.

- Please explain that you can use any custom `scope` name, aggregating the calls of one or several scripts in a script `conan`. And then you can refer to it in `env` argument of `self.run` with `conan`. Currently documentation is too focused on the built-in `build` & `run` scopes (except one sentence in https://docs.conan.io/en/1.51/reference/conanfile/tools/env/environment.html#obtaining-environment-variables), which can be misleading.

- Also it would be nice to explain how to create a custom `scope` aggregating custom scripts and script of `VirtualBuildEnv` (again to not pollute `build` scope), while still having the script of `VirtualBuildEnv` in `build` scope.
So basically is it possible to pass an array of values to `scope` argument so that a script can be wrapped in several `scope`? Something like this maybe:

```python
def generate(self):
env1 = VirtualBuildEnv(self)
env1.generate(scope=["build", "custom"])

env2 = Environment()
env2.define("FOO", "bar")
env2vars = env2.vars(self, scope="custom")
env2vars.save_script("custom_env_file")

def build(self):
self.run("...") # I need build scope here (implicit), but I do not want FOO
self.run("...", env="conancustom") # I need my custom scope which contains my FOO variable & variables from VirtualBuildEnv
```

- https://docs.conan.io/en/1.51/reference/conanfile/tools/env/environment.html#variable-declaration should say that you can also give a python array of paths to `define_path`, `append_path` and `prepend_path`, and that it's properly translated to corresponding syntax depending on build OS.

- It is not clear whether `buildenv_info` of `tool_requires` (and `runenv_info` of their `requires`) coming from a host profile are automatically injected in `build` scope (regardless of recipe generators since obviously a recipe should be agnostic to these profile details) or not.

- Could you clarify whether `buildenv_info` of "internal" `tool_requires` of a recipe (I mean not coming from a host profile, but hardcoded in the recipe) are automatically injected to `build` scope or if it requires an explicit `VirtualBuildEnv` in generators?
If explicit `VirtualBuildEnv` is required, maybe add a big rule of thumb stating that as soon as a recipe has at least one `tool_requires`, it should have `VirtualBuildEnv` in its generators?

- The documentation doesn't explain in which methods of conan v2 build helpers (`conan.tools.cmake.CMake`, `conan.tools.meson.Meson` etc) `conanbuild` is automatically called.

- The documentation doesn't say whether variables from `VirtualRunEnv` are automatically injected in `configure()` method of `Autotools` helper when there is `AutotoolsDeps` and in case of native build, so that `configure` can succeed in case of shared dependencies (if native build, autotools configuration runs test executables to check working compiler, and if `LIBS` has been populated with shared libs, it fails if this test executable can't find these shared libs at runtime).
If it's not automatically handled, it would be a very good idea to explain that recipes authors must inject `VirtualRunEnv` in `build` scope if: autotools will call configure AND there are dependencies AND `AutotoolsDeps` is in generators AND not cross-building.

- Finally, some code examples are incorrect. `Environment(self)` is invalid, it's `Environment()` (at least in conan 1.51.3).

(by the way I've also tried `scope=None`, and it raised an error:

```
ERROR: emsdk/3.1.18: Error in generate() method, line 73
envvars = env.vars(self, scope=None)
AttributeError: 'NoneType' object has no attribute 'startswith'
```
)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.