EnvVars

EnvVars is a class that represents an instance of environment variables for a given system. It is obtained from the generic Environment class.

This class is used by other tools like the conan.tools.gnu autotools helpers and the VirtualBuildEnv and VirtualRunEnv generator.

Creating environment files

EnvVars object can generate environment files (shell, bat or powershell scripts):

def generate(self):
    env1 = Environment()
    env1.define("foo", "var")
    envvars = env1.vars(self)
    envvars.save_script("my_env_file")

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_env_file.bat for Windows systems or my_env_file.sh otherwise.

In Windows, it is possible to opt-in to generate Powershell .ps1 scripts instead of .bat ones, using the conf tools.env.virtualenv:powershell=True.

Also, by default, Conan will automatically append that launcher file path to a list that will be used to create a conanbuild.bat|sh|ps1 file aggregating all the launchers in order. The conanbuild.sh|bat|ps1 launcher will be created after the execution of the generate() method.

The scope argument ("build" by default) can be used to define different scope of environment files, to aggregate them separately. For example, using a scope="run", like the VirtualRunEnv generator does, will aggregate and create a conanrun.bat|sh|ps1 script:

def generate(self):
    env1 = Environment()
    env1.define("foo", "var")
    envvars = env1.vars(self, scope="run")
    # Will append "my_env_file" to "conanrun.bat|sh|ps1"
    envvars.save_script("my_env_file")

You can also use scope=None argument to avoid appending the script to the aggregated conanbuild.bat|sh|ps1:

env1 = Environment()
env1.define("foo", "var")
# Will not append "my_env_file" to "conanbuild.bat|sh|ps1"
envvars = env1.vars(self, scope=None)
envvars.save_script("my_env_file")

Running with environment files

The conanbuild.bat|sh|ps1 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 of self.run():

...
def build(self):
    # This will automatically wrap the "foo" command with the correct environment:
    # source my_env_file.sh && foo
    # my_env_file.bat && foo
    # powershell my_env_file.ps1 ; cmd c/ foo
    self.run("foo", env=["my_env_file"])

Applying the environment variables

As an alternative to running a command, environments can be applied in the python environment:

from conan.tools.env import Environment

env1 = Environment()
env1.define("foo", "var")
envvars = env1.vars(self)
with envvars.apply():
   # Here os.getenv("foo") == "var"
   ...

Iterating the variables

You can iterate the environment variables of an EnvVars object like this:

env1 = Environment()
env1.append("foo", "var")
env1.append("foo", "var2")
envvars = env1.vars(self)
for name, value in envvars.items():
    assert name == "foo":
    assert value == "var var2"

The current value of the environment variable in the system is replaced in the returned value. This happens when variables are appended or prepended. If a placeholder is desired instead of the actual value, it is possible to use the variable_reference argument with a jinja template syntax, so a string with that resolved template will be returned instead:

env1 = Environment()
env1.append("foo", "var")
envvars = env1.vars(self)
for name, value in envvars.items(variable_reference="$penv{{{name}}}""):
    assert name == "foo":
    assert value == "$penv{{foo}} var"

Warning

In Windows, there is a limit to the size of environment variables, a total of 32K for the whole environment, but specifically the PATH variable has a limit of 2048 characters. That means that the above utils could hit that limit, for example for large dependency graphs where all packages contribute to the PATH env-var.

This can be mitigated by:

  • Putting the Conan cache closer to C:/ for shorter paths

  • Better definition of what dependencies can contribute to the PATH env-var

  • Other mechanisms for things like running with many shared libraries dependencies with too many .dlls, like deployers

Reference

class EnvVars(conanfile, values, scope)

Represents an instance of environment variables for a given system. It is obtained from the generic Environment class.

get(name, default=None, variable_reference=None)

get the value of a env-var

Parameters:

  • name – The name of the environment variable.

  • default – The returned value if the variable doesn’t exist, by default None.

  • variable_reference – if specified, use a variable reference instead of the pre-existing value of environment variable, where {name} can be used to refer to the name of the variable.

items(variable_reference=None)

returns {str: str} (varname: value)

Parameters:

variable_reference – if specified, use a variable reference instead of the pre-existing value of environment variable, where {name} can be used to refer to the name of the variable.

apply()

Context manager to apply the declared variables to the current os.environ restoring the original environment when the context ends.

save_script(filename)

Saves a script file (bat, sh, ps1) with a launcher to set the environment. If the conf “tools.env.virtualenv:powershell” is set to True it will generate powershell launchers if Windows.

Parameters:

filename – Name of the file to generate. If the extension is provided, it will generate the launcher script for that extension, otherwise the format will be deduced checking if we are running inside Windows (checking also the subsystem) or not.