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

[SpaceIm]

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<scopename>. And then you can refer to it in env argument of self.run with conan<scopename>. 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:

  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'

)