multi-config env

reference/conanfile/tools/env/environment.rst

@@ -74,35 +74,55 @@ Environments can generate launcher files:
 
 .. code:: python
 
-    env1 = Environment(self)
-    env1.define("foo", "var")
-    env1.save_script("my_launcher")
+    def generate(self):
+        env1 = Environment(self)
+        env1.define("foo", "var")
+        env1.save_script("my_launcher")
 
 
+Although it potentially could be used in other methods, this functionality is intended to work in the ``generate()``
+method.
+
 It will generate automatically a ``my_launcher.bat`` for Windows systems or ``my_launcher.sh`` otherwise.
 
 Also, by default, Conan will automatically append that launcher file path to a list that will be used to
-create a ``conan_env.bat/sh`` file aggregating all the launchers in order. The ``conan_env.sh/bat`` launcher
+create a ``conanbuild.bat|sh`` file aggregating all the launchers in order. The ``conanbuild.sh/bat`` launcher
 will be created after the execution of the ``generate()`` method.
 
-The ``conan_env.bat/sh`` launcher will be executed by default before calling every ``self.run`` command.
-You can change the default launcher with the `env` argument:
+The ``conanbuild.bat/sh`` launcher will be executed by default before calling every ``self.run()`` command. This
+would be typically done in the ``build()`` method.
+
+You can change the default launcher with the ``env`` argument:
 
 .. code:: python
 
     ...
-    # This will automatically wrap the "foo" command with the correct launcher:
-    # my_launcher.sh && foo
-    self.run("foo", env=["my_launcher"])
+    def build(self):
+        # This will automatically wrap the "foo" command with the correct launcher:
+        # my_launcher.sh && foo
+        self.run("foo", env=["my_launcher"])
+
+The ``group`` argument (``"build"`` by default) can be used to define different groups of environment files, to
+aggregate them separately. For example, using a ``group="run"``, like the ``VirtualRunEnv`` generator does, will
+aggregate and create a ``conanrun.bat|sh`` script:
+
+.. code:: python
+
+    def generate(self):
+        env1 = Environment(self)
+        env1.define("foo", "var")
+        # Will append "my_launcher" to "conanrun.bat|sh"
+        env1.save_script("my_launcher", group="run")
 
 
-You can also use ``auto_activate=False`` argument to avoid appending the script to the aggregated ``conan_env.bat/sh``:
+You can also use ``group=None`` argument to avoid appending the script to the aggregated ``conanbuild.bat|sh``:
 
 .. code:: python
 
     env1 = Environment(self)
     env1.define("foo", "var")
-    env1.save_script("my_launcher", auto_activate=False)
+    # Will not append "my_launcher" to "conanbuild.bat|sh"
+    env1.save_script("my_launcher", group=None)
 
 
 

reference/conanfile/tools/env/virtualbuildenv.rst

@@ -45,6 +45,22 @@ That information is collected from the direct ``build_requires`` in "build" cont
 definition plus the ``self.runenv_info`` of the transitive dependencies of those ``build_requires``.
 
 
+This generator (for example the invocation of ``conan install cmake/3.20.0@ -g VirtualBuildEnv --build-require``)
+will create the following files:
+
+- conanbuildenv-release-x86_64.(bat|sh): This file contains the actual definition of environment variables
+  like PATH, LD_LIBRARY_PATH, etc, and any other variable defined in the dependencies ``buildenv_info``
+  corresponding to the ``build`` context, and to the current installed
+  configuration. If a repeated call is done with other settings, a different file will be created.
+- conanbuild.(bat|sh): Accumulates the calls to one or more other scripts, in case there are multiple tools
+  in the generate process that create files, to give one single convenient file for all. This only calls
+  the latest specific configuration one, that is, if ``conan install`` is called first for Release build type,
+  and then for Debug, ``conanbuild.(bat|sh)`` script will call the Debug one.
+
+After the execution of one of those files, a new deactivation script will be generated, capturing the current
+environment, so the environment can be restored when desired. The file will be named also following the
+current active configuration, like ``deactivate_conanbuildenv-release-x86_64.bat``.
+
 Constructor
 +++++++++++
 
@@ -60,10 +76,10 @@ generate()
 
 .. code:: python
 
-    def generate(self, auto_activate=True):
+    def generate(self, group="build"):
 
 
 Parameters:
 
-    * **auto_activate** (Defaulted to ``True``): Add the launcher automatically to the ``conanenv`` launcher. Read more
+    * **group** (Defaulted to ``"build"``): Add the launcher automatically to the ``conanbuild`` launcher. Read more
       in the :ref:`Environment documentation <conan_tools_env_environment_model>`.

reference/conanfile/tools/env/virtualrunenv.rst

@@ -46,6 +46,18 @@ the compiled executables and applications. The information is obtained from the
 deduced from the ``self.cpp_info`` definition of the package, to define ``PATH``, ``LD_LIBRARY_PATH``, ``DYLD_LIBRARY_PATH``
 and ``DYLD_FRAMEWORK_PATH`` environment variables.
 
+This generator will create the following files:
+
+- conanrunenv-release-x86_64.(bat|sh): This file contains the actual definition of environment variables
+  like PATH, LD_LIBRARY_PATH, etc, and ``runenv_info`` of dependencies corresponding to the ``host`` context,
+  and to the current installed configuration. If a repeated call is done with other settings, a different file will be created.
+- conanrun.(bat|sh): Accumulates the calls to one or more other scripts to give one single convenient file
+  for all. This only calls the latest specific configuration one, that is, if ``conan install`` is called first for Release build type,
+  and then for Debug, ``conanrun.(bat|sh)`` script will call the Debug one.
+
+After the execution of one of those files, a new deactivation script will be generated, capturing the current
+environment, so the environment can be restored when desired. The file will be named also following the
+current active configuration, like ``deactivate_conanrunenv-release-x86_64.bat``.
 
 
 Constructor
@@ -63,10 +75,10 @@ generate()
 
 .. code:: python
 
-    def generate(self, auto_activate=True):
+    def generate(self, group="run"):
 
 
 Parameters:
 
-    * **auto_activate** (Defaulted to ``True``): Add the launcher automatically to the ``conanenv`` launcher. Read more
+    * **group** (Defaulted to ``run``): Add the launcher automatically to the ``conanrun`` launcher. Read more
       in the :ref:`Environment documentation <conan_tools_env_environment_model>`.

reference/conanfile/tools/microsoft.rst

@@ -304,9 +304,9 @@ generate()
 
 .. code:: python
 
-    def generate(self, auto_activate=True):
+    def generate(self, group="build"):
 
 Parameters:
 
-    * **auto_activate** (Defaulted to ``True``): Add the launcher automatically to the ``conanenv`` launcher. Read more
+    * **group** (Defaulted to ``"build"``): Add the launcher automatically to the ``conanbuild`` launcher. Read more
       in the :ref:`Environment documentation <conan_tools_env_environment_model>`.