These tools are still experimental (so subject to breaking changes) but with very stable syntax. We encourage their usage to be prepared for Conan 2.0.
Available since: 1.35.0
Environment is a generic class that helps defining modifications to the environment variables.
This class is used by other tools like the conan.tools.gnu autotools helpers and
the VirtualBuildEnv and VirtualRunEnv
generator. It is important to highlight that this is a generic class, to be able to use it, a specialization
for the current context (shell script, bat file, path separators, etc), a
EnvVars object needs to be obtained
from conan.tools.env import Environment def generate(self): 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.remove("MYVAR3", "MyValue3") # Remove the MyValue3 from MYVAR3 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
The “normal” variables (the ones declared with
prepend) will be appended with a space,
by default, but the
separator argument can be provided to define a custom one.
The “path” variables (the ones declared with
prepend_path) will be appended
with the default system path separator, either
;, but it also allows defining which one.
Environments can be composed:
from conan.tools.env import Environment env1 = Environment() env1.define(...) env2 = Environment() env2.append(...) env1.compose_env(env2) # env1 has priority, and its modifications will prevail
Obtaining environment variables¶
You can obtain an
EnvVars object with the
vars() method like this:
from conan.tools.env import Environment def generate(self): env = Environment() env.define("MYVAR1", "MyValue1") envvars = env.vars(self, scope="build") # use the envvars object
scope is equal
"build", which means that if this
envvars generate a script to
activate the variables, such script will be automatically added to the
conanbuild.sh|bat one, for
users and recipes convenience. Conan generators use
run scope, but it might be possible
to manage other scopes too.
There are some other places where
Environment can be defined and used:
- In recipes
package_info()method, in new
self.runenv_info, this environment will be propagated via
VirtualRunEnvrespectively to packages depending on this recipe.
- In generators like
AutotoolsToolchain, that need to define environment for the current recipe.
- In profiles new [buildenv] section.
The definition in
package_info() is as follow, taking into account that both
are objects of
from conan 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"))