diff --git a/.gitignore b/.gitignore index 0567a562d54..f3af9eb4a0c 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,6 @@ __pycache__/ # Distribution / packaging .Python -env/ _build/ develop-eggs/ dist/ diff --git a/reference/conanfile/tools.rst b/reference/conanfile/tools.rst index 5ef1fcc2146..b62a59f7704 100644 --- a/reference/conanfile/tools.rst +++ b/reference/conanfile/tools.rst @@ -40,4 +40,5 @@ Contents: tools/meson tools/microsoft tools/qbs + tools/env tools/files diff --git a/reference/conanfile/tools/env.rst b/reference/conanfile/tools/env.rst new file mode 100644 index 00000000000..1c557f07577 --- /dev/null +++ b/reference/conanfile/tools/env.rst @@ -0,0 +1,9 @@ +conan.tools.env +=============== + + +.. toctree:: + :maxdepth: 2 + + env/environment + env/virtualenv diff --git a/reference/conanfile/tools/env/environment.rst b/reference/conanfile/tools/env/environment.rst new file mode 100644 index 00000000000..a6daf0b93ec --- /dev/null +++ b/reference/conanfile/tools/env/environment.rst @@ -0,0 +1,78 @@ +Environment +=========== + +.. warning:: + + This is a **very experimental** feature and it will have breaking changes in future releases. + + +``Environment`` is a class that helps defining modifications to the environment variables. This class is +used by other tools like the ``conan.tools.gnu`` autotools helpers. + +It allows different operations like: + +.. code:: python + + from conan.tools.env import Environment + + env = Environment() + env.define("MYVAR1", "MyValue1") # Overwrite previously existing MYVAR1 with new value + env.append("MYVAR2", "MyValue2") # Append to existing MYVAR2 the new value + env.prepend("MYVAR3", "MyValue3") # Prepend to existing MYVAR3 the new value + env.unset("MYVAR4") # Remove MYVAR4 definition from environment + + # And the equivalent with paths + env.define_path("MYPATH1", "path/one") # Overwrite previously existing MYPATH1 with new value + env.append_path("MYPATH2", "path/two") # Append to existing MYPATH2 the new value + env.prepend_path("MYPATH3", "path/three") # Prepend to existing MYPATH3 the new value + +Normal variables will be appended by default with space, but ``separator`` argument can be provided to define +a custom one. +Path variables will be appended with the default system path separator, either ``:`` or ``;``, but it also +allows defining which one. + +Environments can compose: + +.. code:: python + + from conan.tools.env import Environment + + env1 = Environment() + env1.define(...) + env2 = Environment() + env2.append(...) + + env1.compose(env2) # env1 has priority, and its modifications will prevail + + +There are some places where this ``Environment`` is used: + +- In recipes ``package_info()`` method, in new ``self.buildenv_info`` and ``self.runenv_info``. +- In other generators like ``AutootoolsDeps`` and ``AutotoolsToolchain`` that need to define environment +- In profiles new ``[buildenv]`` and ``[runenv]`` sections. + + +The definition in ``package_info()`` is as follow, taking into account that both ``self.buildenv_info`` and ``self.runenv_info`` +are objects of ``Environment()`` class. + + +.. code:: python + + from conans import ConanFile + + class App(ConanFile): + name = "mypkg" + version = "1.0" + settings = "os", "arch", "compiler", "build_type" + + def package_info(self): + # This is information needed by consumers to build using this package + self.buildenv_info.append("MYVAR", "MyValue") + self.buildenv_info.prepend_path("MYPATH", "some/path/folder") + + # This is information needed by consumers to run apps that depends on this package + # at runtime + self.runenv_info.define("MYPKG_DATA_DIR", os.path.join(self.package_folder, + "datadir")) + + diff --git a/reference/conanfile/tools/env/virtualenv.rst b/reference/conanfile/tools/env/virtualenv.rst new file mode 100644 index 00000000000..98ba7d9900a --- /dev/null +++ b/reference/conanfile/tools/env/virtualenv.rst @@ -0,0 +1,44 @@ +VirtualEnv +========== + +.. warning:: + + This is a **very experimental** feature and it will have breaking changes in future releases. + + +The ``VirtualEnv`` generator can be used by name in conanfiles: + +.. code-block:: python + :caption: conanfile.py + + class Pkg(ConanFile): + generators = "VirtualEnv" + +.. code-block:: text + :caption: conanfile.txt + + [generators] + VirtualEnv + +And it can also be fully instantiated in the conanfile ``generate()`` method: + +.. code-block:: python + :caption: conanfile.py + + from conans import ConanFile + from conan.tools.env import VirtualEnv + + class Pkg(ConanFile): + settings = "os", "compiler", "arch", "build_type" + requires = "zlib/1.2.11", "bzip2/1.0.8" + + def generate(self): + ms = VirtualEnv(self) + ms.generate() + +When the ``VirtualEnv`` generator is used, calling ``conan install`` will generate files containing environment variables information: + + +- *conanbuildenv* .bat or .sh scripts, that are automatically loaded if existing by the ``self.run()`` recipes methods. *conanbuildenv* is the build time environment information. It is collected from the direct ``build_requires`` in "build" context recipes from the ``self.buildenv_info`` definition plus the ``self.runenv_info`` of the transitive dependencies of those ``build_requires``. +- *conanrunenv* .bat or .sh scripts, that can be explicitly opted-in in ``self.run()`` recipes methods with ``self.run(..., env=["conanrunenv"])``. *conanrunenv* is the runtime environment information, anything that is necessary in the environment to actually run the compiled executables and applications. +- In both cases, whenever the runtime environment information is necessary, it wil also be automatically 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.