.\" $NetBSD: pbulk-build.1,v 1.6 2023/09/29 08:22:48 abs Exp $
.\"
.\" Copyright (c) 2007 Thomas Klausner and Joerg Sonnenberger.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd February 7, 2023
.Dt PBULK-BUILD 1
.Os
.Sh NAME
.Nm pbulk-build
.Nd build all packages specified in input file
.Sh SYNOPSIS
.Nm
.Fl s Oo Ar host: Oc Ns Ar port
.Nm
.Op Fl v
.Fl c Oo Ar host: Oc Ns Ar port
.Fl b Ar build_script
.Nm
.Op Fl I Ar start_script
.Op Fl r Ar report_file
.Op Fl v
.Fl m Oo Ar host: Oc Ns Ar port
.Ar input success error
.Nm
.Op Fl r Ar report_file
.Op Fl v
.Fl b Ar build_script
.Ar input success error
.Sh DESCRIPTION
.Nm
builds all packages specified in an input file.
.Pp
Supported options are:
.Bl -tag -width 15n -offset indent
.It Fl b Ar build_script
Use
.Ar build_script
for building the packages.
See
.Sx BUILD SCRIPT FORMAT
for details.
.It Fl c Oo Ar host: Oc Ns Ar port
Obtain jobs from master running on the given
.Ar port
(or
.Ar host:port ) .
If used with
.Fl v ,
print the name of the package to build to stdout.
.It Fl I Ar start_script
Run
.Ar start_script
after opening the socket and wait for completion before entering build loop.
.It Fl m Oo Ar host : Oc Ns Ar port
Enter master mode.
The master binds to
.Ar port
(or
.Ar host:port )
and waits for clients to connect and build individual packages.
.It Fl s Oo Ar host: Oc Ns Ar port
Query the master running on the given
.Ar port
(or
.Ar host:port )
for the current number of successful, open, and failed builds.
.It Fl r Ar report_file
Write name of each package,
the result of its build,
whether the package belongs to the restricted subset
and the size of the subtree
to
.Ar report_file
at the end of the build.
.It Fl v
Be more verbose.
Details depend on the other flags used with it.
.El
In normal mode (neither
.Fl c ,
.Fl m ,
nor
.Fl s
specified) and master mode
.Pq Fl m ,
.Nm
reads the resolved tree scan from
.Ar input .
It then writes successful builds to
.Ar success
and failing builds to
.Ar error .
If either
.Ar success
or
.Ar error
exists at start-up, they are read and the build continues where
they left off.
If
.Fl v
is specified once,
.Nm
prints the start of each build and the result.
If
.Fl v
is specified twice, each begin and end message is prefixed with
the current time.
.Ss BUILD SCRIPT FORMAT
The
.Ar build_script
is given information about one package which it should build.
It should return 0 on success or any other value for an error.
The
.Ar build_script
gets the information in a number of variables provided on standard input.
The variables are provided in the format
.Dl VARIABLE=value
The following variables are provided as of February 2023:
.Bl -tag -width 20n
.It Dv PKGNAME
Name of the package including the version number, e.g.
.Dq pbulk-0.54 .
.It Dv PKG_LOCATION
Path to the package below
.Pa pkgsrc ,
e.g.
.Dq pkgtools/pbulk .
.It Dv ALL_DEPENDS
All dependencies of the package in one line, as determined by the
dependency resolution step, in the following format:
.Dl digest>=20211023:../../pkgtools/digest libtool-base>=2.4.2nb9:../../devel/libtool-base ...
.It Dv PKG_SKIP_REASON
A string containing the reason if the package should be skipped.
Usually an empty string.
.It Dv PKG_FAIL_REASON
A string containing the reason if the package failed the dependency resolution
or is broken for another reason.
Usually an empty string.
.It Dv NO_BIN_ON_FTP
A string containing the reason why the binary package may not be uploaded to
.Lk ftp.NetBSD.org .
Usually an empty string.
.It Dv RESTRICTED
A string containing the reason why the binary package may not be distributed.
.It Dv CATEGORIES
Categories to which the package belongs, as specified in its Makefile.
.It Dv MAINTAINER
Maintainer of the package, as specified in its Makefile.
.It Dv USE_DESTDIR
DESTDIR method this package supports.
Now almost exclusively
.Dq user-destdir .
.It Dv BOOTSTRAP_PKG
If this package is used during pkgsrc bootstrap (as specified in its Makefile).
Usually empty.
.It Dv USERGROUP_PHASE
The phase of the build process during which the user and/or group
needed by this package need to be available.
.It Dv SCAN_DEPENDS
List of files (in a single line) read during the dependency scanning step.
Can be used to identify if a package needs to be updated because on of these files
changed compared to the previous build.
Example:
.Dl /usr/pkgsrc/pkgtools/pbulk/../../mk/tools/tools.NetBSD.mk /usr/share/mk/bsd.host.mk /usr/share/mk/bsd.own.mk /usr/share/mk/sys.mk Makefile options.mk
.It Dv MULTI_VERSION
For some languages or databases (or similar), pkgsrc contains multiple
major versions at the same time, and supports building a single
package against more than one of these.
This variable contains a list of variables (in a single line) to
determine which of these versions this particular package should be
built against.
Example:
.Dl MULTI_VERSION= PYTHON_VERSION_REQD=311 LUA_VERSION_REQD=52
means to build against Python 3.11 and Lua 5.2.
This variable is missing completely for packages that do not provide
multi-package support.
.It Dv DEPENDS
.Dv PKGNAME Ap s
of the packages this package depends on (including their version number).
Example:
.Dl DEPENDS=digest-20220214 libtool-base-2.4.7nb1
.It Dv PBULK_WEIGHT
Numeric build priority of the package.
If this variable is not present, a value of 100 is assumed.
.Pp
The effective weight of a package is the sum of the weights of the
package itself and all packages transitively depending on it.
If two packages are buildable at the same time, the package with
the higher effective weight is built first.
.El
These items correspond to the output of
.Dl make pbulk-index-item
run in the package directory with the additional variables
.Dv PKG_LOCATION
and
.Dv DEPENDS
computed by the pbulk scan phase.
.\" XXX: .Sh EXIT STATUS