:py:mod:`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. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: env.EnvInfo env.AbstractBaseEnv env.BaseEnv env.Env Attributes ~~~~~~~~~~ .. autoapisummary:: env.logger env.BITS_64 env.CANADIAN_EXCEPTIONS env.BaseEnv_T .. py:data:: logger .. py:data:: BITS_64 :value: 64 .. py:data:: CANADIAN_EXCEPTIONS :value: (('x86-windows', 'x86_64-windows'), ('sparc-solaris', 'sparc64-solaris')) .. py:class:: EnvInfo Bases: :py:obj:`NamedTuple` Store build, host and target platform information. .. py:attribute:: build :type: e3.platform.Platform .. py:attribute:: host :type: e3.platform.Platform .. py:attribute:: target :type: e3.platform.Platform .. 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: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:property:: dll_path_var :type: str Dll path var. .. 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:: _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() -> collections.abc.Iterable :abstractmethod: Return the list of instance variables. .. 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: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: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 :param platform: platform name string .. 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 .. py:method:: __setattr__(name: str, value: Any) -> None Set an attribute. :param name: attribute name :param value: attribute value .. py:method:: __getattr__(name: str) -> None Get an attribute. :param name: attribute name .. py:method:: _items() -> collections.abc.Iterable[Any] Return the list of instance variables. .. py:method:: copy(build: str | None = None, host: str | None = None, target: str | None = None) -> typing_extensions.Self 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) -> typing_extensions.Self :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:property:: _initialized :type: bool Whether the new instance should be initialized. This is mostly useful to implement a singleton, as done in Env() .. py:attribute:: _instance :type: ClassVar[dict[str, Any]] .. py:attribute:: _context :type: ClassVar[list[Any]] :value: [] .. py:method:: __setattr__(name: str, value: Any) -> None Set an attribute. :param name: attribute name :param value: attribute value .. py:method:: __getattr__(name: str) -> Any Get an attribute. :param name: attribute name .. py:method:: _items() -> collections.abc.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