PYBUILD(5)

NAME
pybuild - Portmod Repositories and related files

Repositories have the following basic file structure:

./profiles/repo_name
./CATEGORY_NAME/metadata.yaml
./CATEGORY_NAME/PACKAGE_NAME/PACKAGE_NAME-VER.pybuild
./CATEGORY_NAME/PACKAGE_NAME/PACKAGE_NAME-OTHER_VER.pybuild
./CATEGORY_NAME/PACKAGE_NAME/Manifest
./CATEGORY_NAME/PACKAGE_NAME/metadata.yaml

PROFILES

  Profiles

Profiles are used to provide preset configurations for users.

  profiles.yaml

The file profiles/profiles.yaml describes the available profiles. It contains a mapping with the architecture as the key at the root, followed by a mapping of profile paths to profile stability keywords (either stable or unstable). These paths should refer to a directory within the profiles directory.

E.g.

openmw:
    dev: unstable
    default/openmw/1.0: stable

  Profile Files

Within each profile directory the following files can be used to customize the profile.

•   packages

•   package.mask

•   package.use

•   use.force

•   package.use.force

•   parent

•   license_groups.yaml

•   defaults.conf

  packages

A list of atoms to be included in the system set and thus installed by default. Each line to be included in the system set should start with an asterisk (*), followed by the atom to include. Lines not beginning in an asterisk will be ignored.

  package.mask

A profile-specific list of masked packages.

See package.mask

  package.use

Default per-package use flags. The file can contain comments (starting with #) and lines containing a qualified atom (i.e. containing a category, can also include versions and operators) followed by a whitespace-separated list of flags. Flags can be disabled by prefixing them with a -.

See package.use

  use.force

Global use flags that are required to always be enabled in this profile. The format is the same as the contents of the USE variable in defaults.conf.

  package.use.force

Per-package use flags that are required to always be enabled in this profile. The format is the same as package.use.

  parent

Defines another directory (via relative path) to be included in the current profile. This allows profiles to share configuration, and it is recommended that all profiles include the profiles/base directory in their hierarchy.

  license_groups.yaml

A mapping of license group names to the licenses in the group. Licenses should be a whitespace-separated list. Licenses listed are merged with the license groups in master repositories.

The special REDISTRIBUTABLE license group is used to determine if a package can be mirrored (and also if mirrors should be checked when fetching the file).

E.g.

profiles/license_groups.yaml

REDISTRIBUTABLE: CC-BY CC-0 GPL-3

  defaults.conf

The format is the same as portmod.conf, but additional variables are available. Also note that unlike the user-defined defaults.conf, variables defined in defaults.conf which are not listed on this page will not be set as environment variables (this is for security reasons, as there are variables such as PATH which could be abused).

As portmod.conf is a python file (albeit a restricted subset of the language), other variables defined earlier in the same file can be referenced directly. Additionally, you can reference the final value of a variable using string templating. I.e. strings containing values of the form ${VAR} will be substituted for the final value of the referenced variable once all conf files have been parsed.

Collapsible Variables

These variables contain whitespace-delimited sets (as strings), the entries of which can be disabled (if enabled in a previously loaded conf file) by prefixing them with a minus/hyphen (-).
Variable | Description
USE | Enabled use flags. These provide the profile default enabled use flags.
ACCEPT_LICENSE | A list of accepted licenses. License groups, as specified in profiles/license_groups.yaml, can be included by prefixing the group name with an @. An asterisk (*) can be used to accept all licenses by default, with the ability to disable specific licenses by default by prefixing them with -. Recommended defaults are * -@EULA or @FREE.
ACCEPT_KEYWORDS | The default keywords to accept. Should usually only contain
INFO_VARS | Variables to display when portmod <prefix> info is run.
INFO_PACKAGES | Packages to display when portmod <prefix> info is run.
USE_EXPAND | The names of USE_EXPAND variables. The values they can take should be described in the profiles/desc directory in a yaml file with a name equal to the lowercased variable name, followed by .yaml.
USE_EXPAND_HIDDEN | A subset of USE_EXPAND that should be hidden to the user and not show up in searches and transaction lists.
PROFILE_ONLY_VARIABLES | This defines which variables cannot be modified by the user in their portmod.conf (technically, portmod.conf can configure everything that defaults.conf can, with the exception of the variables listed here). Note that users can still use profile.user to create a custom profile and override these variables.
CACHE_FIELDS | A list of fields that should be cached (e.g. fields that may be added by classes in this repo which it would be useful to have accessible to external software).

Other Variables
Variable | Description
ARCH | The architecture for the profile. See arch.list. This is set automatically and should not be modified
TEXTURE_SIZE | The algorithm for choosing texture size. See portmod.conf
PORTMOD_MIRRORS | The list of download mirrors. See portmod.conf
CASE_INSENSITIVE_FILES | Whether or not files in the VFS should be case-insensitive. When enabled, portmod will treat files of identical path other than their case as the same when installing. Otherwise, such files may be installed side by side instead of overriding each other.
OMWMERGE_DEFAULT_OPTS | The default options passed to portmod <prefix> merge. See portmod.conf
MODULEPATH | The directory (relative to ROOT) which stores Importing Modules.
DOC_DEST | The default installation directory for documentation when the dodoc function is called.
VARIABLE_DATA | The directory, relative to ROOT should contain generated portmod files such as the package database. This variable should never be changed since it takes effect immediately. Instead, it is recommended to create a new profile with a new value and a migration tool to update the filesystem.
CFG_PROTECT | A glob-style patterns (or list of patterns) indicating files which should not be overwritten on installation if they have been modified since the file was first installed. Instead, a .new file will be created and users will be able to run the cfg updater to merge the modifications.

  metadata.yaml

metadata.yaml files are used to store additional information about mods and categories. Note that no information stored in metadata.yaml should be specific to a particular version of a mod.
Key | Value
longdescription | Description of the mod or category.
maintainer | Maintainer, or list of maintainers for the package in the form of Person (email is required, name and desc are optional) or Group
use | Use flags and their descriptions. Key is the flag name, value is the description
upstream | Description of the mod’s upstream information. Is a dictionary with one or more of the entries listed in the table below
tags | A set of tags which describe this package. These tags are primarily used by the search indexer, and may be used by external software to categorise packages.

  Upstream contents
Key | Value
maintainer | maintainers/authors of the original mod. Must be either a Person or a list of Person with a name attribute and/or an email attribute.
changelog | URL where a changelog for the mod can be found. Must be version independent
doc | URL where the location of the upstream documentation can be found. The link must not point to any third party documentation and must be version independent
bugs-to | A place where bugs can be reported in the form of an URL or an e-mail address prefixed with mailto:

  Person
Key | Value
name | Name of maintainer
email | email address of maintainer
desc | Can be used to note details about the current maintainership E.g. Willing to pass this off to someone else

E.g.

name: foo
email: foo@example.org
# If provided with one argument, that argument is the name of the maintainer
# The person tag can be omitted and a string can be provided instead,
# in which case the string is treated as the maintainer's name,
# with email optionally following in angle brackets.
baz <foo@example.org>
# Note that maps can also be written in a single line using braces:
{ name: foo, email: foo@example.org }

  Groups
Key | Value
group | Group identifier (as listed in metadata/groups.yaml)

E.g.

group: foo
# Note that the groups cannot be provided as just a string,
# as strings are treated as person maintainers

  Mod Metadata

Example

maintainer:
    - name: foo
      email: foo@example.org
      desc: E.g. Willing to pass this off to someone else
    - group: Group name, as defined in metadata/groups.yaml
longdescription: "Long mod description. Can be multiple lines long, but
should not contain version-specific information.
That being said, confine this to a general description only and link to
upstream documentation rather than put extremely large amounts of detail
in this string"
use:
    flag: description of flag
    otherflag: description
upstream:
    maintainer:
        name: foo
        email: foo@example.org
    changelog: http://doc.example.org/changelog
    doc: http://doc.example.org/doc
    bugs-to: mailto:foo@example.org

  Category Metadata

Example

longdescription: The patches category contains mods that combine information from other mods to build a patch.

When categories are created, a metadata.yaml containing a longdescription is required.

  layout.conf

Describes the repository metadata.

E.g.

# Comments can be included
masters = "python openmw"
# 2 is new, so it's not a bad idea to stick with 1 for now
pybuild_versions_banned = [2]
# Obviously this isn't helpful if you also include the above statement,
# But eventually you will want to deprecate Pybuild1 since support for
# it will be dropped.
pybuild_versions_deprecated = [1]

  Fields

  masters

A space-separated string list of repository masters

  pybuild_versions_banned

A python list of banned pybuild versions. E.g. if this list includes 2, pybuild.Pybuild2 will be considered banned and will not be able to be loaded. inquisitor will also produce an error for packages which use banned pybuild versions.

This is primarily a QA feature, but is also enforced at runtime.

  pybuild_versions_deprecated

A python list of deprecated pybuild versions. E.g. if this list includes 2, pybuild.Pybuild2 will be considered deprecated and inquisitor will emit a warning when encountering packages which use it.

  Syntax

Same as defaults.conf. I.e. a restricted subset of python using only basic primitives and no imports.

CATEGORIES

Any category must be listed in profiles/categories and contain a metadata.yaml file.

PACKAGES

Mod directories must be in a subdirectory of a category and their directory name should be the same as the base name of the mod’s pybuilds (excluding version).

The Manifest file is optional, but is required to contain a manifest entry for each source file listed in SRC_URI (i.e. only optional for pybuilds without sources).

metadata.yaml is optional.

PROFILES DIRECTORY

The files in profiles are optional, except for repo_name.
File | Description
arch.list | A newlline-separated list of architectures. An architecture may refer to a game-engine variant or an operating system, and is used to distinguish configurations where a package may be stable when used in the context of one, but unstable in the context of another.
categories | A newline-separated list of categories. These determine which directories in the root of the repository are considered categories containing packages. Directories not listed in this file will not be detected as containing packages.
license_groups.yaml | A yaml file containing a mapping from license groups to a whitespace-separated list of license names. Each group can be referenced within ACCEPT_LICENSE by prefixing it with an @, and they also reference each other using the same method.
package.mask | A package.mask file which applies regardless of profile
profiles.yaml | A yaml file containing profile declarations. See Profiles.
repo_name | A file containing a single line with the name of this repository
use.yaml | A file describing the global use flags, containing a mapping of use flag names to descriptions
use.alias.yaml | A file describing global use flags which have their values tied to packages. Contains a mapping of use flag names to package atoms.
desc | A directory containing USE_EXPAND descriptor files. Each file has the same form as use.yaml.

METADATA DIRECTORY

The metadata directory is optional
File | Description
groups.yaml | Defines maintainer groups
layout.conf | See layout.conf
news | See GLEP 42, noting that news files are in yaml format rather than XML. Specification for the files can be found here (TODO: Rustdoc), and the directory structure follows GLEP 42.

AUTHOR
Benjamin Winger, Roma Tentser, Hristos N. Triantafillou, lumbo7332, PopeRigby, marius david, marius851000, Joel, Nords Morrow, Paul Infield-Harm, Pope_Rigby, Tenchi, louisabraham, ultramink

COPYRIGHT
2019-2023, Portmod Authors