Document port modules, nroff input by jmc.

2 files changed, 328 insertions, 3 deletions

diff --git a/share/man/man5/Makefile b/share/man/man5/Makefile
index 72418a84db4..d0ecc2e47d5 100644
--- a/share/man/man5/Makefile
+++ b/share/man/man5/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.40 2008/05/08 16:51:41 millert Exp $
+#	$OpenBSD: Makefile,v 1.41 2008/05/11 18:50:58 espie Exp $
 #	$NetBSD: Makefile,v 1.14 1995/05/11 23:13:15 cgd Exp $
 
 # missing: dump.5 plot.5
@@ -8,8 +8,8 @@ MAN=	a.out.5 acct.5 bsd.port.mk.5 bsd.regress.mk.5 changelist.5 core.5 \
 	forward.5 fs.5 fstab.5 genassym.cf.5 group.5 hostname.if.5 \
 	hosts.equiv.5 hosts.5 intro.5 link.5 login.conf.5 mixerctl.conf.5 \
 	mk.conf.5 moduli.5 motd.5 myname.5 netgroup.5 networks.5 passwd.5 \
-	pf.conf.5 pf.os.5 phones.5 printcap.5 protocols.5 remote.5 \
-	resolv.conf.5 rpc.5 services.5 shells.5 stab.5 spamd.conf.5 \
+	pf.conf.5 pf.os.5 phones.5 port-modules.5 printcap.5 protocols.5 \
+	remote.5 resolv.conf.5 rpc.5 services.5 shells.5 stab.5 spamd.conf.5 \
 	sysctl.conf.5 utmp.5 wsconsctl.conf.5
 	
 MLINKS= dir.5 dirent.5 fs.5 inode.5 utmp.5 wtmp.5 utmp.5 lastlog.5
diff --git a/share/man/man5/port-modules.5 b/share/man/man5/port-modules.5
new file mode 100644
index 00000000000..8562a086a3f
--- /dev/null
+++ b/share/man/man5/port-modules.5
@@ -0,0 +1,325 @@
+.\"	$OpenBSD: port-modules.5,v 1.1 2008/05/11 18:50:58 espie Exp $
+.\"
+.\" Copyright (c) 2008 Marc Espie
+.\"
+.\" 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 DEVELOPERS ``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 DEVELOPERS 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 $Mdocdate: May 11 2008 $
+.Dt PORT-MODULES 5
+.Os
+.Sh NAME
+.Nm port-modules
+.Nd format and conventions used in port modules
+.Sh DESCRIPTION
+The
+.Ox
+Ports framework is based on a gigantic makefile named
+.Xr bsd.port.mk 5 .
+.Pp
+In order to curb unwieldy growth, parts of the framework
+that are not always needed have been set apart in optional
+files called
+.Nm port modules ,
+which are retrieved as needed through the
+.Ev MODULES
+variable of
+.Xr bsd.port.mk 5 .
+.Pp
+Some of these modules correspond to basic mechanisms which are not
+always needed, such as GNU autoconf, or perl5.
+.Pp
+Other modules correspond to shortcuts for using some other ports as
+dependencies without needing to hardcode too much, such as libiconv or
+the qt ports.
+.Sh THE MODULES LOOK-UP MECHANISM
+The variable
+.Ev MODULES
+should contain a list of module names.
+Some core modules are a single word, all other modules should be
+${PKGPATH}.
+If the module is
+.Pa some/dir/portname ,
+the ports framework will look for a file named
+.Pa ${PORTSDIR}/some/dir/portname/portname.mk
+and include it.
+.Pp
+Most modules should conform to this syntax.
+The historic practice of having a redirection file directly under
+.Pa ${PORTSDIR}/infrastructure/mk
+is deprecated for new modules.
+.Pp
+Modules may refer to each other.
+The modules mechanism has specific recursion handling such that
+adding
+.Li MODULES += foo/bar
+to a module will work as expected.
+.Sh NAMING CONVENTIONS
+Since there is no actual scope in makefiles, everything defined within
+a module will be global to the ports framework, and thus may interfere
+with other ports.
+.Pp
+As far as possible, all variables and targets belonging to a module named
+.Pa some/dir/foo
+should be named
+.Ev MODFOO_*
+and
+.Ar modfoo_* .
+.Pp
+Following the same conventions as
+.Xr bsd.port.mk 5 ,
+internal variables and targets not intended for user consumption should be
+named
+.Ev _MODFOO_*
+and
+.Ar _modfoo_* .
+.Pp
+For instance, if a module wants some value to be available for the rest
+of the world, it should define
+.Ev MODFOO_VARNAME ,
+with a name matching the basic infrastructure as far as possible.
+That is, a port that defines specific dependencies will usually
+define
+.Ev MODFOO_WANTLIB ,
+.Ev MODFOO_LIB_DEPENDS ,
+and
+.Ev MODFOO_RUN_DEPENDS ,
+as appropriate.
+.Pp
+As an exception to the naming mechanism, some ports have several distinct
+versions in the ports tree, say
+.Pa x11/qt2 ,
+.Pa x11/qt3 ,
+and
+.Pa x11/qt4 .
+Instead of using the namespace
+.Ev MODQT2* ,
+variables will usually drop the version suffix and be simply called
+.Ev MODQT_*
+so that a port using the module can be switched from version to version
+without needing to change everything.
+.Pp
+It is highly desirable to define names in both namespaces for such ports,
+for example to define both
+.Ev MODQT3_LIB_DEPENDS
+and
+.Ev MODQT_LIB_DEPENDS .
+Normal client ports will use
+.Ev MODQT_LIB_DEPENDS ,
+but a port may exceptionally import both modules with
+.Li MODULES += x11/qt3 x11/qt4
+and differentiate between qt3 and qt4 needs with
+.Ev MODQT3_LIB_DEPENDS
+and
+.Ev MODQT4_LIB_DEPENDS .
+See
+.Pa print/poppler
+for an example.
+.Sh OVERRIDING TARGET BEHAVIOR
+The main framework contains several hooks that allow ports to override
+normal behavior.
+This evolved as an ad-hoc framework, where only hooks that turned out
+to be needed were added.
+If several modules define the same hook, hook behaviors will be
+invoked in sequence.
+.Bl -tag -width do-configure
+.It Ar patch
+There is a
+.Ar post-patch
+hook that can be activated by defining
+.Ev MODFOO_post-patch .
+It will be run right after
+.Ar post-patch
+and before
+.Ev REORDER_DEPENDENCIES
+touches things.
+.It Ar configure
+The normal
+.Ar do-configure
+behavior is to invoke all
+.Ev MODFOO_configure
+contents that are defined in
+.Ev CONFIGURE_STYLE .
+By default,
+.Ar configure
+will do nothing.
+Some
+.Ev CONFIGURE_STYLE
+values, namely perl, gnu, imake, automake, autoconf, and autoupdate
+will automatically import the correct module.
+User-defined modules must both add to
+.Ev CONFIGURE_STYLE
+and import the correct module to override behavior.
+Contrary to other hooks, module behavior is not invoked in
+addition to
+.Ar do-configure ,
+but as the normal configure process.
+If
+.Ar do-configure
+is overriden, normal hook processing will not happen.
+.It Ar fake
+There is a
+.Ar pre-fake
+hook that can be activated by defining
+.Ev MODFOO_pre-fake .
+This will be invoked right after
+.Xr mtree 8 ,
+and before the normal
+.Ar pre-fake
+behavior.
+.It Ar install
+There is a
+.Ar pre-install
+hook that can be activated by defining
+.Ev MODFOO_pre-install .
+It will be run right before installing the package with
+.Xr pkg_add 1 .
+.El
+.Sh OVERRIDING VARIABLE BEHAVIOR
+Some variables can be overriden by modules.
+Be very cautious, as this can make the module difficult to use,
+or interact badly with other modules.
+As a rule, always provide the override as:
+.Pp
+.Dl VARIABLE ?= value
+.Pp
+and provide a module-specific variable with the same value:
+.Pp
+.Dl MODFOO_VARIABLE = value .
+.Pp
+The following variables can be overriden in a relatively safe fashion:
+.Ev CONFIGURE_SCRIPT ,
+.Ev DESTDIRNAME ,
+.Ev DIST_SUBDIR ,
+.Ev EXTRACT_SUFX ,
+.Ev FAKE_FLAGS ,
+.Ev FETCH_MANUALLY ,
+.Ev IS_INTERACTIVE ,
+.Ev LIBTOOL_FLAGS ,
+.Ev MAKE_FLAGS ,
+.Ev MASTER_SITES ,
+.Ev PKG_ARCH ,
+.Ev PREFIX ,
+.Ev REGRESS_IS_INTERACTIVE ,
+.Ev REORDER_DEPENDENCIES ,
+.Ev SEPARATE_BUILD ,
+.Ev SHARED_ONLY ,
+.Ev USE_GMAKE ,
+.Ev USE_LIBTOOL ,
+.Ev USE_MOTIF .
+.Pp
+The following variables can be added to in a relatively safe fashion:
+.Ev BUILD_DEPENDS ,
+.Ev CATEGORIES ,
+.Ev FLAVOR ,
+.Ev FLAVORS ,
+.Ev LIB_DEPENDS ,
+.Ev PSEUDO_FLAVORS ,
+.Ev RUN_DEPENDS ,
+.Ev WANTLIB .
+.Sh SPECIFIC MODULE INTERACTIONS
+Some modules correspond to extra ports that will be used mostly as
+.Ev BUILD_DEPENDS
+or
+.Ev RUN_DEPENDS .
+Such modules can safely append values directly to the
+.Ev BUILD_DEPENDS ,
+.Ev RUN_DEPENDS ,
+.Ev LIB_DEPENDS ,
+and
+.Ev WANTLIB
+variables, as long as they also define module-specific variables for
+all runtime dependencies.
+.Pp
+Simple client ports will use the module directly, and thus inherit extra
+build and runtime dependencies.
+.Pp
+More sophisticated ports can use
+.Ev MULTI_PACKAGES
+to select specific behavior: build-time dependencies will always be
+needed.
+Runtime dependencies will be selected on a subpackage basis,
+since runtime dependencies such as
+.Ev LIB_DEPENDS-sub
+do not inherit the default
+.Ev LIB_DEPENDS
+value.
+The client port's author must only bear in mind that external modules
+may add values to the default
+.Ev WANTLIB ,
+.Ev LIB_DEPENDS ,
+and
+.Ev RUN_DEPENDS ,
+and thus that it is not safe to inherit from it blindly.
+.Pp
+Modules are imported during
+.Pp
+.Dl .include <bsd.port.mk>
+.Pp
+Thus they can be affected by user choices such as setting a variable
+to Yes or No.
+Modules may make decisions based on documented
+.Ev MODFOO_BEHAVIOR
+values.
+.Pp
+When modules are processed, only a few
+.Xr bsd.port.mk 5
+variables are already defined.
+Modules may depend upon the following variables already having a sane
+value:
+.Ev ARCH ,
+.Ev LP64_ARCHS ,
+.Ev NO_BUILD ,
+.Ev NO_DEPENDS ,
+.Ev NO_REGRESS ,
+.Ev NO_SHARED_ARCHS ,
+.Ev NO_SHARED_LIBS ,
+.Ev PORTSDIR ,
+.Ev USE_X11 .
+Note that this is only relevant for tests.
+It is perfectly okay to define variables or targets that depend on the
+basic ports framework without having to care whether that variable is
+already defined, since
+.Xr make 1
+performs lazy evaluation.
+.Sh CORE MODULES DOCUMENTATION
+The following modules are available.
+.Bl -tag -width do-configure
+.It cpan
+.It gcc3
+.It gcc4
+.It ghc
+.It gnu
+.It imake
+.It java
+.It ocaml
+.It pear
+.It perl
+.It python
+.It ruby
+.El
+.Pp
+They will be documented soon.
+.Sh SEE ALSO
+.Xr make 1 ,
+.Xr bsd.port.mk 5 ,
+.Xr ports 7