diff --git a/reference/conanfile/tools/env/environment.rst b/reference/conanfile/tools/env/environment.rst index 650a7269511..5cbd92f26ed 100644 --- a/reference/conanfile/tools/env/environment.rst +++ b/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) diff --git a/reference/conanfile/tools/env/virtualbuildenv.rst b/reference/conanfile/tools/env/virtualbuildenv.rst index 6e92ba8fd35..84b9101cc7b 100644 --- a/reference/conanfile/tools/env/virtualbuildenv.rst +++ b/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 `. diff --git a/reference/conanfile/tools/env/virtualrunenv.rst b/reference/conanfile/tools/env/virtualrunenv.rst index 5ab69f21133..1978fbedaac 100644 --- a/reference/conanfile/tools/env/virtualrunenv.rst +++ b/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 `. diff --git a/reference/conanfile/tools/microsoft.rst b/reference/conanfile/tools/microsoft.rst index 08b897ea039..f3ad4d48600 100644 --- a/reference/conanfile/tools/microsoft.rst +++ b/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 `.