name: env
long_name: Environment
description: |
  This object is returned by [[environment]] and stores
  detailed information about how environment variables should be set.
  It should be passed as the `env` keyword argument to tests and other functions.

  *Since 0.58.0* [[env.append]] and [[env.prepend]] can be called multiple times
  on the same `varname`. Earlier Meson versions would warn and only the last
  operation took effect.

  *Since 1.5.0* This object becomes immutable after first use. This means that
  calling append(), prepend() or set() will cause a deprecation warning if this
  object has already been used in any function arguments. However, assignment
  creates a mutable copy.

example: |
  ```meson
  env = environment()

  # MY_PATH will be '0:1:2:3'
  env.set('MY_PATH', '1')
  env.append('MY_PATH', '2')
  env.append('MY_PATH', '3')
  env.prepend('MY_PATH', '0')

  # Deprecated since 1.5.0
  run_command('script.py', env: env)
  env.append('MY_PATH', '4')

  # Allowed and only env2 is modified
  env2 = env
  env2.append('MY_PATH', '4')
  ```

methods:
- name: append
  returns: void
  description: |
    appends the given values to
    the old value of the environment variable, e.g.  `env.append('FOO',
    'BAR', 'BAZ', separator : ';')` produces `BOB;BAR;BAZ` if `FOO` had
    the value `BOB` and plain `BAR;BAZ` if the value was not defined.

  posargs:
    variable:
      type: str
      description: The variable to modify

  varargs:
    type: str
    name: Value
    description: The values to append

  kwargs:
    separator:
      type: str
      description: |
        The separator to use. If not explicitly specified, the default path
        separator for the host operating system will be used, i.e. ';' for
        Windows and ':' for UNIX/POSIX systems.

- name: prepend
  returns: void
  description: Same as `append` except that it writes to the beginning of the variable.

  posargs:
    variable:
      type: str
      description: The variable to modify

  varargs:
    type: str
    name: Value
    description: The values to prepend

  kwargs_inherit: env.append

- name: set
  returns: void
  description: |
    Sets the environment variable
    specified in the first argument to the values in the varargs
    joined by the separator. For instance, `env.set('FOO', 'BAR'),` sets envvar
    `FOO` to value `BAR`.

  posargs:
    variable:
      type: str
      description: The variable to modify

  varargs:
    type: str
    name: Value
    description: The values to set

  kwargs_inherit: env.append

- name: unset
  returns: void
  since: 1.4.0
  description: |
    Unset the specified environment variable. If this variable does not exist,
    nothing happens.