-.\" $OpenBSD: bsd.port.mk.5,v 1.568 2022/09/10 05:50:40 jmc Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.569 2022/09/11 06:41:36 jmc Exp $
.\"
.\" Copyright (c) 2000-2008 Marc Espie
.\"
.\" (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 $Mdocdate: September 10 2022 $
+.Dd $Mdocdate: September 11 2022 $
.Dt BSD.PORT.MK 5
.Os
.Sh NAME
unreproducible builds.
Set to bison if needed.
.El
-.Sh DIAGNOSTICS
-Note that some of these messages are actually emitted by some other external
-commands, but grouped here for convenience: easier to look for in
-.Xr dpb 1 Ns 's
-logs.
-.Bl -diag
-.It "/bin/sh: cd .../pkg - No such file or directory"
-Emitted during
-.Cm generate-readmes .
-.Pa ${PKGDIR}
-must point to an existing directory, so that
-.Nm
-can be certain there are no
-.Pa MESSAGEs
-or
-other files pertinent to the package.
-.It "Discovered old directory in ..."
-This message comes from
-.Xr update-plist 1 .
-A directory was found in the packing-list file mentioned in the diagnostic.
-That directory line used to be needed but is no longer,
-because it's now accounted for through dependencies.
-Indicates the old directory has been removed.
-.It "Error: change in plist between ..."
-Error message comes from
-.Xr register-plist 1 .
-.It "Error: duplicate item in packing-list"
-Error message comes from
-.Xr pkg_create 1 ,
-and will result from incorrect packing-lists, such as including several
-fragments with the same file, or having incorrect
-.Ev PKG_ARGS-sub .
-.It "Error: Libraries in packing-lists...and libraries from installed packages don't match"
-The ports tree and the installed packages are out-of-sync.
-Mixing library information from both sources might produce packages that can't
-be installed elsewhere.
-Cleanest fix is to update the out-of-date source (e.g., update the ports tree,
-or build and install new packages).
-Developers may use
-.Ev PKG_CREATE_NO_CHECKS
-instead, assuming they understand the implications.
-See
-.Cm print-package-args Pq Cm wantlib-args
-for details.
-.It "Fatal: can't flavor a SUBDIR"
-A dependency mentions top_subdir,flavor.
-Flavor would then be ignored, as it is only applied to individual ports.
-.It "Fatal: can't subpackage a SUBDIR"
-A dependency mentions top_subdir,-sub.
-Subpackage would then be ignored, as it is only applied to individual ports.
-.It "Fatal: flavor should never start with a digit"
-This would utterly confuse
-.Xr pkg_add 1 .
-See
-.Xr packages-specs 7 .
-.It "Fatal: inclusion of <file> from <file>"
-.Pa bsd.port.mk
-or
-.Pa bsd.port.subdir.mk
-has been included from a
-.Ev MODULE
-or from
-.Pa Makefile.inc ,
-resulting in a double inclusion.
-This would lead to weird results, such as
-.Ev PKG_ARGS
-being defined twice.
-.It "Fatal: SUBPACKAGES should always begin with -: <offending list>"
-That is the only way to differentiate between
-.Ev FLAVOR
-and
-.Ev SUBPACKAGE
-in
-.Xr pkgpath 7
-specifications.
-.It "Fatal: building ports requires correctly installed X11"
-All file sets of the base OS, including xenocara, must be installed
-before building ports.
-.It "Fatal: /usr/local/lib/X11/app-defaults should exist and be a symlink"
-/usr/local/lib/X11/app-defaults is distributed as a symlink in the
-xshare*.tgz file set.
-If xenocara was not fully installed before packages were added, it may
-have been created as a directory instead.
-.It "Fatal: the licensing info for <pkgname> is incomplete..."
-Every port must have explicit defines of all
-.Ev PERMIT_*
-values.
-.It "Fatal: Use 'env FLAVOR=flavor make' instead"
-Arguments specified after
-.Xr make 1
-are hardcoded for all recursive sub-makes, and very difficult to override.
-Thus,
-.Ev FLAVOR
-must be specified in the environment instead.
-.It "Fatal: Use 'env SUBPACKAGE=-sub make' instead"
-Arguments specified after
-.Xr make 1
-are hardcoded for all recursive sub-makes, and very difficult to override.
-Thus,
-.Ev SUBPACKAGE
-must be specified in the environment instead.
-.It "ldconfig: <dir>: No such file or directory"
-Usually produced by
-.Xr pkg_add 1
-running
-.Xr ldconfig 8 .
-Some tools such as GNU libtool will add directories living under
-.Pa ${WRKINST}
-to the shared library path during the
+.Sh THE FAKE FRAMEWORK
+The
.Cm fake
-stage.
-Of course,
-.Xr ldconfig 8
-will later complain after the directory no longer exists.
-The bogus tool should be fixed to conform to
-.Ox
-usage.
-.It LIB_DEPENDS <spec> not needed for <FULLPKGPATH>
-There doesn't seem to be any WANTLIB to match the given LIB_DEPENDS.
-Thus, the LIB_DEPENDS won't turn into a @depends line in the created package.
-This is often because of confusion between LIB_DEPENDS and RUN_DEPENDS:
-RUN_DEPENDS is needed for dlopen'd libraries.
+target is used to install the port in a private directory first, ready for
+packaging by the
+.Cm package
+target, so that the actual installation will use the package.
.Pp
-Might be intentional sometimes, if some compile flavors create static binaries,
-for instance.
-Also, will happen for multi-packages, where one sets LIB_DEPENDS to have
-a given build dependency (and corresponding WANTLIB for a given SUBPACKAGE).
+Essentially,
+.Cm fake
+invokes a real install process after tweaking a few variables.
.Pp
-See
-.Cm print-package-args Pq Cm lib-depends-args
-for details.
-.It "Warning: FULLPKGNAME-sub defined but not FULLPKGPATH-sub"
-.Ev FULLPKGNAME-sub
-has been explicitly defined by the port, instead of relying on the default,
-but no value of
-.Ev FULLPKGPATH-sub
-has been given.
-This is often an error.
-.It "Warning: no debug-info in ..."
-Port uses
+.Cm fake
+first creates a skeleton tree under ${WRKINST}, using
+.Xr mkdir 1
+.Fl p .
+.Pp
+A
+.Cm pre-fake
+target may be used to complete that skeleton tree.
+For instance, a few ports may need supplementary stuff to be present (as
+it would be installed if the port's dependencies were present).
+.Pp
+If
+.Cm {pre,do,post}-install
+overrides are present, they are used with some
+important changes, listed in
+.Ev FAKE_SETUP :
+.Bd -literal -offset indent
+TRUEPREFIX=${PREFIX}
+PREFIX=${WRKINST}${PREFIX}
+${DESTDIRNAME}=${WRKINST}
+.Ed
+.Pp
+Essentially, old install targets work transparently, except for a need to
+change
+.Ev PREFIX
+to
+.Ev TRUEPREFIX
+for symbolic links and similar path lookups.
+Specific traditional post install work can be simply removed, as it will
+be taken care of by the package itself (for instance, ldconfig, or
+texinfo's install-info).
+.Pp
+If no
+.Cm do-install
+override is present, the port is installed using
+.Bd -literal -offset 2n
+env -i ${MAKE_ENV} ${FAKE_SETUP} ${MAKE_PROGRAM} ${ALL_FAKE_FLAGS} -f ${MAKE_FILE} ${FAKE_TARGET}
+.Ed
+.Pp
+Note that this does set both PREFIX and ${DESTDIRNAME}.
+If a port's Makefile both heeds ${DESTDIRNAME},
+and references PREFIX explicitly,
+FAKE_FLAGS may rectify the problem by setting PREFIX=${PREFIX}
+(which will do the right thing, since ${PREFIX} is a
+.Xr make 1
+construct which will not be seen by the shell).
+.Pp
+${FAKE_FLAGS} is used to set variables on
+.Xr make 1
+command line, which will override the port Makefile contents.
+Thus, a port that mentions DESTDIR= does not need any patch to work with fake.
+.Pp
+Files such as
+.Pa ${PKGDIR}/README*
+or
+.Pa ${PKGDIR}/*.rc
+get copied to
+.Pa ${WRKINST}
+right after the end of
+.Cm fake ,
+during
+.Cm generate-readmes
+(see the
+.Sx FILES
+section above for details).
+.Sh THE DEBUG_PACKAGES INFRASTRUCTURE
+If
.Ev DEBUG_PACKAGES
-so the
+is not empty, debug packages will be built "on the side".
+Since debug information is usually large, this is controlled on a per-arch
+basis with
+.Ev DEBUGINFO_ARCHS
+controlling the behavior (set to amd64 by default).
+.Pp
+During the normal
+.Cm package
+target ,
.Xr build-debug-info 1
-script expects debug information on all binaries and libraries.
-Most probably, the build machinery for that specific port omitted -g
-somewhere, or it runs strips during fake anyway.
-It can also occur if
-.Ev DEBUG_PACKAGES
-includes subpackages with no files holding debug info.
-.It "Warning: symlink(s) point to non existent file."
-Warning message comes from
-.Xr pkg_create 1 .
-The symlink resides in the fake area, under
-.Pa ${WRKINST} .
-This is only a warning because the symlink may point to a run-time dependency,
-which obviously won't exist under
-.Pa ${WRKINST}
-at the time
-.Ql make package
-is run.
-.It "Warning: @option no-default-conflict with no @conflict"
-Warning message comes from
-.Xr pkg_create 1 .
-Most packages that waive "default-conflict" will have explicit conflict markers
-instead.
-Otherwise, the package will only conflict with the exact same version, with
-some possible
-.Ev REVISION
-bumps.
-Any other version or
-.Ev FLAVOR
-won't conflict.
-This is generally an error, apart from very few ports like
-.Pa devel/autoconf/* .
-.It "groff produced empty result for <manpage>..."
-Warning message comes from
-.Xr pkg_create 1 .
-Manpages are automatically formatted with
-.Xr groff 1
-if
-.Ev USE_GROFF
-is set.
-The above message denotes an actual problem while formatting the page,
-which should be addressed.
-In the meantime,
-.Xr pkg_create 1
-still produces a package, but leaves the manpage unformatted, in the hope
-that something will be able to make sense of it.
-.El
-.Sh FILES
-.Bl -tag -width Ds
-.It Pa ../Makefile.inc
-Common Makefile fragment for a set of ports, included automatically.
-.It Pa /cdrom/distfiles
-Default path to a CD-ROM (or other media) full of distribution files.
-.It Pa ${PORTSDIR}/distfiles
-Default setup of ${DISTDIR}.
-.It Pa ${DISTDIR}
-Cache of all distribution files.
-.It Pa distinfo
-Checksum file.
-Holds the output of
-.Xr cksum 1 ,
-using
-.Xr sha256 1
-for the port's ${DISTFILES} and ${PATCHFILES},
-as well as the sizes of these files.
-.It Pa ${DISTDIR}/${CHECKSUMFILES}
-Cache of normal distribution files for a given port.
-.It Pa ${DISTDIR}/${MAKESUMFILES}
-Cache of all distribution files for a given port.
-.It Pa ${PORTSDIR}/infrastructure/mk/*.mk
-Actual location of the
-.Xr make 1
-glue for the ports tree.
-.Xr make 1
-looks for
-.Pa bsd.port.mk
-.Po
-and
-.Pa bsd.port.subdir.mk
-.Pc
-under
-.Pa /usr/share/mk/bsd.port.mk ,
-but that file is just a stub that redirects to the real location.
-.It Pa ${PKGDIR}/DESCR
-Description for the port.
-Variables such as ${HOMEPAGE} and ${MAINTAINER} will be expanded
-(see SUBST_VARS).
-Multi-package ports will use DESCR${SUBPACKAGE}.
-.It Pa ${PKGDIR}/README
-.Ox
-specific documentation for a port, that will be installed as
-.Pa ${LOCALBASE}/share/doc/pkg-readmes/${PKGSTEM}
-at the end of
-.Cm fake .
-Variables from
-.Ev SUBST_VARS
-will be expanded.
-Multi-package ports will use
-.Pa README${SUBPACKAGE} .
-.It Pa ${PKGDIR}/<foo>.login
-login.conf.d file for class <foo>.
-Will be installed as
-.Ar ${PREFIX}/share/examples/login.conf.d/foo
-at the end of
-.Cm fake .
-When a port provides a daemon started by
-.Xr rc.d 8
-requiring non-default
-.Xr login.conf 5
-attributes, a sample file should be provided
-and used as a template by adding
-.Cm @sample /etc/login.conf.d/${ Ns Va class Ns }
-to the packing list.
-.It Pa ${PKGDIR}/<foo>.rc
-Startup script for <foo>.
-Will be installed as
-.Ar ${RCDIR}/<foo>
-at the end of
-.Cm fake .
-Variables from
-.Ev SUBST_VARS
-will be expanded.
-.It Pa ${PORTSDIR}/plist
-Default setup of ${PLIST_REPOSITORY}.
-.It Pa ${PORTSDIR}/packages
-Default setup of ${PACKAGE_REPOSITORY}.
-.It Pa ${PACKAGE_REPOSITORY}/no-arch
-Location of arch-independent packages.
-.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/all
-Location of all built packages.
-.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cache
-Location of packages retrieved through the network.
-.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cksums
-Location of checksums, see
-.Ev CHECKSUM_PACKAGES .
-.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cdrom
-Location of packages suitable for the CD.
-.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/ftp
-Location of packages suitable for FTP.
-.It Pa ${PORTSDIR}/bulk/${MACHINE_ARCH}
-Default setup of ${BULK_COOKIES_DIR}.
-.It Pa ${PORTSDIR}/update/${MACHINE_ARCH}
-Default setup of ${UPDATE_COOKIES_DIR}.
-.It Pa ${PORTSDIR}/mystuff
-Extra directory used to store local ports before committing them.
-All depend targets will normally look there after the normal lookup fails.
-See
-.Ev PORTSDIR_PATH .
-.El
-.Sh THE FAKE FRAMEWORK
-The
-.Cm fake
-target is used to install the port in a private directory first, ready for
-packaging by the
-.Cm package
-target, so that the actual installation will use the package.
-.Pp
-Essentially,
-.Cm fake
-invokes a real install process after tweaking a few variables.
-.Pp
-.Cm fake
-first creates a skeleton tree under ${WRKINST}, using
-.Xr mkdir 1
-.Fl p .
-.Pp
-A
-.Cm pre-fake
-target may be used to complete that skeleton tree.
-For instance, a few ports may need supplementary stuff to be present (as
-it would be installed if the port's dependencies were present).
-.Pp
-If
-.Cm {pre,do,post}-install
-overrides are present, they are used with some
-important changes, listed in
-.Ev FAKE_SETUP :
-.Bd -literal -offset indent
-TRUEPREFIX=${PREFIX}
-PREFIX=${WRKINST}${PREFIX}
-${DESTDIRNAME}=${WRKINST}
-.Ed
-.Pp
-Essentially, old install targets work transparently, except for a need to
-change
-.Ev PREFIX
-to
-.Ev TRUEPREFIX
-for symbolic links and similar path lookups.
-Specific traditional post install work can be simply removed, as it will
-be taken care of by the package itself (for instance, ldconfig, or
-texinfo's install-info).
-.Pp
-If no
-.Cm do-install
-override is present, the port is installed using
-.Bd -literal -offset 2n
-env -i ${MAKE_ENV} ${FAKE_SETUP} ${MAKE_PROGRAM} ${ALL_FAKE_FLAGS} -f ${MAKE_FILE} ${FAKE_TARGET}
-.Ed
-.Pp
-Note that this does set both PREFIX and ${DESTDIRNAME}.
-If a port's Makefile both heeds ${DESTDIRNAME},
-and references PREFIX explicitly,
-FAKE_FLAGS may rectify the problem by setting PREFIX=${PREFIX}
-(which will do the right thing, since ${PREFIX} is a
-.Xr make 1
-construct which will not be seen by the shell).
-.Pp
-${FAKE_FLAGS} is used to set variables on
-.Xr make 1
-command line, which will override the port Makefile contents.
-Thus, a port that mentions DESTDIR= does not need any patch to work with fake.
-.Pp
-Files such as
-.Pa ${PKGDIR}/README*
-or
-.Pa ${PKGDIR}/*.rc
-get copied to
-.Pa ${WRKINST}
-right after the end of
-.Cm fake ,
-during
-.Cm generate-readmes
-(see the
-.Sx FILES
-section above for details).
-.Sh THE DEBUG_PACKAGES INFRASTRUCTURE
-If
-.Ev DEBUG_PACKAGES
-is not empty, debug packages will be built "on the side".
-Since debug information is usually large, this is controlled on a per-arch
-basis with
-.Ev DEBUGINFO_ARCHS
-controlling the behavior (set to amd64 by default).
-.Pp
-During the normal
-.Cm package
-target ,
-.Xr build-debug-info 1
-will be invoked to deduce debug packing-lists from the normal packing-lists,
-and some extra makefile rules will be invoked to set aside the debug
-information.
-.Pp
-Then each normal package will have a "shadow" debug-* package built alongside
-it, with the exact same package signature, except it will also be tied closely
-with the normal package.
-.Pp
-Figuring out what files contain debug information is entirely achieved through
-.Cm @bin ,
-.Cm @lib ,
-.Cm @so
-and
-.Cm @static-lib
-annotations in the base packing-lists.
-.Pp
-Debug packages will be produced for all subpackages in
-.Ev DEBUG_PACKAGES .
-Usually, the heuristics of trimming arch-independent packages
-from
-.Ev BUILD_PACKAGES
-is enough.
-In case this still produces empty debug packages, the
+will be invoked to deduce debug packing-lists from the normal packing-lists,
+and some extra makefile rules will be invoked to set aside the debug
+information.
+.Pp
+Then each normal package will have a "shadow" debug-* package built alongside
+it, with the exact same package signature, except it will also be tied closely
+with the normal package.
+.Pp
+Figuring out what files contain debug information is entirely achieved through
+.Cm @bin ,
+.Cm @lib ,
+.Cm @so
+and
+.Cm @static-lib
+annotations in the base packing-lists.
+.Pp
+Debug packages will be produced for all subpackages in
+.Ev DEBUG_PACKAGES .
+Usually, the heuristics of trimming arch-independent packages
+from
+.Ev BUILD_PACKAGES
+is enough.
+In case this still produces empty debug packages, the
.Ev DEBUG_PACKAGES
list should be produced manually.
.Pp
automatically adds
.Li "-Dno_mips64=1"
or
-.Li "-Dno_mips64=0"
-to
-.Ev PKG_ARGS ,
-and the porter only needs to provide the appropriate fragment.
-.Pp
+.Li "-Dno_mips64=0"
+to
+.Ev PKG_ARGS ,
+and the porter only needs to provide the appropriate fragment.
+.Pp
+.Xr pkg_add 1
+now calls
+.Xr ldconfig 8
+directly, provided dynamic libraries have been annotated with
+.Li "@lib libthingy.so.5.0" .
+Adding new directories to the dynamic loader cache has been
+deprecated.
+It is often better to let libraries be visible as a link
+under ${LOCALBASE}.
+Having a separate directory is enough to trick
+.Xr ld 1
+into grabbing the right version.
+Libraries used only for
+.Xr dlopen 3
+do not need to be visible.
+Some programs will prefer to use rpath to find their own libraries.
+.Pp
+The special
+.Cm update-plist
+target does a fairly good job of automatically generating the packing-list
+information.
+.Pp
+If
+.Ev PLIST_REPOSITORY
+points to a directory, all packing-lists from packages generated by
+.Xr pkg_create 1
+during the
+.Cm package
+stage are saved in
+.Pa ${PLIST_REPOSITORY}/${MACHINE_ARCH}
+by a script:
+.Pa ${PORTSDIR}/infrastructure/bin/register-plist .
+This script strips some irrelevant information and normalizes the
+packing-list somehow, and compares it to existing information, looking
+for relevant changes.
+Since a package name must always be changed when the packing-list changes,
+any attempt to replace a packing-list of a given name with a different
+packing-list will be flagged as an error.
+.Pp
+In
+.Ev MULTI_PACKAGES
+mode, there must be separate COMMENT, DESCR, and PLIST
+templates for each SUBPACKAGE (and optional distinct MESSAGE, UNMESSAGE
+files in a similar way).
+This contrasts with the
+.Ev FLAVORS
+situation, where all these files will automatically default to the
+non-flavor version if there is no flavor-specific file around.
+.Sh OBSOLETE TARGETS
+.Bl -tag -width Ds
+.It Cm {build,run,lib}-depends
+The dependency mechanism now meshes
+.Ev BUILD_DEPENDS , LIB_DEPENDS , RUN_DEPENDS, WANTLIB
+and
+.Ev MULTI_PACKAGES .
+Refer to
+.Cm prepare , install-depends , test-depends .
+.El
+.Sh OBSOLETE VARIABLES
+.Bl -tag -width Ds
+.It Ev FETCH_BEFORE_ARGS , FETCH_AFTER_ARGS
+Set
+.Ev FETCH_CMD
+to point to a script that does any required special treatment instead.
+.It Ev FETCH_DEPENDS
+Used to specify dependencies that were needed to fetch files.
+It is much easier to mirror locally weird distribution files.
+.It Ev NO_EXTRACT
+Set EXTRACT_ONLY= instead.
+.It Ev NO_WRKDIR
+All ports should have a working directory, as this is necessary to store
+cookies and keep state.
+.It Ev NO_WRKSUBDIR
+The same functionality is obtained by setting WRKDIST=${WRKDIR}.
+.It Ev OPSYS_VER
+Use
+.Ev OSREV
+instead.
+.It Ev PKGNAME
+Used to refer to the full package name, has been superseded by
+.Ev FULLPKGNAME-foo ,
+for
+.Ev SUBPACKAGE
+-foo.
+.Ev PKGNAME
+now holds the package name, not taking multi-packages or flavors
+into account.
+Most ports are not concerned by this change.
+.It Ev PLIST_SUBST
+From
+.Nx
+and
+.Fx .
+Use SUBST_VARS instead.
+.Ox
+does not allow general substitutions of the form VAR=value, but uses
+only a list of variables instead.
+Most package files gets transformed, instead of only the packing-list.
+.It Ev SCRIPTDIR
+Old location for scripts related to the current port.
+There is no reason for the semantic distinction, use
+.Ev FILESDIR
+for those.
+.It Ev USE_BZIP2
+The framework will automatically detect the presence of
+.Pa .tar.bz2
+files to extract.
+See also
+.Ev BZIP2 , EXTRACT_CASES ,
+and
+.Ev EXTRACT_SUFX .
+.It Ev USE_ZIP
+The framework will automatically detect the presence of
+.Pa .zip
+files to extract.
+See also
+.Ev ZIP , EXTRACT_CASES ,
+and
+.Ev EXTRACT_SUFX .
+.El
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa ../Makefile.inc
+Common Makefile fragment for a set of ports, included automatically.
+.It Pa /cdrom/distfiles
+Default path to a CD-ROM (or other media) full of distribution files.
+.It Pa ${PORTSDIR}/distfiles
+Default setup of ${DISTDIR}.
+.It Pa ${DISTDIR}
+Cache of all distribution files.
+.It Pa distinfo
+Checksum file.
+Holds the output of
+.Xr cksum 1 ,
+using
+.Xr sha256 1
+for the port's ${DISTFILES} and ${PATCHFILES},
+as well as the sizes of these files.
+.It Pa ${DISTDIR}/${CHECKSUMFILES}
+Cache of normal distribution files for a given port.
+.It Pa ${DISTDIR}/${MAKESUMFILES}
+Cache of all distribution files for a given port.
+.It Pa ${PORTSDIR}/infrastructure/mk/*.mk
+Actual location of the
+.Xr make 1
+glue for the ports tree.
+.Xr make 1
+looks for
+.Pa bsd.port.mk
+.Po
+and
+.Pa bsd.port.subdir.mk
+.Pc
+under
+.Pa /usr/share/mk/bsd.port.mk ,
+but that file is just a stub that redirects to the real location.
+.It Pa ${PKGDIR}/DESCR
+Description for the port.
+Variables such as ${HOMEPAGE} and ${MAINTAINER} will be expanded
+(see SUBST_VARS).
+Multi-package ports will use DESCR${SUBPACKAGE}.
+.It Pa ${PKGDIR}/README
+.Ox
+specific documentation for a port, that will be installed as
+.Pa ${LOCALBASE}/share/doc/pkg-readmes/${PKGSTEM}
+at the end of
+.Cm fake .
+Variables from
+.Ev SUBST_VARS
+will be expanded.
+Multi-package ports will use
+.Pa README${SUBPACKAGE} .
+.It Pa ${PKGDIR}/<foo>.login
+login.conf.d file for class <foo>.
+Will be installed as
+.Ar ${PREFIX}/share/examples/login.conf.d/foo
+at the end of
+.Cm fake .
+When a port provides a daemon started by
+.Xr rc.d 8
+requiring non-default
+.Xr login.conf 5
+attributes, a sample file should be provided
+and used as a template by adding
+.Cm @sample /etc/login.conf.d/${ Ns Va class Ns }
+to the packing list.
+.It Pa ${PKGDIR}/<foo>.rc
+Startup script for <foo>.
+Will be installed as
+.Ar ${RCDIR}/<foo>
+at the end of
+.Cm fake .
+Variables from
+.Ev SUBST_VARS
+will be expanded.
+.It Pa ${PORTSDIR}/plist
+Default setup of ${PLIST_REPOSITORY}.
+.It Pa ${PORTSDIR}/packages
+Default setup of ${PACKAGE_REPOSITORY}.
+.It Pa ${PACKAGE_REPOSITORY}/no-arch
+Location of arch-independent packages.
+.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/all
+Location of all built packages.
+.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cache
+Location of packages retrieved through the network.
+.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cksums
+Location of checksums, see
+.Ev CHECKSUM_PACKAGES .
+.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cdrom
+Location of packages suitable for the CD.
+.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/ftp
+Location of packages suitable for FTP.
+.It Pa ${PORTSDIR}/bulk/${MACHINE_ARCH}
+Default setup of ${BULK_COOKIES_DIR}.
+.It Pa ${PORTSDIR}/update/${MACHINE_ARCH}
+Default setup of ${UPDATE_COOKIES_DIR}.
+.It Pa ${PORTSDIR}/mystuff
+Extra directory used to store local ports before committing them.
+All depend targets will normally look there after the normal lookup fails.
+See
+.Ev PORTSDIR_PATH .
+.El
+.Sh DIAGNOSTICS
+Note that some of these messages are actually emitted by some other external
+commands, but grouped here for convenience: easier to look for in
+.Xr dpb 1 Ns 's
+logs.
+.Bl -diag
+.It "/bin/sh: cd .../pkg - No such file or directory"
+Emitted during
+.Cm generate-readmes .
+.Pa ${PKGDIR}
+must point to an existing directory, so that
+.Nm
+can be certain there are no
+.Pa MESSAGEs
+or
+other files pertinent to the package.
+.It "Discovered old directory in ..."
+This message comes from
+.Xr update-plist 1 .
+A directory was found in the packing-list file mentioned in the diagnostic.
+That directory line used to be needed but is no longer,
+because it's now accounted for through dependencies.
+Indicates the old directory has been removed.
+.It "Error: change in plist between ..."
+Error message comes from
+.Xr register-plist 1 .
+.It "Error: duplicate item in packing-list"
+Error message comes from
+.Xr pkg_create 1 ,
+and will result from incorrect packing-lists, such as including several
+fragments with the same file, or having incorrect
+.Ev PKG_ARGS-sub .
+.It "Error: Libraries in packing-lists...and libraries from installed packages don't match"
+The ports tree and the installed packages are out-of-sync.
+Mixing library information from both sources might produce packages that can't
+be installed elsewhere.
+Cleanest fix is to update the out-of-date source (e.g., update the ports tree,
+or build and install new packages).
+Developers may use
+.Ev PKG_CREATE_NO_CHECKS
+instead, assuming they understand the implications.
+See
+.Cm print-package-args Pq Cm wantlib-args
+for details.
+.It "Fatal: can't flavor a SUBDIR"
+A dependency mentions top_subdir,flavor.
+Flavor would then be ignored, as it is only applied to individual ports.
+.It "Fatal: can't subpackage a SUBDIR"
+A dependency mentions top_subdir,-sub.
+Subpackage would then be ignored, as it is only applied to individual ports.
+.It "Fatal: flavor should never start with a digit"
+This would utterly confuse
+.Xr pkg_add 1 .
+See
+.Xr packages-specs 7 .
+.It "Fatal: inclusion of <file> from <file>"
+.Pa bsd.port.mk
+or
+.Pa bsd.port.subdir.mk
+has been included from a
+.Ev MODULE
+or from
+.Pa Makefile.inc ,
+resulting in a double inclusion.
+This would lead to weird results, such as
+.Ev PKG_ARGS
+being defined twice.
+.It "Fatal: SUBPACKAGES should always begin with -: <offending list>"
+That is the only way to differentiate between
+.Ev FLAVOR
+and
+.Ev SUBPACKAGE
+in
+.Xr pkgpath 7
+specifications.
+.It "Fatal: building ports requires correctly installed X11"
+All file sets of the base OS, including xenocara, must be installed
+before building ports.
+.It "Fatal: /usr/local/lib/X11/app-defaults should exist and be a symlink"
+/usr/local/lib/X11/app-defaults is distributed as a symlink in the
+xshare*.tgz file set.
+If xenocara was not fully installed before packages were added, it may
+have been created as a directory instead.
+.It "Fatal: the licensing info for <pkgname> is incomplete..."
+Every port must have explicit defines of all
+.Ev PERMIT_*
+values.
+.It "Fatal: Use 'env FLAVOR=flavor make' instead"
+Arguments specified after
+.Xr make 1
+are hardcoded for all recursive sub-makes, and very difficult to override.
+Thus,
+.Ev FLAVOR
+must be specified in the environment instead.
+.It "Fatal: Use 'env SUBPACKAGE=-sub make' instead"
+Arguments specified after
+.Xr make 1
+are hardcoded for all recursive sub-makes, and very difficult to override.
+Thus,
+.Ev SUBPACKAGE
+must be specified in the environment instead.
+.It "ldconfig: <dir>: No such file or directory"
+Usually produced by
.Xr pkg_add 1
-now calls
+running
+.Xr ldconfig 8 .
+Some tools such as GNU libtool will add directories living under
+.Pa ${WRKINST}
+to the shared library path during the
+.Cm fake
+stage.
+Of course,
.Xr ldconfig 8
-directly, provided dynamic libraries have been annotated with
-.Li "@lib libthingy.so.5.0" .
-Adding new directories to the dynamic loader cache has been
-deprecated.
-It is often better to let libraries be visible as a link
-under ${LOCALBASE}.
-Having a separate directory is enough to trick
-.Xr ld 1
-into grabbing the right version.
-Libraries used only for
-.Xr dlopen 3
-do not need to be visible.
-Some programs will prefer to use rpath to find their own libraries.
-.Pp
-The special
-.Cm update-plist
-target does a fairly good job of automatically generating the packing-list
-information.
+will later complain after the directory no longer exists.
+The bogus tool should be fixed to conform to
+.Ox
+usage.
+.It LIB_DEPENDS <spec> not needed for <FULLPKGPATH>
+There doesn't seem to be any WANTLIB to match the given LIB_DEPENDS.
+Thus, the LIB_DEPENDS won't turn into a @depends line in the created package.
+This is often because of confusion between LIB_DEPENDS and RUN_DEPENDS:
+RUN_DEPENDS is needed for dlopen'd libraries.
.Pp
-If
-.Ev PLIST_REPOSITORY
-points to a directory, all packing-lists from packages generated by
-.Xr pkg_create 1
-during the
-.Cm package
-stage are saved in
-.Pa ${PLIST_REPOSITORY}/${MACHINE_ARCH}
-by a script:
-.Pa ${PORTSDIR}/infrastructure/bin/register-plist .
-This script strips some irrelevant information and normalizes the
-packing-list somehow, and compares it to existing information, looking
-for relevant changes.
-Since a package name must always be changed when the packing-list changes,
-any attempt to replace a packing-list of a given name with a different
-packing-list will be flagged as an error.
+Might be intentional sometimes, if some compile flavors create static binaries,
+for instance.
+Also, will happen for multi-packages, where one sets LIB_DEPENDS to have
+a given build dependency (and corresponding WANTLIB for a given SUBPACKAGE).
.Pp
-In
-.Ev MULTI_PACKAGES
-mode, there must be separate COMMENT, DESCR, and PLIST
-templates for each SUBPACKAGE (and optional distinct MESSAGE, UNMESSAGE
-files in a similar way).
-This contrasts with the
-.Ev FLAVORS
-situation, where all these files will automatically default to the
-non-flavor version if there is no flavor-specific file around.
-.Sh OBSOLETE TARGETS
-.Bl -tag -width Ds
-.It Cm {build,run,lib}-depends
-The dependency mechanism now meshes
-.Ev BUILD_DEPENDS , LIB_DEPENDS , RUN_DEPENDS, WANTLIB
-and
-.Ev MULTI_PACKAGES .
-Refer to
-.Cm prepare , install-depends , test-depends .
-.El
-.Sh OBSOLETE VARIABLES
-.Bl -tag -width Ds
-.It Ev FETCH_BEFORE_ARGS , FETCH_AFTER_ARGS
-Set
-.Ev FETCH_CMD
-to point to a script that does any required special treatment instead.
-.It Ev FETCH_DEPENDS
-Used to specify dependencies that were needed to fetch files.
-It is much easier to mirror locally weird distribution files.
-.It Ev NO_EXTRACT
-Set EXTRACT_ONLY= instead.
-.It Ev NO_WRKDIR
-All ports should have a working directory, as this is necessary to store
-cookies and keep state.
-.It Ev NO_WRKSUBDIR
-The same functionality is obtained by setting WRKDIST=${WRKDIR}.
-.It Ev OPSYS_VER
-Use
-.Ev OSREV
+See
+.Cm print-package-args Pq Cm lib-depends-args
+for details.
+.It "Warning: FULLPKGNAME-sub defined but not FULLPKGPATH-sub"
+.Ev FULLPKGNAME-sub
+has been explicitly defined by the port, instead of relying on the default,
+but no value of
+.Ev FULLPKGPATH-sub
+has been given.
+This is often an error.
+.It "Warning: no debug-info in ..."
+Port uses
+.Ev DEBUG_PACKAGES
+so the
+.Xr build-debug-info 1
+script expects debug information on all binaries and libraries.
+Most probably, the build machinery for that specific port omitted -g
+somewhere, or it runs strips during fake anyway.
+It can also occur if
+.Ev DEBUG_PACKAGES
+includes subpackages with no files holding debug info.
+.It "Warning: symlink(s) point to non existent file."
+Warning message comes from
+.Xr pkg_create 1 .
+The symlink resides in the fake area, under
+.Pa ${WRKINST} .
+This is only a warning because the symlink may point to a run-time dependency,
+which obviously won't exist under
+.Pa ${WRKINST}
+at the time
+.Ql make package
+is run.
+.It "Warning: @option no-default-conflict with no @conflict"
+Warning message comes from
+.Xr pkg_create 1 .
+Most packages that waive "default-conflict" will have explicit conflict markers
instead.
-.It Ev PKGNAME
-Used to refer to the full package name, has been superseded by
-.Ev FULLPKGNAME-foo ,
-for
-.Ev SUBPACKAGE
--foo.
-.Ev PKGNAME
-now holds the package name, not taking multi-packages or flavors
-into account.
-Most ports are not concerned by this change.
-.It Ev PLIST_SUBST
-From
-.Nx
-and
-.Fx .
-Use SUBST_VARS instead.
-.Ox
-does not allow general substitutions of the form VAR=value, but uses
-only a list of variables instead.
-Most package files gets transformed, instead of only the packing-list.
-.It Ev SCRIPTDIR
-Old location for scripts related to the current port.
-There is no reason for the semantic distinction, use
-.Ev FILESDIR
-for those.
-.It Ev USE_BZIP2
-The framework will automatically detect the presence of
-.Pa .tar.bz2
-files to extract.
-See also
-.Ev BZIP2 , EXTRACT_CASES ,
-and
-.Ev EXTRACT_SUFX .
-.It Ev USE_ZIP
-The framework will automatically detect the presence of
-.Pa .zip
-files to extract.
-See also
-.Ev ZIP , EXTRACT_CASES ,
-and
-.Ev EXTRACT_SUFX .
+Otherwise, the package will only conflict with the exact same version, with
+some possible
+.Ev REVISION
+bumps.
+Any other version or
+.Ev FLAVOR
+won't conflict.
+This is generally an error, apart from very few ports like
+.Pa devel/autoconf/* .
+.It "groff produced empty result for <manpage>..."
+Warning message comes from
+.Xr pkg_create 1 .
+Manpages are automatically formatted with
+.Xr groff 1
+if
+.Ev USE_GROFF
+is set.
+The above message denotes an actual problem while formatting the page,
+which should be addressed.
+In the meantime,
+.Xr pkg_create 1
+still produces a package, but leaves the manpage unformatted, in the hope
+that something will be able to make sense of it.
.El
.Sh SEE ALSO
.Xr clean-old-distfiles 1 ,
.Bx .
.\" Voluntarily undocumented:
.\" AUTOCONF_ENV: probably not needed anyway, should be internal.
-.Sh BUGS AND LIMITATIONS
+.Sh BUGS
.Ev LOCALBASE ,
.Ev X11BASE ,
.Ev BASESYSCONFDIR ,
projects / openbsd / commitdiff