.Dd December 27, 2024
.Dt TIX-METABUILD 8
.Os
.Sh NAME
.Nm tix-metabuild
.Nd build packages from ports
.Sh SYNOPSIS
.Nm
.Op Fl \-build Ns = Ns Ar triplet
.Op Fl \-build-id Ns = Ns Ar build-id
.Op Fl \-cache-package
.Op Fl \-collection Ns = Ns Ar collection
.Op Fl \-destination Ns = Ns Ar directory
.Op Fl \-distclean
.Op Fl \-download-package
.Op Fl \-end Ns = Ns Ar step
.Op Fl \-exec-prefix Ns = Ns Ar prefix
.Op Fl \-generation Ns = Ns Ar level
.Op Fl \-host Ns = Ns Ar triplet
.Op Fl \-hosts Ns = Ns Ar triplets
.Op Fl \-main Ns = Ns Ar url
.Op Fl \-make Ns = Ns Ar path
.Op Fl \-makeflags Ns = Ns Ar makeflags
.Op Fl \-metadata
.Op Fl \-mirror Ns = Ns Ar url
.Op Fl \-mirror-directory Ns = Ns Ar directory
.Op Fl \-mirrors Ns = Ns Ar urls
.Op Fl \-packages Ns = Ns Ar packages
.Op Fl \-prefix Ns = Ns Ar prefix
.Op Fl \-public-key Ns = Ns Ar path
.Op Fl \-randomize
.Op Fl \-release Ns = Ns Ar release
.Op Fl \-release-directory Ns = Ns Ar directory
.Op Fl \-release-key Ns = Ns Ar file
.Op Fl \-release-info
.Op Fl \-release-url Ns = Ns Ar url
.Op Fl \-repository Ns = Ns Ar directory
.Op Fl \-secret-key Ns = Ns Ar path
.Op Fl \-sign
.Op Fl \-start Ns = Ns Ar step
.Op Fl \-sysroot Ns = Ns Ar directory
.Op Fl \-sysroot-download-packages Ns = Ns Ar packages
.Op Fl \-sysroots Ns = Ns Ar directory
.Op Fl \-tar Ns = Ns Ar path
.Op Fl \-target Ns = Ns Ar triplet
.Op Fl \-tmp Ns = Ns Ar directory
.Op Fl \-version Ns = Ns Ar version
.Ar ports
.Sh DESCRIPTION
.Nm
builds each port in the
.Ar ports
directory and creates a repository with the binary packages.
Each port is in its own subdirectory named after it, containing the
.Xr port 5
The
.Fl \-packages
option can be used to select which packages to build.
.Nm
determines the build order using
.Xr tix-list-packages 8 ,
and then builds and installs the packages in order using
.Xr tix-port 8 ,
forwarding all the appropriate options.
.Nm
is usually invoked through
.Xr development 7
for the official ports.
.Pp
If the end of the build is beyond the
.Sy clean
phase, then the tix collection is automatically created if needed using
.Xr tix-collection 8
before the builds begin.
.Pp
Optionally
.Nm
can create a tix release and sign it per the
.Fl \-metadata ,
.Fl \-release-info ,
and
.Fl \-sign
options which invoke
.Xr tix-repository 8
appropriately.
.Pp
The options are as follows:
.Bl -tag -width "12345678"
.It Fl \-build Ns = Ns Ar triplet
The platform
.Ar triplet
for the machine the port is built on.
(Default: Automatically detected.)
.It Fl \-build-id Ns = Ns Ar build-id
The overall build identifier, such as a git commit hash, forwarded to the
.Xr tix-collection 8
.Sy create
and
.Xr tix-repository
.Sy release
invocations.
.It Fl \-cache-package
Skip the build if the binary package already exists and is the right version.
.It Fl \-collection Ns = Ns Ar collection
Install the binary package into this
.Ar collection
created with
.Xr tix-collection 8 .
(Default:
.Fl \-sysroot
plus
.Fl \-prefix )
.It Fl \-destination Ns = Ns Ar directory
The binary package is placed inside this
.Ar directory .
.It Fl \-download-package
Download an existing binary package from the collection using
.Xr tix-fetch 8
and use it if it is the right version as per
.Fl \-cache-package .
.It Fl \-distclean
Clean the port for distribution.
Remove the extraction and all the metadata files.
If
.Sy DEVELOPMENT
is
.Sy true
in the
.Xr port 5 ,
then emit a warning, and do nothing to avoid deleting any in-progress work.
.It Fl \-end Ns = Ns Ar step
Stop the build after this
.Ar step :
.Pp
.Bl -tag -width "clean, pre-clean" -compact
.It start
The start step before anything has happened.
.It download
Download the source code.
.It extract
Extract the source code and apply patches.
.It tix-build-start
The start step in
.Xr tix-build 8 .
.It clean, pre-clean
Clean the source directory before the build.
.It configure
Configure the port.
.It build
Build the port.
.It install
Install the port into the
.Ev DESTDIR .
.It post-install
Run the post-installation script.
.It post-clean
Clean the source code after the port.
.It package
Create the binary package.
.It tix-build-end
The end step in
.Xr tix-build 8 .
.It strip
Strip the executables in the binary package.
.It diff
Regenerate the patches if in development.
.It tix-install
Install the binary package.
.It end
The end step after everything has happened.
(Default)
.El
.It Fl \-exec-prefix Ns = Ns Ar prefix
The
.Ar prefix
where architecture dependent files are installed.
(Default:
.Fl \-prefix )
.It Fl \-generation Ns = Ns Ar generation
Create a binary package in the format of this tix generation
.Ar level .
(Default: 3)
.It Fl \-host Ns = Ns Ar triplet
The platform
.Ar triplet
for the machine the port will run on.
(Default:
.Fl \-build )
.It Fl \-hosts Ns = Ns Ar triplets
Build binary packages for each
.Fl \-host
triplet in the space-separated
.Ar triplets list.
The
.Fl \-sysroots
option is useful for cross-compilation.
.It Fl \-main Ns = Ns Ar url
The URL to the main mirror in the release information.
Forwarded to the
.Xr tix-repository 8
.Sy release
invocation.
This option is usually not used, as the mirror feature should be used in a
.Xr tix-repository 8
.Sy channel
instead.
.It Fl \-make Ns = Ns Ar path
Which
.Xr make 1
to use.
(Default:
.Ev MAKE
if set and otherwise
.Xr make 1 )
.It Fl \-makeflags Ns = Ns Ar makeflags
Override the
.Ev MAKEFLAGS
variable inherited by make.
.It Fl \-metadata
After building the packages, run the
.Xr tix-repository 8
metadata command to generate the tix repository metadata from the binary
packages.
.It Fl \-mirror Ns = Ns Ar url
First attempt to download the upstream releases from the port's source code
mirror at
.Ar url
before attempting the upstream site.
The files are copied from the filesystem if the
.Ar url
has no schema.
.It Fl \-mirror-directory Ns = Ns Ar directory
Place the downloaded upstream releases in this
.Ar directory
in the layout that can be used as a mirror for the
.Fl \-mirror
option.
(Default:
.Ar port Ns Pa .mirror )
.It Fl \-mirrors Ns = Ns Ar url
The space-separated URLs to the secondary mirrors in the release information.
Forwarded to the
.Xr tix-repository 8
.Sy release
invocation.
This option is usually not used, as the mirror feature should be used in a
.Xr tix-repository 8
.Sy channel
instead.
.It Fl \-packages Ns = Ns Ar packages
Build these
.Ar packages
as evaluated by
.Xr tix-list-packages 8 .
The defaullt is
.Sq all!! .
.It Fl \-prefix Ns = Ns Ar prefix
Build the port into this
.Ar prefix .
(Default: The empty prefix designating the root directory)
.It Fl \-public-key Ns = Ns Ar path
The public key to use for the
.Fl \-sign
option.
Forwarded to the
.Xr tix-repository
.Sy sign
invocation.
.It Fl \-randomize
Build the ports in a random order while still respecting the build dependencies.
.It Fl \-release Ns = Ns Ar release
The name of the
.Ar release .
Forwarded to the
.Xr tix-repository
.Sy release
invocation.
.It Fl \-release-directory Ns = Ns Ar release
Place the binary package inside the
.Pa $release/repository/$host
directory, if the
.Fl \-destination
and
.Fl \-repository
options are not set.
.It Fl \-release-key Ns = Ns Ar file
Copy the release public key from the
.Pa file ,
forwarded to the
.Xr tix-collection 8
.Sy create
invocation.
.It Fl \-release-info
Generate the top-level release information by invoking
.Xr tix-repository 8
.Sy release .
Implies the
.Fl \-metadata
option and requires the
.Fl \-build-id ,
.Fl \-release ,
and
.Fl \-version
options to be set.
.It Fl \-release-url Ns = Ns Ar url
The url to the location where the release being built will be published,
.Pa file ,
forwarded to the
.Xr tix-collection 8
.Sy create
invocation.
.It Fl \-repository Ns = Ns Ar repository
Place the binary package inside the
.Pa $repository/$host
directory, if the
.Fl \-destination
option is not set.
.It Fl \-secret-key Ns = Ns Ar path
The secret key to use for the
.Fl \-sign
option.
Forwarded to the
.Xr tix-repository
.Sy sign
invocation.
.It Fl \-sign
Sign the top-level release information by invoking
.Xr tix-repository 8
.Sy sign .
Implies the
.Fl \-metadata
and
.Fl \-release-info
option and requires the
.Fl \-build-id ,
.Fl \-public-key ,
.Fl \-release ,
.Fl \-secret-key ,
and
.Fl \-version
options to be set.
.It Fl \-start Ns = Ns Ar step
Start the build at this step (see
.Fl \-end ) .
(Default:
.Sy start )
.It Fl \-sysroot Ns = Ns Ar directory
The system root to use while building and installing the port.
The toolchain is wrapped to transparently use this sysroot during the build.
.It Fl \-sysroot-download-packages Ns = Ns Ar packages
Create a
.Xr tix-collection 8
inside the system root if needed by importing the configuration from the
.Pa /
collection, and then download and install the packages in the space-separated
.Ar packages
list along with their runtime dependencies.
The
.Sy system
package is useful to get the headers and libraries for the base system.
.It Fl \-sysroots Ns = Ns Ar directory
In combination with
.Fl \-hosts,
use system roots named after the triplets in the
.Ar directory
for cross-compilation.
.It Fl \-tar Ns = Ns Ar path
Which
.Xr tar 1
to use during the build.
(Default:
.Xr tar 1 )
.It Fl \-target Ns = Ns Ar triplet
The port's outputs targets this platform
.Ar triplet .
(Default:
.Fl \-host )
.It Fl \-tmp Ns = Ns Ar directory
Place temporary files in this
.Ar directory .
(Default:
.Ev TMPDIR
if set otherwise
.Pa /tmp )
.It Fl \-version Ns = Ns Ar version
The
.Ar version
number of the release.
Forwarded to the
.Xr tix-repository
.Sy release
invocation.
.El
.Sh EXIT STATUS
.Nm
will exit 0 on success and non-zero otherwise.
.Sh EXAMPLES
.Ss Create a new tix release
First create a signing key either to be reused across releases, or a per-release
signing key to be rotated:
.Bd -literal
mkdir -p keys
signify -G -c 'local repository signing key' -p keys/local.pub -s keys/local.sec
.Ed
.Pp
Use the
.Xr signify 1
.Fl n
option to omit the password for unattended signing.
.Pp
Create a tix release with custom
.Xr port 5
packages from the
.Pa ports
directory, meant to be installed into
.Pa /local ,
cross-compiling to multiple hosts using downloaded system roots
containing the base system, and create it as the 1.0 release signed with the
secret key:
.Bd -literal
tix-metabuild \\
  --build-id=$(git rev-parse HEAD) \\
  --hosts='i686-sortix x86_64-sortix' \\
  --prefix=/local \\
  --public-key=keys/local.pub \\
  --release=1.0 \\
  --release-directory=release/1.0 \\
  --secret-key=keys/local.sec \\
  --sign \\
  --sysroot-download-packages=minimal \\
  --sysroots=sysroots \\
  --version=1.0 \\
  ports
.Ed
.Pp
The
.Pa release
directory can published after signing.
.Pp
Next use the
.Xr tix-repository 8
.Sy channel
command to provide a layer of indirection with dynamic data such as available
upgrades and available mirrors.
The release directory is meant to be immutable whereas the channel is modified
and resigned as needed.
See
.Xr tix-repository 8
for more information.
.Sh SEE ALSO
.Xr signify 1 ,
.Xr port 5 ,
.Xr development 7 ,
.Xr porting 7 ,
.Xr tix-collection 8 ,
.Xr tix-install 8 ,
.Xr tix-list-packages 8 ,
.Xr tix-port 8 ,
.Xr tix-repository 8
.Sh HISTORY
.Nm
originally appeared in Sortix 1.1.