.Dd March 19, 2022
.Dt PORT 5
.Os
.Sh NAME
.Nm port
.Nd port build instructions
.Sh SYNOPSIS
.Pa /src/ports/example/example.port
.Sh DESCRIPTION
The .port file format defines the build instructions for a piece of software
ported to this operating system as a package.
.Pp
This manual documents the file format and
.Xr porting 7
is the guide on how to author a port.
.Pp
A port called
.Sy example
consists of the following adjacent files:
.Pp
.Bl -tag -width "example.execpatch" -compact
.It Pa example.port
build instructions and meta information.
.It Pa example.patch
optional
.Xr patch 1
applied to the upstream release.
.It Pa example.execpatch
optional
.Xr tix-execpatch 8
changing the executable bit on files.
.It Pa example.rmpatch
optional
.Xr tix-rmpatch 8
deleting files from the upstream release.
.El
.Pp
The upstream release archive is downloaded and extracted into the
.Pa 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
.Pa example.version
file is created with the version number and checksums of the above files.
.Pp
If the port is placed in the
.Pa /src/ports/example/
directory then it's built as part of the operating system.
The port can be built directly using
.Xr tix-port 8
which handles downloading and patching the source code, building the port,
and installing the binary package.
.Pp
The .port files define the meta information using a subset of the
.Xr sh 1
language syntax for variable assignments as parsed by
.Xr tix-vars 8 .
Basic variable substitutions, escape sequences, single quotes, double quotes,
and comments are supported.
.Pp
The variables are as follows:
.Bl -tag -width "12345678"
.It Sy ALIAS_OF
Declares this port to be an empty port that's an alias for the named port.
.It Sy ARCHIVE
Extract the upstream archive by this file name if set,
usually
.Sy $DISTNAME.$COMPRESSION
where
$COMPRESSION
is normally tar.xz or the appropriate file extension.
.It Sy ARCHIVE_2
A second
.Sy ARCHIVE
if set with its own set of similar variables.
.It Sy BUILD_LIBRARIES
Space delimited list of libraries (ports) linked with.
Optional dependencies are suffixed with a question mark
.Sq "?" .
.It Sy BUILD_PROGRAMS
Space delimited list of programs (ports) needed to build this port.
Optional dependencies are suffixed with a question mark
.Sq "?" .
.It Sy BUILD_SYSTEM
The build system used by this port:
.Bl -tag -width "configure"
.It Sy configure
A
.Pa ./configure
script following the GNU coding conventions communicated with using standard
command line options and standard environment variables.
.It Sy makefile
A
.Pa Makefile
using the below set of conventional environment variables.
.It Sy none
The port is not built and contains no files.
Useful for port sets depending on other ports.
.El
.It Sy CONFIGURE
The path to the configure script relative to the source directory.
(Default:
.Pa ./configure )
.It Sy CONFIGURE_ARGS
Additional command line arguments passed to configure.
.It Sy CONFIGURE_USE_BUILD_DIRECTORY Ns = Ns Oo Sy false "|" true Oc
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:
.Sy false )
.It Sy CONFIGURE_VARS
Additional environment variable assignments while configure is run.
.It Sy CONFIGURE_WITH_BUILD_SYSROOT Ns = Ns Oo Sy false "|" true Oc
Whether to tell configure where the system root is located during the build
using the
.Fl \-with-build-sysroot
option.
(Default:
.Sy false )
.It Sy CONFIGURE_WITH_SYSROOT Ns = Ns Oo Sy false "|" true Oc
Whether to tell configure where the system root is located at runtime using the
.Fl \-with-sysroot
option.
(Default:
.Sy false )
.It Sy CONFIGURE_WITH_SYSROOT_LD_BUG Ns = Ns Oo Sy false "|" true Oc
Whether the
.Fl \-with-sysroot
option doesn't understand the empty string as meaning no system root will be
used at runtime and
.Fl \-with-sysroot Ns = Ns /
should be used instead.
(Default:
.Sy false )
.It Sy COMPRESSION Ns = Ns Oo Sy tar "|" tar.gz "|" tar.bz2 "|" tar.xz Oc
The file extension of
.Sy ARCHIVE
including the compression format.
.It Sy COMPRESSION_2 Ns = Ns Oo Sy tar "|" tar.gz "|" tar.bz2 "|" tar.xz Oc
For
.Sy ARCHIVE_2 .
.It Sy DEVELOPMENT Ns = Ns Oo Sy false "|" true Oc
Whether the port is in the development workflow per
.Xr porting 7 .
(Default:
.Sy false )
.Pp
If
.Sy 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.
.Pp
If
.Sy 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.
.It Sy DIRTY_FILE
The port doesn't need to be cleaned if this file doesn't exist.
(Default:
.Sy config.log ,
.Sy Makefile ,
and
.Sy makefile )
.It Sy DISTNAME
The name of the upstream release, usually
.Sy $NAME-$VERSION .
.It Sy DISTNAME_2
For
.Sy ARCHIVE_2 .
.It Sy DISTNAME_REGEX
Extended regular expression recognizing distnames of releases with the version
number matched in the first subexpression.
(Default: Automatically determined using
.Sy ARCHIVE
and
.Sy VERSION_REGEX )
.It Sy 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
.Sy RENAMES
variable can be used in combination with
.Sy EDITION
to rename and split packages.
The default edition is 1.
.It Sy IS_SET Ns = Ns Oo Sy false "|" true Oc
Whether the bootloader should offer this port as a reasonable subset of ports
expressed recursively in
.Sy RUNTIME_DEPS .
.It Sy LICENSE
Primary license identifier for the installed files from the
.Lk https://spdx.org/licenses/ "SPDX License List" .
Library ports use the license for linking with the library.
.It Sy LOCATION_INDEPENDENT Ns = Ns Oo Sy false "|" true Oc
Whether binary packages are location independent, i.e. can be installed in
another prefix than one supplied at build time.
(Default:
.Sy false )
.It Sy MAKE
The
.Xr make 1
program to use.
(Default: Search the PATH for the program in the
.Ev MAKE
environment variable or
.Xr make 1
as a fallback)
.It Sy MAKE_ARGS
Additional arguments passed to make.
.It Sy MAKE_BUILD_TARGET
Build the port by making this target.
(Default:
.Sy all )
.It Sy MAKE_CLEAN_TARGET
Clean the port by making this target.
(Default:
.Sy distclean
if
.Sy BUILD_SYSTEM=configure
and
.Sy clean
otherwise)
.It Sy MAKE_IGNORE_CLEAN_FAILURE Ns = Ns Oo Sy false "|" true Oc
Whether to silently ignore if cleaning the port failed.
(Default:
.Sy true )
.It Sy MAKE_INSTALL_TARGET
Install the port by making this target with the
.Ev DESTDIR
environment variable set to a temporary secondary prefix for the purpose of
installation-time packaging.
(Default:
.Sy install )
.It Sy MAKE_VARS
Additional environment variable assignments while make is run.
.It Sy NAME
The name of the port.
.It Sy NEED_WRITABLE Ns = Ns Oo Sy false "|" true Oc
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:
.Sy false )
.It Sy POST_INSTALL
Optional program to invoke post-installation to fix up the installation.
The
.Sy TIX_BUILD_DIR ,
.Sy TIX_SOURCE_DIR ,
.Sy TIX_INSTALL_DIR ,
.Sy TIX_SYSROOT ,
.Sy BUILD ,
.Sy HOST ,
.Sy TARGET ,
.Sy PREFIX ,
and
.Sy EXEC_PREFIX
environment variables are set and unset appropriately.
.It Sy RELEASE_SEARCH_PAGE
Upstream URL listing the available versions of the port.
.It Sy RELEASE_SEARCH_REGEX
Locate new upstream versions of the port by searching
.Sy RELEASE_SEARCH_PAGE
using this regular expression matching the new version number in the first
subexpression.
.It Sy RENAMES
Comma-separated list of package renames.
Each rename is expressed as the name of a package followed by a
.Sq "@"
and its
.Sy EDITION ,
followed by a
.Sq ":"
and then a potentially-empty space separated list of replacement packages, each
taking the form of a replacement package name followed by
.Sq "@"
and then the replacement package
.Sy EDITION .
.It Sy RUNTIME_DEPS
Space delimited list of ports needed at run time.
.It Sy SHA256SUM
.Xr sha256sum 1
of the upstream release.
.It Sy SHA256SUM_2
For
.Sy ARCHIVE_2 .
.It Sy SOURCE_PORT
Use the named port's source code instead.
.It Sy SUBDIR
Run the build commands in this subdir.
.It Sy UPGRADE_BLOCKED
A reason why upgrading to a newer version is blocked.
.It Sy UPSTREAM_ARCHIVE
The filename of the upstream release on
.Sy UPSTREAM_SITE ,
usually
.Sy $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
.Sy ARCHIVE
is set to a unique filename for use in the mirror.
.It Sy UPSTREAM_ARCHIVE_2
For
.Sy ARCHIVE_2 .
.It Sy UPSTREAM_SITE
Download releases from this upstream URL (without a trailing slash) in case the
mirror fails.
.It Sy UPSTREAM_SITE_2
For
.Sy ARCHIVE_2 .
.It Sy USE_BOOTSTRAP Ns = Ns Oo Sy false "|" true Oc
Bootstrap a new version of this port by first building a local version installed
into a temporary directory in the
.Ev PATH
and then use it to build the final version.
(Default:
.Sy false )
.Pp
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
.Sy BOOTSTRAP_
with the same semantics as their counterparts, e.g.:
.Pp
.Bl -tag -compact -width "12345678"
.It Sy BOOTSTRAP_BUILD_SYSTEM
.It Sy BOOTSTRAP_CONFIGURE
.It Sy BOOTSTRAP_CONFIGURE_ARGS
.It Sy BOOTSTRAP_CONFIGURE_USE_BUILD_DIRECTORY
.It Sy BOOTSTRAP_CONFIGURE_VARS
.It Sy BOOTSTRAP_MAKE
.It Sy BOOTSTRAP_MAKE_ARGS
.It Sy BOOTSTRAP_MAKE_VARS
.El
.It Sy VERSION
The version of the port.
If the version number components are used individually, define them as
.Sy VERSION_MAJOR ,
.Sy VERSION_MINOR ,
and
.Sy VERSION_PATCH
and define
.Sy VERSION
as
.Sy $VERSION_MAJOR.$VERSION_MINOR.$VERSION_PATCH .
.It Sy VERSION_2
For
.Sy ARCHIVE_2 .
.It Sy VERSION_REGEX
Extended regular expression parsing the version number with the full version in
the first subexpression.
(Default:
.Sq ([0-9]+\.[0-9]+(\.[0-9]+)*) )
.El
.Pp
The following environment variables are set by default during the port build:
.Bl -tag -width "12345678"
.It Ev CC
The C compiler.
.It Ev CFLAGS
Command line options when compiling C code.
.It Ev DESTDIR
An optional extra prefix used when installing the port for packaging.
.It Ev PKG_CONFIG
The
.Xr pkg-config 1
to use for locating dependencies.
.El
.Sh SEE ALSO
.Xr development 7 ,
.Xr porting 7 ,
.Xr tix-vars 8
.Sh HISTORY
The
.Nm
format originally appeared in Sortix 1.1 as the semantic continuation of the
former
.Pa tixbuildinfo
format introduced in Sortix 0.8.