Kevin Daughtridge

boxenator.Context reference

Boxenator specifications are Python scripts. Before they are executed, a global boxenator.Context instance, box, is defined. All specifications are made through its attributes and methods, as described below.

boxenator may also be imported as a module. The Context class is the only public member of the module; its __init__ takes no extra arguments. A future version may explicity support target extensions.

A depatom is a DEPEND atom which specifies one or more packages, as defined in the ebuild(5) man page.

Contents

Portage behaviour

enable_feature (*features=str)
Enables each specified Portage feature in FEATURES.
add_mirror (*mirrors=str)
Adds each specified distfiles mirror URI to GENTOO_MIRRORS. This is intended for official Portage mirrors; local servers should be specified with add_local_mirror ().
add_local_mirror (host=str)
Adds each specified host URI as a "local" (unofficial) Portage distfiles mirror.
add_type_mirror (mirror_type=str, host=str)
Adds a host URI to the distfiles mirrors for type mirror_type. Mirror types (e.g. "kernel", "sourceforge") are referenced from ebuilds as mirror://type/, and are enumerated in /usr/portage/profiles/thirdpartymirrors.
add_overlay (*overlays=str)
Adds each specified Portage tree overlay path to PORTDIR_OVERLAY.
add_category (category=str)
Adds a custom Portage category category.
set_env (envvar=str, value=str)
Sets envvar to value in the global Portage environment.

Global settings

arch
This attribute stores the Portage architecture being targeted, if already set. It does not produce output, and should not be set directly (use set_arch ()).
set_arch (arch=str)
Sets the targeted Portage architecture to arch.
accept_arch (arch=str)
Adds a specified Portage architecture arch to the ACCEPT_KEYWORDS list of accepted architecture keywords. The targeted system architecture is accepted implicitly.
accept_unstable ()
Adds the targeted architecture with the "~" unstable specifier (e.g. ~x86) to the ACCEPT_KEYWORDS list. The targeted architecture must have been specified with set_arch ().
add_cflag (*cflags=str)
add_cxxflag (*cxxflags=str)
Adds each specified cflag or cxxflag to the list of global CFLAGS or CXXFLAGS.
mask_install (*files=str)
Adds each specified file to the INSTALL_MASK list of files and paths that will not be installed from packages.
add_lingua (*linguas=str)
Adds each specified language code lingua to the list of LINGUAS for which data should be installed. Each lingua may be any type of language code (e.g. fr, fr_FR, or fra) used by ebuilds. get_linguas () may return any code type, but the output LINGUAS list will only include language codes of the fr and fr_FR types.
get_linguas ([length=int])
Returns a list of language codes which have been added with add_lingua (). If length is specified, only language codes of that string length will be returned. This allows filtering for specific code types.

USE flags

enable_use (*useflags=str)
disable_use (*useflags=str)
Enables or disables each specified useflag in the global USE flag list.
reset_use ()
Prefixes the global USE flag list with -*, causing all default USE flags from the Portage profile to be ignored. This does not reset USE flags enabled or disabled in this configuration.
mask_use (useflag=str)
unmask_use (useflag=str)
Causes a specified useflag to be masked or to be unmasked. Masking prevents a USE flag from being enabled.
force_use (useflag=str)
unforce_use (useflag=str)
Causes a specified useflag to be forced or not to be forced. Forcing requires a USE flag to be enabled.
enable_ex_use (expand=str, *flags=str)
disable_ex_use (expand=str, *flags=str)
Enables or disables each specified expanded USE flag for expand. Expanded USE lists follow the USE flag pattern, but apply to separate list variables (e.g. INPUT_DEVICES, VIDEO_CARDS). Each flag should not be prefixed with the expand name. LINGUAS is not currently treated as an expanded USE list, and should be set with add_lingua () instead.

Package inclusion and exclusion

add_package (*depatoms[, category=str][, prefix=str][, unstable=bool][, OTHER=list (str)][, ...])
where each OTHER is one of enable_use, disable_use, add_cflag, add_cxxflag, mask_install, or add_econf

Adds or removes each specified depatom to or from the list of packages in the world set. If prefix is specified, each depatom is prefixed with it before use. If category is specified, each depatom is treated as an unqualified package name in that category. For example, box.add_package ("foldoc", "jargon", prefix="dictd-", category="app-dicts") adds app-dicts/dictd-foldoc and app-dicts/dictd-jargon to the world set.

If unstable is True, each resultant depatom is also passed to accept_package_unstable (). If enable_use or disable_use is specified, each USE flag in the specified list is enabled or disabled for each depatom. If add_cflag, add_cxxflag, mask_install, or add_econf is specified, each depatom is passed to add_package_cflag (), add_package_cxxflag (), mask_package_install (), or add_package_econf () with the specified list. (See that section for details on requirements.)

provide_package (*depatoms=str)
Adds each specified depatom as a provided package, which will be treated as installed when calculating dependencies. Each depatom must specify a single package version.
prefer_package (virtual=str, depatom=str)
Lists the specified depatom as the preferred package to satisfy a dependency on the specified virtual. virtual should not be prefixed with "virtual/".
add_system_package (*depatoms=str)
remove_system_package (*depatoms=str)
Adds or removes each specified depatom to or from the list of packages in the system set.
add_package_version (*depatoms=str)
remove_package_version (*depatoms=str)
Adds or removes a global dependency on each specified depatom version. There is no dependency on the package itself, but only versions matching the depatom will be accepted.

Package stability levels

accept_package_arch (depatom, arch)
reject_package_arch (depatom, arch)
Accepts or rejects a specified Portage arch keyword for the specified depatom.
accept_package_unstable (depatom)
Accepts the unstable keyword for the Portage system architecture for a specified depatom. For example, ~ppc is accepted for the ppc architecture. This is not based on the arch attribute, which need not be set.
accept_package_otherwise (depatom)
Accepts the architecture keywords for a specified depatom even if the system architecture has been excluded implicitly by "-*".
mask_package (*depatoms)
unmask_package (*depatoms)
Hard-masks or hard-unmasks each specified depatom. "Hard" masking prevents a matching package version from being installed.

Per-package USE flags

enable_package_use (depatom, *useflags)
disable_package_use (depatom, *useflags)
Enables or disables each specified useflag for the specified depatom.
mask_package_use (depatom, useflag)
unmask_package_use (depatom, useflag)
Causes a specified useflag to be masked or to be unmasked for the specified depatom. Masking prevents a USE flag from being enabled.
force_package_use (depatom, useflag)
unforce_package_use (depatom, useflag)
Causes a specified useflag to be forced or not to be forced for the specified depatom. Forcing requires a USE flag to be enabled.

Other per-package configuration

These methods provide support for additional per-package options. The /etc/portage/package.env and /etc/portage/package.patch files are output. This support is provided by the Boxenator bashrc file, which must be installed for these methods to be effective. See the download page for instructions.

set_package_env (depatom, envvar, value[, before=bool])
prepend_package_env (depatom, envvar, value[, before=bool])
append_package_env (depatom, envvar, value[, before=bool])
Sets envvar to value or prepends or appends value to the existing value of envvar for the specified depatom. If before is True, the envvar is set before pkg_setup; otherwise it is set after pkg_setup. The value will be interpreted by bashrc as a double-quoted shell string, and may contain appropriate shell expressions which will be evaluated at build time.
add_package_cflag (depatom, *cflags)
add_package_cxxflag (depatom, *cxxflags)
Adds each specified cflag or cxxflag to the list of CFLAGS or CXXFLAGS for the specified depatom.
add_package_econf (depatom, *config)
Adds each config argument to the EXTRA_ECONF list of arguments to be passed to the configure script for the specified depatom.
mask_package_install (depatom, *files)
Adds each specified file to the INSTALL_MASK list of files and paths that will not be installed from the specified depatom.
add_package_patch (depatom, patch[, opts=list (str)])
Causes the working directory for the specified depatom to be patched with the specified patch file after it has been unpacked. If opts are specified, each is passed to patch when it is run. The patch file is expected to be found in the distfiles directory of the Portage tree or an overlay tree.

Licensing support

These methods provide support for encoding licence acceptance in the Portage configuration. Each license is a licence file name in /usr/portage/licenses. The ACCEPT_LICENSES environment variable and /etc/portage/package.licenses dictionary file are output. This support is intended to be provided by the Boxenator bashrc (see other per-package configuration), but is not yet implemented. Licensing may be specified now, and will generate output, but will be ignored by Portage.

accept_license (*licenses)
reject_license (*licenses)
Accepts or rejects each specified license globally.
accept_package_license (depatom, license)
reject_package_license (depatom, license)
Accepts or rejects a specified license for the specified depatom.
accept_package_licensing (depatom)
Accept the licensing for a specified depatom unconditionally.

Script interaction

[param=str]
Returns the value of a Boxenator parameter param, including those defined on the command line with -D. Parameters are a convenience for passing script-specific options and maintaining state, and do not result in any output. If param is not set, returns None.
set (*params=str[, prefix=str][, value=any])
Sets each Boxenator parameter param specified to value, or to True if no value is specified. If a prefix is specified, each param is prefixed with it before use. For example, box.set ("bar", "baz", prefix="foo") sets parameters foobar and foobaz to True.
print_debug (notice=str)
print_warning (notice=str)
print_error (notice=str)
Prints a notice to standard error. print_debug only produces output if Boxenator was run with -v/--verbose. print_error additionally indicates that Boxenator will abort. If standard error is a TTY, appropriate colouring is applied.
abort ()
Aborts Boxenator due to an error condition. No targets will be output. An abort () should be preceded by an explanatory print_error ().
include_file (filename=str)
Interprets filename as a Boxenator script at the point it is called. filename is relative to the working directory, which may or may not contain the script being interpreted. Unless called from standard input, failure to read the file will terminate Boxenator.
include_stdin ()
Interprets lines from standard input as a Boxenator script. A readline interface is provided. When reading standard input, no errors are fatal and only abort () causes an exit without output.

Internal methods

These methods are used internally to implement command line options. They should not be used in Boxenator scripts. If the boxenator module is imported by another Python program, they may be useful. No other methods are intended to be public or stable.

get_targets ()
Returns a list of valid target configuration files. Each file is specified by its full path.
run_target (target=str)
run_all_targets ()
Outputs a specified target or all valid target files with the current configuration. A target is specified by its base (without path) file name.
set_mode (mode=enum)
Sets the mode in which target files will be output. The following values, also members of Context, are accepted.
MODE_STDOUT (default)
Target files will be sent to standard output.
MODE_FILES
Target files will be output in appropriate subdirectories of the destination path.
MODE_SHALLOW
Target files will be output in the destination path directory.
set_destination (path=str)
Sets the path in which target files will be output, if applicable. (default: current directory)
set_verbose (verbose=bool)
Sets whether spec files and targets will be listed as they are processed. (default: False)
set_check_real (check_real=bool)
Sets whether the program will be terminated if a referenced package, category, etc. does not exist. This is the inverse of the --force command line option. (default: True)
set_use_color (use_color=bool)
Sets whether program output will be colourised. (default: if standard error is a TTY)
realize_world ()
Installs any packages in the world set that are not currently installed. Applies to the live configuration at ROOT regardless of any specified destination path.

Notes