PORT(5)

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.

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)

LICENSE
    Primary license identifier for the installed files from the SPDX License List: https://spdx.org/licenses/. 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.

RUNTIME_DEPS
    Space delimited list of libraries (ports) needed at run time. Unsupported.

RUNTIME_PROGRAMS
    Space delimited list of programs (ports) needed at run time. Unsupported.

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.

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.