share/man/man7/library-specs.7

   1 .\" $OpenBSD: library-specs.7,v 1.10 2010/11/15 07:41:21 jmc Exp $
   2 .\"
   3 .\" Copyright (c) 2001-2010 Marc Espie
   4 .\"
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd $Mdocdate: November 15 2010 $
  28 .Dt LIBRARY-SPECS 7
  29 .Os
  30 .Sh NAME
  31 .Nm library-specs
  32 .Nd shared library name specifications
  33 .Sh DESCRIPTION
  34 Each
  35 .Ev WANTLIB
  36 item in the ports tree conforms to
  37 .Bd -literal -offset indent
  38 [path/]libname[=major[.minor]]
  39 .Ed
  40 .Pp
  41 or
  42 .Bd -literal -offset indent
  43 [path/]libname[>=major[.minor]]
  44 .Ed
  45 .Pp
  46 All libraries that a package needs must be mentioned in that list.
  47 Except for system and X11 libraries, they all must be reachable through
  48 .Ev LIB_DEPENDS
  49 and
  50 .Ev RUN_DEPENDS ,
  51 directly, or indirectly through recursive dependencies.
  52 .Pp
  53 Conversely, the ports tree
  54 uses
  55 .Ev WANTLIB
  56 to check whether a given
  57 .Ev LIB_DEPENDS
  58 will be required at runtime for shared libraries, and thus turn it into a
  59 .Cm @depend
  60 line
  61 .Po
  62 see
  63 .Xr pkg_create 1
  64 .Pc .
  65 .Pp
  66 The package system will embed correct dependency checks in the built
  67 package in the form of
  68 .Cm @wantlib
  69 lines, according to the normal shared library semantics: any library with
  70 the same major number, and a greater or equal minor number will do.
  71 .Pp
  72 Note that static libraries can only satisfy a library specification if
  73 no shared library has been found.
  74 Thus, if WANTLIB = foo>=5, and both libfoo.so.4.0 and libfoo.a are present,
  75 the check will fail.
  76 .Pp
  77 Therefore, porters must strive to respect correct shared library semantics
  78 in their own ports: by bumping the minor number each time the interface is
  79 augmented, and by bumping the major number each time the interface changes.
  80 Note that adding functions to a library is an interface augmentation.
  81 Removing functions is an interface change.
  82 .Pp
  83 The major.minor components of the library specification are used only as a
  84 build-time check, the run-time checks are computed by
  85 .Xr resolve-lib 1 .
  86 For
  87 .Sq libname>=major[.minor] ,
  88 any library which is more recent than the given major.minor version will
  89 do.
  90 If a specific major number is needed, use the form
  91 .Sq libname=major[.minor] .
  92 If the minor component is left empty, any minor will do.
  93 If both components are left empty, any version will do.
  94 .Pp
  95 If a given architecture does not support shared libraries, all
  96 .Ev LIB_DEPENDS
  97 will be turned into simple
  98 .Ev BUILD_DEPENDS
  99 checks, and so,
 100 failure to mention
 101 .Ev RUN_DEPENDS
 102 if the port needs anything beyond libraries from the dependent port will
 103 lead to strange errors on such architectures.
 104 .Pp
 105 Most specifications won't mention a
 106 .Pa path :
 107 .Xr resolve-lib 1
 108 will look in the default
 109 .Xr ldconfig 8
 110 path automatically, namely
 111 .Pa /usr/local/lib ,
 112 .Pa /usr/X11R6/lib ,
 113 .Pa /usr/lib .
 114 It is generally a bad idea to put libraries elsewhere as they won't be
 115 reached directly.
 116 .Pp
 117 However, distinct ports may install different major versions of the same
 118 library in
 119 .Pa /usr/local/lib ,
 120 and disambiguate the build by creating a link in a separate directory,
 121 and specifying the right options to the linker.
 122 .Pp
 123 These libraries will require a
 124 .Pa path
 125 component in the corresponding
 126 .Ev WANTLIB
 127 to make sure the right library is resolved.
 128 This path is rooted under
 129 .Pa /usr/local .
 130 For instance, to refer to
 131 .Pa /usr/local/lib/qt3/libqt-mt.so.33.0 ,
 132 one would use
 133 .Sq lib/qt3/qt-mt>=33 .
 134 .Sh SEE ALSO
 135 .Xr check-lib-depends 1 ,
 136 .Xr ld 1 ,
 137 .Xr ld.so 1 ,
 138 .Xr pkg_add 1 ,
 139 .Xr resolve_lib 1 ,
 140 .Xr bsd.port.mk 5 ,
 141 .Xr packages 7 ,
 142 .Xr packages-specs 7 ,
 143 .Xr ports 7 ,
 144 .Xr ldconfig 8
 145 .Sh HISTORY
 146 Full support for library specifications first appeared in
 147 .Ox 3.1 .
 148 The format of specifications changed slightly to include
 149 .Sq >=
 150 before
 151 .Ox 4.0 .
 152 The interactions between
 153 .Ev LIB_DEPENDS
 154 and
 155 .Ev WANTLIB
 156 were modified and clarified for
 157 .Ox 4.8 .
 158 The format of specifications changed again before
 159 .Ox 4.9
 160 to remove extra noise.