NAME

port — port build instructions

SYNOPSIS

/src/ports/example/example.port

DESCRIPTION

The .port file format defines the build instructions for a piece of software ported to this operating system as a package. This manual documents the file format and porting(7) is the guide on how to author a port. A port called example consists of the following adjacent files:

example.port

build instructions and meta information.

example.patch

optional patch(1) applied to the upstream release.

example.execpatch

optional tix-execpatch(8) changing the executable bit on files.

example.rmpatch

optional tix-rmpatch(8) deleting files from the upstream release.

The upstream release archive is downloaded and extracted into the example directory with each kind of patches applied, which is used as the working directory when building the port. Ports are extracted with read-only files and writable directories by default. The example.version file is created with the version number and checksums of the above files. If the port is placed in the /src/ports/example/ directory then it's built as part of the operating system. The port can be built directly using tix-port(8) which handles downloading and patching the source code, building the port, and installing the binary package. The .port files define the meta information using a subset of the sh(1) language syntax for variable assignments as parsed by tix-vars(8). Basic variable substitutions, escape sequences, single quotes, double quotes, and comments are supported. The variables are as follows:

ALIAS_OF

Declares this port to be an empty port that's an alias for the named port.

ARCHIVE

Extract the upstream archive by this file name if set, usually $DISTNAME.$COMPRESSION where $COMPRESSION is normally tar.xz or the appropriate file extension.

ARCHIVE_2

A second ARCHIVE if set with its own set of similar variables.

BUILD_LIBRARIES

Space delimited list of libraries (ports) linked with. Optional dependencies are suffixed with a question mark ‘?’.

BUILD_PROGRAMS

Space delimited list of programs (ports) needed to build this port. Optional dependencies are suffixed with a question mark ‘?’.

BUILD_SYSTEM

The build system used by this port:

configure

A ./configure script following the GNU coding conventions communicated with using standard command line options and standard environment variables.

makefile

A Makefile using the below set of conventional environment variables.

none

The port is not built and contains no files. Useful for port sets depending on other ports.

CONFIGURE

The path to the configure script relative to the source directory. (Default: ./configure)

CONFIGURE_ARGS

Additional command line arguments passed to configure.

CONFIGURE_USE_BUILD_DIRECTORY=[false | true]

Whether to use a temporary working directory when building the port where the object files will be placed instead of inside the source directory. (Default: false)

CONFIGURE_VARS

Additional environment variable assignments while configure is run.

CONFIGURE_WITH_BUILD_SYSROOT=[false | true]

Whether to tell configure where the system root is located during the build using the --with-build-sysroot option. (Default: false)

CONFIGURE_WITH_SYSROOT=[false | true]

Whether to tell configure where the system root is located at runtime using the --with-sysroot option. (Default: false)

CONFIGURE_WITH_SYSROOT_LD_BUG=[false | true]

Whether the --with-sysroot option doesn't understand the empty string as meaning no system root will be used at runtime and --with-sysroot=/ should be used instead. (Default: false)

COMPRESSION=[tar | tar.gz | tar.bz2 | tar.xz]

The file extension of ARCHIVE including the compression format.

COMPRESSION_2=[tar | tar.gz | tar.bz2 | tar.xz]

For ARCHIVE_2.

DEVELOPMENT=[false | true]

Whether the port is in the development workflow per porting(7). (Default: false)

If false, the port is extracted with read-only files and writable directories. The port's source directory is considered a cache that can be safely deleted without data loss e.g. whenever the meta information or the patches change.

If true, any old non-development extraction is deleted, and the archive is instead extracted with writable permissions in development mode. The port's source directory contains an in-progress port that's considered valuable and will not be deleted under any circumstances as long as the port remains in development mode. If the port builds successfully, then the patches are regenerated by diffing the upstream release with the source directory.

DIRTY_FILE

The port doesn't need to be cleaned if this file doesn't exist. (Default: config.log, Makefile, and makefile)

DISTNAME

The name of the upstream release, usually $NAME-$VERSION.

DISTNAME_2

For ARCHIVE_2.

DISTNAME_REGEX

Extended regular expression recognizing distnames of releases with the version number matched in the first subexpression. (Default: Automatically determined using ARCHIVE and VERSION_REGEX)

EDITION

An increasing number used to distinguish this edition of the package from any previous packages by the same name. A new pacckage with the same name and a different edition will considered a different package. Upgrades will uninstall the old package and will not upgrade to the new edition as if the package has stopped existing. The RENAMES variable can be used in combination with EDITION to rename and split packages. The default edition is 1.

IS_SET=[false | true]

Whether the bootloader should offer this port as a reasonable subset of ports expressed recursively in RUNTIME_DEPS.

LICENSE

Primary license identifier for the installed files from the SPDX License List. Library ports use the license for linking with the library.

LOCATION_INDEPENDENT=[false | true]

Whether binary packages are location independent, i.e. can be installed in another prefix than one supplied at build time. (Default: false)

MAKE

The make(1) program to use. (Default: Search the PATH for the program in the MAKE environment variable or make(1) as a fallback)

MAKE_ARGS

Additional arguments passed to make.

MAKE_BUILD_TARGET

Build the port by making this target. (Default: all)

MAKE_CLEAN_TARGET

Clean the port by making this target. (Default: distclean if BUILD_SYSTEM=configure and clean otherwise)

MAKE_IGNORE_CLEAN_FAILURE=[false | true]

Whether to silently ignore if cleaning the port failed. (Default: true)

MAKE_INSTALL_TARGET

Install the port by making this target with the DESTDIR environment variable set to a temporary secondary prefix for the purpose of installation-time packaging. (Default: install)

MAKE_VARS

Additional environment variable assignments while make is run.

NAME

The name of the port.

NEED_WRITABLE=[false | true]

Whether to extract the port with writable files because the port couldn't be fully normalized and the port actually needs to modify files shipped in the upstream releases at build time. (Default: false)

POST_INSTALL

Optional program to invoke post-installation to fix up the installation. The TIX_BUILD_DIR, TIX_SOURCE_DIR, TIX_INSTALL_DIR, TIX_SYSROOT, BUILD, HOST, TARGET, PREFIX, and EXEC_PREFIX environment variables are set and unset appropriately.

RELEASE_SEARCH_PAGE

Upstream URL listing the available versions of the port.

RELEASE_SEARCH_REGEX

Locate new upstream versions of the port by searching RELEASE_SEARCH_PAGE using this regular expression matching the new version number in the first subexpression.

RENAMES

Comma-separated list of package renames. Each rename is expressed as the name of a package followed by a ‘@’ and its EDITION, followed by a ‘:’ and then a potentially-empty space separated list of replacement packages, each taking the form of a replacement package name followed by ‘@’ and then the replacement package EDITION.

RUNTIME_DEPS

Space delimited list of ports needed at run time.

SHA256SUM

sha256sum(1) of the upstream release.

SHA256SUM_2

For ARCHIVE_2.

SOURCE_PORT

Use the named port's source code instead.

SUBDIR

Run the build commands in this subdir.

UPGRADE_BLOCKED

A reason why upgrading to a newer version is blocked.

UPSTREAM_ARCHIVE

The filename of the upstream release on UPSTREAM_SITE, usually $ARCHIVE but may be different in cases where the upstream filename is poor (e.g. isn't unique, lacking the name of the port and the version) and ARCHIVE is set to a unique filename for use in the mirror.

UPSTREAM_ARCHIVE_2

For ARCHIVE_2.

UPSTREAM_SITE

Download releases from this upstream URL (without a trailing slash) in case the mirror fails.

UPSTREAM_SITE_2

For ARCHIVE_2.

USE_BOOTSTRAP=[false | true]

Bootstrap a new version of this port by first building a local version installed into a temporary directory in the PATH and then use it to build the final version. (Default: false)

This functionality is useful when e.g. cross-compiling a port requires the same version of the port to already be locally installed. The bootstrap phase uses its own set of variables prefixed with BOOTSTRAP_ with the same semantics as their counterparts, e.g.:

BOOTSTRAP_BUILD_SYSTEM

BOOTSTRAP_CONFIGURE

BOOTSTRAP_CONFIGURE_ARGS

BOOTSTRAP_CONFIGURE_USE_BUILD_DIRECTORY

BOOTSTRAP_CONFIGURE_VARS

BOOTSTRAP_MAKE

BOOTSTRAP_MAKE_ARGS

BOOTSTRAP_MAKE_VARS

VERSION

The version of the port. If the version number components are used individually, define them as VERSION_MAJOR, VERSION_MINOR, and VERSION_PATCH and define VERSION as $VERSION_MAJOR.$VERSION_MINOR.$VERSION_PATCH.

VERSION_2

For ARCHIVE_2.

VERSION_REGEX

Extended regular expression parsing the version number with the full version in the first subexpression. (Default: ‘([0-9]+.[0-9]+(.[0-9]+)*)’)

The following environment variables are set by default during the port build:

CC

The C compiler.

CFLAGS

Command line options when compiling C code.

DESTDIR

An optional extra prefix used when installing the port for packaging.

PKG_CONFIG

The pkg-config(1) to use for locating dependencies.

SEE ALSO

development(7), porting(7), tix-vars(8)

HISTORY

The port format originally appeared in Sortix 1.1 as the semantic continuation of the former tixbuildinfo format introduced in Sortix 0.8.