env
===

.. py:module:: env

.. autoapi-nested-parse::

   Global environment and platform information support.

   This package provide a class called Env used to store global
   information. Env is a singleton so there is in fact only one instance.



Attributes
----------

.. autoapisummary::

   env.logger
   env.CANADIAN_EXCEPTIONS
   env.BaseEnv_T


Classes
-------

.. autoapisummary::

   env.EnvInfo
   env.AbstractBaseEnv
   env.BaseEnv
   env.Env


Module Contents
---------------

.. py:data:: logger

.. py:data:: CANADIAN_EXCEPTIONS
   :value: (('x86-windows', 'x86_64-windows'), ('sparc-solaris', 'sparc64-solaris'))


.. py:class:: EnvInfo

   Bases: :py:obj:`tuple`


   .. py:attribute:: build


   .. py:attribute:: host


   .. py:attribute:: target


.. py:class:: AbstractBaseEnv(build: e3.platform.Platform | None = None, host: e3.platform.Platform | None = None, target: e3.platform.Platform | None = None)

   Environment Handling.

   Abstract class to factorize code between BaseEnv and Env.
   :ivar build: current build Platform
   :vartype build: Platform
   :ivar host: current host Platform
   :vartype host: Platform
   :ivar target: current target Platform
   :vartype target: Platform
   :ivar main_options: The command-line switches, after parsing by
   the e3.Main class (see the documentation of that class).


   .. py:method:: _initialized() -> bool
      :abstractmethod:


      Whether the new instance should be initialized.

      This is mostly useful to implement a singleton, as done in Env()



   .. py:method:: _items() -> Iterable
      :abstractmethod:


      Return the list of instance variables.



   .. py:property:: platform
      :type: str


      Compute the platform name based on the host and the target.

      For example for target ppc-elf hosted on linux, platform will
      be ppc-elf-linux. So the concept of platform embed both target
      and host concept.



   .. py:property:: is_canadian
      :type: bool


      Return true if this is a canadian configuration.



   .. py:property:: is_cross
      :type: bool


      Return true if this is a cross configuration.



   .. py:method:: set_build(name: str | None = None, version: str | None = None, machine: str | None = None, mode: str | None = None, cores: int | None = None) -> None

      Set build platform.

      :param name: a string that identify the system to be considered
          as the build. If None then build is unchanged. Note that passing
          an empty value will force the autodetection and possibly reset to
          the default value.
      :param version: a string containing the system version. If set
          to None the version is either a default or autodetected when
          possible
      :param machine: a string containing the name of the target
          machine.
      :param mode: a string containing the name of the mode. This
          notion is needed on some targets such as VxWorks to switch between
          kernel mode and other modes such as rtp
      :param cores: force a number of apparent cores. If None that number
          is either computed (when possible) or set to 1.

      When calling set_build, the target and host systems are reset to the
      build one. Thus you should call set_build before calling either
      set_host or set_target.



   .. py:method:: set_host(name: str | None = None, version: str | None = None, machine: str | None = None, mode: str | None = None, cores: int | None = None) -> None

      Set host platform.

      :param name: a string that identify the system to be considered
          as the host. If None then host is set to the build one (the
          autodetected platform). If set to 'build' or 'target' then host
          is set respectively to current 'build' or 'target' value
      :param version: a string containing the system version. If set to
          None the version is either a default or autodetected when possible
      :param machine: a string containing the name of the target
          machine.
      :param mode: a string containing the name of the mode. This
          notion is needed on some targets such as VxWorks to switch between
          kernel mode and other modes such as rtp
      :param cores: force a number of apparent cores. If None that number
          is either computed (when possible) or set to 1.

      When calling set_host, the target system is reset to the host one.
      Thus you should call set_host before set_target otherwise your call
      to set_target will be ignored. Note also that is the host_name is
      equal to the build platform, host_version will be ignored.



   .. py:method:: set_target(name: str | None = None, version: str | None = None, machine: str | None = None, mode: str | None = None, cores: int | None = None) -> None

      Set target platform.

      :param name: a string that identify the system to be considered
          as the host. If None then host is set to the host one. If set to
          'build' or 'host' then target is set respectively to current
          'build' or 'host' value. In that case target_version and
          target_machine are ignored.
      :param version: a string containing the system version. If set
          to None the version is either a default or autodetected when
          possible.
      :param machine: a string containing the name of the target
          machine.
      :param mode: a string containing the name of the mode. This
          notion is needed on some targets such as VxWorks to switch between
          kernel mode and other modes such as rtp
      :param cores: force a number of apparent cores. If None that number
          is either computed (when possible) or set to 1.

      The target parameters are ignored if the target_name is equal to the
      host platform.



   .. py:method:: set_env(build: str | None = None, host: str | None = None, target: str | None = None) -> None

      Set build/host/target.

      :param build: string as passed to --build option
      :param host: string as passed to --host
      :param target: string as passed to --target



   .. py:method:: str_triplet() -> EnvInfo

      Return a triplet of strings suitable to call set_env.

      :return: a namedtuple suitable for a call to set_env



   .. py:method:: cmd_triplet() -> list[str]

      Return command line parameters corresponding to current env.

      :return: a list of command line parameters



   .. py:method:: get_attr(name: str, default_value: Any = None, forced_value: Any = None) -> Any

      Return an attribute value.

      :param name: name of the attribute to check. Name can contain '.'
      :param default_value: returned value if forced_value not set and the
          attribute does not exist
      :param forced_value: if not None, this is the return value

      :return: the attribute value

      This function is useful to get the value of optional functions
      parameters whose default value might depend on the environment.



   .. py:method:: add_path(path: str, append: bool = False) -> None
      :classmethod:


      Set a path to PATH environment variable.

      :param path: path to add
      :param append: if True append, otherwise prepend. Default is prepend



   .. py:method:: add_search_path(env_var: str, path: str, append: bool = False) -> None
      :classmethod:


      Add a path to the env_var search paths.

      :param env_var: the environment variable name (e.g. PYTHONPATH,
          LD_LIBRARY_PATH, ...)
      :param path: path to add
      :param append: if True append, otherwise prepend. Default is prepend



   .. py:property:: dll_path_var
      :type: str



   .. py:method:: add_dll_path(path: str, append: bool = False) -> None

      Add a path to the dynamic libraries search paths.

      :param path: path to add
      :param append: if True append, otherwise prepend. Default is prepend



   .. py:property:: discriminants
      :type: list[str]


      Compute discriminants.

      :return: the list of discriminants associated with the current context
          (target, host, ...). This is mainly used for testsuites to ensure a
          coherent set of base discriminants.



   .. py:property:: tmp_dir
      :type: str


      Return current temporary directory.

      :return: a path

      The function looks for several variables ``TMPDIR``, ``TMP``
      and in case none of these variables are defined fallback on
      on ``/tmp``.



   .. py:method:: to_dict() -> dict

      Get current env as a dictionary.

      :return: the dictionary entries are all strings and thus the result
          can be used to format string. For example ``Env().target.os.name``
          will appear with the key ``target_os_name``, ...



   .. py:method:: from_platform_name(platform: str) -> AbstractBaseEnv | None
      :classmethod:


      Return a BaseEnv object from a platform name.

      That's the reverse of platform property



.. py:data:: BaseEnv_T

.. py:class:: BaseEnv(build: e3.platform.Platform | None = None, host: e3.platform.Platform | None = None, target: e3.platform.Platform | None = None)

   Bases: :py:obj:`AbstractBaseEnv`


   BaseEnv.


   .. py:attribute:: _initialized
      :value: False


      Whether the new instance should be initialized.

      This is mostly useful to implement a singleton, as done in Env()



   .. py:attribute:: _instance
      :type:  dict[str, Any]


   .. py:attribute:: _context
      :type:  list[Any]
      :value: []



   .. py:method:: __setattr__(name: str, value: Any) -> None


   .. py:method:: __getattr__(name: str) -> None


   .. py:method:: _items() -> Iterable[Any]

      Return the list of instance variables.



   .. py:method:: copy(build: str | None = None, host: str | None = None, target: str | None = None) -> BaseEnv_T

      Copy an env.

      :param build: like build set_env parameter
      :param host: like host set_env parameter
      :param target: like target set_env parameter
      :return: a deep copy of the current env



   .. py:method:: from_env(env: Env | BaseEnv | None = None) -> BaseEnv_T
      :classmethod:


      Return a new BaseEnv object from an env.

      :param env: env. If None copy the current Env



.. py:class:: Env

   Bases: :py:obj:`AbstractBaseEnv`


   Env shows the current environment in used.

   Env is a singleton holding the current environment and platform
   information. It is set by e3.main when the --build/--host/--target option
   are passed to the command line and can be then changed by calling
   py:meth:`set_build`, py:meth:`set_host`, and py:meth:`set_target`.


   .. py:attribute:: _instance
      :type:  dict[str, Any]


   .. py:attribute:: _context
      :type:  list[Any]
      :value: []



   .. py:property:: _initialized
      :type: bool


      Whether the new instance should be initialized.

      This is mostly useful to implement a singleton, as done in Env()



   .. py:method:: __setattr__(name: str, value: Any) -> None


   .. py:method:: __getattr__(name: str) -> Any


   .. py:method:: _items() -> Iterable[Any]

      Return the list of instance variables.



   .. py:method:: store(filename: str | None = None) -> None

      Save environment into memory or file.

      :param filename: a string containing the path of the filename in which
          the environment will be saved. If set to None the environment is
          saved into memory in a stack like structure.



   .. py:method:: restore(filename: str | None = None) -> None

      Restore environment from memory or a file.

      :param filename: a string containing the path of the filename from
          which the environment will be restored. If set to None the
          environment is pop the last saved one



