PORTMOD(5)

NAME
portmod - Configuration files for portmod

These files are found in the CONFIG_DIR (as displayed by portmod <prefix> info). This is typically one of the following locations, depending on your platform.
Linux | ~/.config/portmod/<prefix>
Windows | C:\Documents and Settings\<User>\Application Data\Local Settings\portmod\portmod\<prefix> or C:\Documents and Settings\<User>\Application Data\portmod\portmod\<prefix>

PACKAGE.ACCEPT_LICENSE

The file {CONFIG_DIR}/package.accept_license can be used to allow the installation of packages with a license which is not accepted using the global ACCEPT_LICENSE setting.

E.g.:

# This license is not accepted by default
>category/foo-1.2.3-r1 license_name

  Syntax

package.accept_license should contain a list of package atoms, one per line, followed by the accepted license. The atoms must specify the package category, but other components such as the version are optional. The special * keyword can also be used to accept all licenses for a package, and license groups (see Package Repositories) can be specified by prefixing them with a @.

The file can also include comments, beginning with a #.

PACKAGE.ACCEPT_KEYWORDS

The file {CONFIG_DIR}/package.accept_keywords can be used to configure the visibility of packages via their Keywords.

E.g.:

# This is a custom option
>category/foo-1.2.3-r1 ~arch

  Syntax

package.accept_keywords should contain a list of package atoms, one per line, followed by the accepted Keywords. The atoms must specify the package category, but other components such as the version are optional. The special ** keyword can also be used to make a package visible regardless of keywords.

The file can also include comments, beginning with a #.

PACKAGE.MASK

The file {CONFIG_DIR}/package.mask can be used to prevent certain packages from being installed.

If a package is broken, and you want to skip that version, you can add the exact version to the file:

# Version is broken
=category/foo-1.2.3-r1

This can also be useful for packages where you need a particular version so that your savegame doesn't break. E.g.:

# Newer versions break savegame
>category/foo-1.2.3-r1

  Syntax

package.mask should contain a list of package atoms, one per line. These atoms must specify the package category, but other components such as the version are optional.

The file can also include comments, beginning with a #. Any comments immediately preceding an atom will be treated as descriptive comments and will be displayed if the package mask causes any error messages. Descriptive comments are also linked to atoms which follow, until a newline is encountered.

PACKAGE.USE

The file {CONFIG_DIR}/package.use can be used to configure Use Flags for individual packages or package versions.

E.g.:

# This is a custom option
>category/foo-1.2.3-r1 flag -otherflag

  Syntax

package.use should contain a list of package atoms, one per line, followed by flags. The atoms must specify the package category, but other components such as the version are optional. Flags prefixed with a - are considered disabled, otherwise they are considered enabled.

The file can also include comments, beginning with a #.

PORTMOD.CONF

The portmod.conf file is used for configuring Portmod’s global options. It can be found in the portmod config directory, found in one of the following locations:
Linux | ~/.config/portmod
macOS | ~/Library/Application\ Support/portmod
Windows | C:\Documents and Settings\<User>\Application Data\Local Settings\portmod\portmod or C:\Documents and Settings\<User>\Application Data\portmod\portmod

All config entries can be overridden using environment variables of the same name. In the case of USE, ACCEPT_LICENSE and ACCEPT_KEYWORDS, this will extend the value, rather than override it. E.g. setting the environment variable USE=foo will use all use flags in your config file (and profile) and also set the foo flag. Similarly, USE=-foo will disable foo if it is set in your config file or profile.

You can also create a prefix-specific version of portmod.conf which will apply the same options just to one prefix. This can be done by creating or modifying the portmod.conf in the subdirectory of the portmod config directory with the name of the prefix. E.g. ~/.config/portmod/<prefix>/portmod.conf

  Format

The portmod config file uses a restricted subset of python with extremely limited support for builtins. No imports are allowed.

Available builtins:

•   join: equivalent to os.path.join and can be used for specifying paths in a platform independant manner.

•   PLATFORM: equivalent to sys.platform.

  Variables used by Portmod

You may define arbitrary variables, but there are several that are reserved for the use of Portmod and have a special meaning

All variables defined in portmod.conf are set as environment variables during portmod execution.

  ACCEPT_KEYWORDS

A string of whitespace separated keywords that indicate stability of mods that you allow to be installed. By default this is generally the stable keyword (equal to your arch, e.g. openmw or tes3mp without qualifiers).

If you also want to include unstable mods, prefix the keyword with a ~. E.g. ACCEPT_KEYWORDS = ~openmw or ACCEPT_KEYWORDS = ~tes3mp.

  PORTMOD_MIRRORS

Specifies a list of mirrors to use to fetch source files (mod archives). Currently the only mirror is the default: https://gitlab.com/portmod/mirror/raw/master/

  ACCEPT_LICENSE

Specifies the globally accepted licenses. By default this is all except EULA licenses, i.e. a value of * -@EULA. If you want to only install mods with Free licenses, you could, for example set this to ACCEPT_LICENSE = -* @FREE.

See profiles/license_groups.yaml in the repo for details on the available license groups.

  TEXTURE_SIZE

Specifies a function for choosing between texture size options. This must contain an operator min or max, followed by an optional inequality.

•   min: Chooses the smallest texture size available

•   max: Chooses the largest texture size available

•   min >= NUM: Chooses the smallest texture size available that is larger than NUM.

•   max <= NUM: Chooses the largest texture size available that is smaller than NUM.

  USE

Sets global use flags. See Use Flags for details.

  OMWMERGE_DEFAULT_OPTS

The default options passed to portmod <prefix> merge (e.g flags such as --verbose, --no-confirm, etc.). Will be ignored if --ignore-default-opts is passed.

  REPOS

The list of repositories (as a whitespace-separated string) which are enabled for this prefix. Only packages from these repositories will be found when installing or searching for packages.

  MERGE_TOOL

A command to be used to merge updates to configuration files.

The placeholders ${orig}, ${new} and ${merged} should be used to specify the input files.

E.g.

MERGE_TOOL = "kdiff3 ${orig} ${new} --output ${merged}"

Version

    Added in portmod 2.3

  Use Expand Variables

Use expand variables represent categories of global use flags for enabling features across all packages that support them.

They can be enabled similarly to USE flags, but use a custom field. E.g. for L10N flags, you can set

L10N = "ru"

Which will enable the flag l10n_ru globally, building support for Russian localization into packages.

Note that supported use expand flags vary depending on your profile and architecture.

PROFILE

The profile symlink points to the first directory of your [[profile]].

REPOS.CFG

The repos.cfg file in the portmod config directory (See portmod.conf) can be used to specify the various repositories that Portmod pulls information from.

The following entry is for the meta repository which is automatically included and does not need to be specified in repos.cfg.

[meta]
location = ${PORTMOD_LOCAL_DIR}/repos/meta
auto_sync = True
sync_type = git
sync_uri = https://gitlab.com/portmod/meta.git
priority = -1000

  Local Repository

A local repository can be specified by setting auto_sync = False (or omitting it, as it is false by default).

E.g. to create a custom repository where you can add your own pybuilds, add the following entry to repos.cfg.

[user]
location = /path/to/repo
auto_sync = False
priority = 0

You also likely want to create the file /metadata/layout.conf within the repository, and specify a parent repository using masters = "<repo>". This makes your custom repo inherit metadata from the other repo, such as categories and global use flags. If you omit this then portmod won’t be able to find your packages without you ensuring that their category exists in the profiles/categories file in your repo.

metadata/layout.conf:

masters = "<repo>"

The priority needs to be higher than the priority of the default repository if you have packages with the same name as those in the main repo, as if a package is otherwise identical to the loader (i.e. the packages have the same name and version) Portmod will attempt to load the package in the higher priority repo.

The only required file that must exist in a repo is profiles/repo_name, which should include a single line containing the name of your repository.

SETS

You can create your own Sets by adding set files to the sets directory in the CONFIG_DIR. A set file is a file where the filename (no file extension) corresponds to the set name, and the contents are a newline-separated list of mod atoms. Set files can also include comments (lines starting with #).

E.g. CONFIG_DIR/sets/mymods

# This is a list of mods
gameplay-advancement/ncgd
assets-meshes/rr-better-meshes

User sets with the same name as a builtin set will be ignored in favour of the builtin sets, as user sets have the lowest priority when loading.

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