document new semantics

2 files changed, 73 insertions, 34 deletions

diff --git a/share/man/man7/library-specs.7 b/share/man/man7/library-specs.7
index ebe08559f14..e174600d9f5 100644
--- a/share/man/man7/library-specs.7
+++ b/share/man/man7/library-specs.7
@@ -1,4 +1,4 @@
-.\" $OpenBSD: library-specs.7,v 1.7 2007/05/31 19:19:58 jmc Exp $
+.\" $OpenBSD: library-specs.7,v 1.8 2010/07/04 17:30:31 espie Exp $
 .\"
 .\" Copyright (c) 2001 Marc Espie
 .\"
@@ -24,7 +24,7 @@
 .\" (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 31 2007 $
+.Dd $Mdocdate: July 4 2010 $
 .Dt LIBRARY-SPECS 7
 .Os
 .Sh NAME
@@ -32,26 +32,48 @@
 .Nd shared library name specifications
 .Sh DESCRIPTION
 Each
-.Ev LIB_DEPENDS
+.Ev WANTLIB
 item in the port tree conforms to
-.Sq lib_specs:[pkgspec]:directory[,-subpackage][,flavor ...][:target] ,
-where
-.Sq lib_specs
-is a comma-separated list of
-.Sq lib_spec
-of the form:
-.Sq libname[.=major[.minor]]
+.Bd -literal -offset indent
+libname[.=major[.minor]]
+.Ed
+.Pp
 or
-.Sq libname[.>=major[.minor]] .
+.Bd -literal -offset indent
+libname[.>=major[.minor]]
+.Ed
+.Pp
+All libraries that a package needs must be mentioned in that list.
+Except for system and X11 libraries, they all must be reachable through
+.Ev LIB_DEPENDS
+and
+.Ev RUN_DEPENDS ,
+directly, or indirectly through recursive dependencies.
 .Pp
-All libraries that a port needs must be mentioned in that list, either
-directly or indirectly through recursive dependencies (except, of course,
-for system libraries).
+Conversely, the ports tree
+uses
+.Ev WANTLIB
+to check whether a given
+.Ev LIB_DEPENDS
+will be required at runtime for shared libraries, and thus turn it into a
+.Cm @depend
+line
+.Po
+see
+.Xr pkg_create 1
+.Pc .
 .Pp
 The package system will embed correct dependency checks in the built
-package, according to the normal shared library semantics: any library with
+package in the form of
+.Cm @wantlib
+lines, according to the normal shared library semantics: any library with
 the same major number, and a greater or equal minor number will do.
 .Pp
+Note that static libraries can only satisfy a library specification if
+no shared library has been found.
+Thus, if WANTLIB=foo.>=5, and both libfoo.so.4.0 and libfoo.a are present,
+the check will fail.
+.Pp
 Therefore, porters must strive to respect correct shared library semantics
 in their own ports: by bumping the minor number each time the interface is
 augmented, and by bumping the major number each time the interface changes.
@@ -59,7 +81,7 @@ Note that adding functions to a library is an interface augmentation.
 Removing functions is an interface change.
 .Pp
 The major.minor components of the library specification are used only as a
-build-time check.
+build-time check, the run-time checks are computed by ports tree internals.
 For
 .Sq libname.>=major[.minor] ,
 any library which is more recent than the given major.minor version will
@@ -69,25 +91,15 @@ If a specific major number is needed, use the form
 If the minor component is left empty, any minor will do.
 If both components are left empty, any version will do.
 .Pp
-The
-.Sq pkgspec
-part is always checked, both at build-time, and at
-.Xr pkg_add 1
-time.
-If
-.Sq pkgspec
-is left empty, any package will do: in effect, the pkgspec used is
-.Sq stem-* .
-.Pp
 If a given architecture does not support shared libraries, all
 .Ev LIB_DEPENDS
 will be turned into simple
 .Ev BUILD_DEPENDS
-checks.
-Failure to mention
+checks, and so,
+failure to mention
 .Ev RUN_DEPENDS
 if the port needs anything beyond libraries from the dependent port will
-lead to strange errors.
+lead to strange errors on such architectures.
 .Sh SEE ALSO
 .Xr pkg_add 1 ,
 .Xr bsd.port.mk 5 ,
@@ -101,3 +113,9 @@ The format of specifications changed slightly to include
 .Sq >=
 before
 .Ox 4.0 .
+The interactions between
+.Ev LIB_DEPENDS
+and
+.Ev WANTLIB
+were modified and clarified for
+.Ox 4.8 .
diff --git a/share/man/man7/packages-specs.7 b/share/man/man7/packages-specs.7
index 034004c06af..d38a054939d 100644
--- a/share/man/man7/packages-specs.7
+++ b/share/man/man7/packages-specs.7
@@ -1,4 +1,4 @@
-.\" $OpenBSD: packages-specs.7,v 1.10 2008/07/15 11:10:51 espie Exp $
+.\" $OpenBSD: packages-specs.7,v 1.11 2010/07/04 17:30:31 espie Exp $
 .\"
 .\" Copyright (c) 2001 Marc Espie
 .\"
@@ -24,7 +24,7 @@
 .\" (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: July 15 2008 $
+.Dd $Mdocdate: July 4 2010 $
 .Dt PACKAGES-SPECS 7
 .Os
 .Sh NAME
@@ -117,7 +117,22 @@ and
 .Qq qt2-3.0 .
 .Sh DEPENDENCIES
 Packages may depend on other packages, as specified by their port's
-Makefile.
+Makefile, in a
+.Ev BUILD_DEPENDS ,
+.Ev LIB_DEPENDS ,
+.Ev REGRESS_DEPENDS
+or
+.Ev RUN_DEPENDS .
+All those conform to
+.Bd -literal -offset indent
+[legacy]:[pkgspec]:directory,[-multi],[flavor...]
+.Ed
+.Pp
+The
+.Ar [legacy]
+part of the dependency corresponds to older semantics that have been
+deprecated.
+.Pp
 The
 .Ar directory,[-multi],[flavor...]
 part of the dependency is always used to obtain the default dependency for
@@ -126,6 +141,12 @@ is found).
 The corresponding package name is also used as a package specification,
 after removing any version and flavor requirements.
 .Pp
+If the
+.Sq pkgspec
+part is left empty, any package will the right stem will do: in effect,
+the pkgspec used is
+.Sq stem-* .
+.Pp
 An explicit specification such as
 .Qq ghostscript-*
 may be used to ask for any version of package ghostscript,
@@ -143,7 +164,7 @@ Note that most default package names don't contain flavor specification,
 which means that any flavor will do.
 For instance, in
 .Bd -literal -offset indent
-LIB_DEPENDS=aa.1.2::graphics/aalib
+LIB_DEPENDS=::graphics/aalib
 .Ed
 .Pp
 both
@@ -161,7 +182,7 @@ append
 .Sq -!f .
 In the preceding case, one may use
 .Bd -literal -offset indent
-LIB_DEPENDS=aa.1.2:aalib-*-!no_x11:graphics/aalib
+LIB_DEPENDS=:aalib-*-!no_x11:graphics/aalib
 .Ed
 .Pp
 to ensure the no_x11 flavor is not picked.