Describe more things

1 files changed, 178 insertions, 13 deletions

diff --git a/share/man/man5/bsd.port.mk.5 b/share/man/man5/bsd.port.mk.5
index add45dc3f5f..d90c0b7231a 100644
--- a/share/man/man5/bsd.port.mk.5
+++ b/share/man/man5/bsd.port.mk.5
@@ -1,4 +1,4 @@
-.\" $OpenBSD: bsd.port.mk.5,v 1.18 2000/11/20 08:00:02 deraadt Exp $
+.\" $OpenBSD: bsd.port.mk.5,v 1.19 2000/12/01 16:29:32 espie Exp $
 .\"
 .\" Copyright (c) 2000 Marc Espie
 .\"
@@ -51,7 +51,7 @@ Default target.
 Build the port.
 Essentially invoke
 .Bd -literal
-env -i ${MAKE_ENV} ${MAKE_PROGRAM} ${MAKE_FLAGS} \\\&\ 
+env -i ${MAKE_ENV} ${MAKE_PROGRAM} ${MAKE_FLAGS} \\\&\
 	-f ${MAKE_FILE} ${ALL_TARGET}
 .Ed
 .It Ar checkpatch
@@ -61,7 +61,7 @@ target that simulates invoking
 .Xr patch 1 .
 .It Ar configure
 Configure the port.
-Might be a no operation.
+Might be a void operation.
 Unless overridden, configure creates the ${WRKBUILD}
 directory (see SEPARATE_BUILD), runs ${SCRIPTDIR}/configure if it exists,
 and runs whatever configuration methods are recorded in
@@ -79,18 +79,103 @@ needs to invoke
 .Ar distpatch
 directly for historical reasons.
 .It Ar extract
-Extract the distfiles (but see
+Extract the distfiles under
+.Pa ${WRKDIST}
+(but see
 .Ev EXTRACT_ONLY ) .
+Refer to
+.Ev EXTRACT_CASES
+for a complete description.
 .It Ar fake
 Do a fake port installation, that is, simulate the port installation under
 ${WRKINST}.
 Described in a separate section below.
 .It Ar fetch
-Fetch the distfiles and patchfiles.
+Fetch the distfiles and patchfiles. Each file of the
+.Ev DISTFILES
+and
+.Ev PATCHFILES
+lists is retrieved, if necessary, from the list of sites in
+.Ev MASTER_SITES ,
+with %SUBDIR% substituted with
+.Ev MASTER_SITE_SUBDIR .
+If a filename ends with a
+.Sq :0
+to
+.Sq :9
+extension, it will be retrieved from
+.Ev MASTER_SITES0
+to
+.Ev MASTER_SITES9
+instead.
+The ports framework uses
+.Pa ${DISTDIR}/${DIST_SUBDIR}
+(aliased to
+.Pa ${FULLDISTDIR} )
+to cache the ports distribution files and patch files.
+Note that
+.Ar fetch
+can be invoked by mirroring scripts, in which case it will also
+retrieve
+.Ev SUPDISTFILES ,
+to fill with supplementary distribution files which are not needed for
+every configuration.
+See
+.Ev ALLFILES ,
+.Ev CDROM_SITE ,
+.Ev DISTDIR ,
+.Ev DISTFILES ,
+.Ev DIST_SUBDIR ,
+.Ev FETCH_SYMLINK_DISTFILES ,
+.Ev FULL_DISTDIR ,
+.Ev MASTER_SITES ,
+.Ev MASTER_SITES0 , ... ,
+.Ev MASTER_SITES9 ,
+.Ev PATCH_FILES ,
+.Ev SUPDISTFILES ,
+.Ar refetch .
 .It Ar patch
 Apply distribution and
 .Ox
+specific patches. Because of historical accident,
+.Ar patch
+does not follow the exact same scheme other standard targets do.
+Namely,
+.Ar patch
+invokes
+.Ar pre-patch
+(if defined),
+.Ar do-patch ,
+and
+.Ar post-patch ,
+but the default
+.Ar do-patch
+target recurses through
+.Ar distpatch
+So, if the
+.Ar do-patch
+target is overridden, it should still begin by calling
+make distpatch, before applying
+.Ox
 specific patches.
+See
+.Ar distpatch
+for the distribution patches-specific description.
+If
+.Pa ${PATCHDIR}
+exists, the files described under
+.Ev PATCH_LIST
+will be applied under
+.Ev WRKDIST .
+.It Ar refetch
+Try grabbing a version of the distfiles with the correct checksum off
+the main
+.Ox
+mirror, if
+.Ar fetch
++
+.Ar checksum
+failed.
 .It Ar show
 Invoked with VARNAME=name, show the contents of VARNAME.
 Mostly used from recursive makes, or to know the contents of another
@@ -98,6 +183,10 @@ port's variables without guessing wrong.
 .El
 .Sh VARIABLES
 .Bl -tag -width MASTER_SITES
+.It Ev ALLFILES
+List of all files that need to be retrieved by
+.Ar fetch ,
+with master site selection extension removed. Read-only.
 .It Ev ALL_TARGET
 Target used to build software.
 Default is
@@ -139,6 +228,17 @@ Name of the bzip2 binary.
 Base location where packages suitable for a CDROM (see
 PERMIT_PACKAGE_CDROM) will be placed
 (default: ${PORTSDIR}/cdrom-packages/${ARCH})
+.It Ev CDROM_SITE
+Path to a local database that holds distribution files (usually a CD-Rom
+or other similar media), used to retrieve distribution files before going
+to the network. Defaults to
+.Pa /cdrom/distfiles
+if this path exists.
+Distribution files are still copied or linked (see
+.Ev FETCH_SYMLINK_DISFILES )
+into
+.Ev DISTDIR
+if they are found under CDROM_SITE.
 .It Ev CFLAGS
 Default flags passed to the compiler for building.
 Many ports ignore it.
@@ -216,12 +316,31 @@ time.
 Default is 022.
 Don't override.
 .It Ev DISTDIR
-Directory where all ports distfiles are stashed.
+Directory where all ports distfiles and patchfiles are stashed.
 Defaults to
 .Pa ${PORTSDIR}/distfiles.
-Override if distfiles are stored elsewhere, but use
+Override if distfiles are stored elsewhere. Always use
 .Ev FULLDISTDIR
-to refer to ports's distfiles location instead.
+to refer to ports's distfiles location, as it takes an eventual
+.Ev DIST_SUBDIR
+into account.
+.It Ev DISTFILES
+The main port distribution files (the actual software source, except
+for binary-only ports). Will be retrieved from the MASTER_SITES (see
+.Ar fetch ) ,
+checksummed and extracted (see
+.Ar checksum ,
+.Ar extract ) .
+normally holds a list of files, possibly with :0
+.Ev DISTFILES
+normally holds a list of files, possibly with
+.Sq 0
+to
+.Sq 9
+appended to select a different
+.Ev MASTER_SITES .
+See also
+.Ev SUPDISTFILES .
 .It Ev DISTORIG
 Suffix used by
 .Ar distpatch
@@ -297,6 +416,12 @@ No current port overrides the default.
 See BUILD_DEPENDS for specification.
 Fetch dependencies are checked at the beginning of the extract stage.
 No current port uses FETCH_DEPENDS.
+.It Ev FETCH_SYMLINK_DISTFILES
+Set to
+.Sq Yes
+to link distribution files off
+.Ev CDROM_DISTSITE
+instead of copying them.
 .It Ev FILESDIR
 Location of other files related to the current ports.
 Holds at least the checksum file, sometimes other files
@@ -406,9 +531,13 @@ if platform does not support shared libraries.
 To be tested after including
 .Nm bsd.port.mk ,
 if neither PFRAG.SHARED nor CONFIGURE_SHARED are enough.
+.It Ev ONLY_FOR_ARCHS
+List of architectures on which this port builds.  Can hold both
+processor-specific information (e.g., m68k), and more specific model
+information (e.g., amiga).
 .It Ev OPSYS
 Always
-.Ox OpenBSD
+.Ox
 (read-only).
 .It Ev OPSYS_VER
 Revision number of
@@ -423,6 +552,14 @@ Defaults to
 .It Ev PATCHDIR
 Location for patches applied by patch target (default: patches.${ARCH} or
 patches).
+.It Ev PATCHFILES
+Files to fetch from the master sites like
+.Ev DISTFILES ,
+but serving a different purpose, as they hold distribution patches that
+will be applied at the
+.Ar patch
+stage. See also
+.Ev SUPDISTFILES .
 .It Ev PATCH_ARGS
 Full list of options used while applying port's patches.
 .It Ev PATCH_CHECK_ONLY
@@ -527,8 +664,30 @@ Always holds
 .Ev PREFIX ,
 and
 .Ev SYSCONFDIR .
+The special construct
+.Sq ${FLAVORS}
+can be used in the packing-list to specify the current list of dash
+separated flavors the port is compiled with (useful for cross-dependencies
+in
+.Ev MULTI_PACKAGES ) .
 Add other
 variables as needed.
+.It Ev SUPDISTFILES
+Supplementary files that need to be retrieved under some specific
+circumstances. For instance, a port might need architecture-specific files.
+.Ev SUPDISTFILES
+should hold a list of all distfiles and patchfiles that are not always
+needed, so that a mirror will be able to grab all files, or that
+.Ar makesum
+will work.
+Having an overlap between
+.Ev SUPDISTFILES
+and
+.Ev DISTFILES ,
+.Ev PATCHFILES
+is admissible, and in fact, expected, as it is much simpler to build
+an error-free list of files to retrieve in that way. See
+the xanim port for an example.
 .It Ev SYSCONFDIR
 Location for ports system configuration files.
 Defaults to
@@ -543,12 +702,12 @@ Base location for the templates used in the
 target.
 .It Ev UNZIP
 Name of the unzip binary.
-.It Ev USE_ZIP
-Set to Yes if port needs zip to build properly.
-This is automatic if EXTRACT_ONLY holds files matching *.zip.
 .It Ev USE_BZIP2
 Set to Yes if port needs bzip2 to build properly.
 This is automatic if EXTRACT_ONLY holds files matching *.bzip2.
+.It Ev USE_ZIP
+Set to Yes if port needs zip to build properly.
+This is automatic if EXTRACT_ONLY holds files matching *.zip.
 .It Ev WRKBUILD
 Subdirectory of ${WRKDIR} where the actual build occurs.
 Defaults to ${WRKSRC}, unless SEPARATE_BUILD is involved, in which case
@@ -609,8 +768,12 @@ and is always appended.
 .Bl -tag -width files/md5
 .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 Makefile.${ARCH}
 Arch-dependent Makefile fragment, included automatically.
+.It Pa ${DISTDIR}
+cache of all distribution files.
 .It Pa ${FILESDIR}/md5
 Checksum file.
 Holds the output of
@@ -619,6 +782,8 @@ Holds the output of
 and
 .Xr rmd160 1
 for the ports ${DISTFILES} and ${PATCHFILES}.
+.It Pa ${FULLDISTDIR}/${ALLFILES}
+cache of distribution files for a given port.
 .It Pa ${PKGDIR}/DESCR
 Description for the port.
 Variables such as ${HOMEPAGE} will be expanded
@@ -744,7 +909,7 @@ Use CLEANDEPENDS instead.
 ships with compressed man pages, and uses this variable to control
 that behavior.
 .It Ev PATCH_SITES
-.Ev PATCH_FILES
+.Ev PATCHFILES
 used to be retrieved from a separate site list.
 For greater flexibility, all files are now retrieved from
 .Ev MASTER_SITES ,