diff options
| author | wiz <wiz@pkgsrc.org> | 2006-09-10 19:27:34 +0000 |
|---|---|---|
| committer | wiz <wiz@pkgsrc.org> | 2006-09-10 19:27:34 +0000 |
| commit | b6e19a3259f178dc8390fa5f6840fe654f8af724 (patch) | |
| tree | d7b084496260fc52bb95d52247064eda63679f69 /doc/guide | |
| parent | d9e85ef31d5aa4ae8becb5217c0a60875b7cfd7b (diff) | |
| download | pkgsrc-b6e19a3259f178dc8390fa5f6840fe654f8af724.tar.gz | |
Document PKGNAME_NOREV. Use more markup. Improve DIST_SUBDIR
description. Add section about programming languages. Describe
UNLIMIT_RESOURCES. Avoid extra whitespace in <para>.
Add section about emulation packages.
Add section about BROKEN and BROKEN_IN.
Diffstat (limited to 'doc/guide')
| -rw-r--r-- | doc/guide/files/fixes.xml | 2961 |
1 files changed, 1535 insertions, 1426 deletions
diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml index 63b7329a229..a960918af0a 100644 --- a/doc/guide/files/fixes.xml +++ b/doc/guide/files/fixes.xml @@ -1,952 +1,1036 @@ -<!-- $NetBSD: fixes.xml,v 1.70 2006/09/03 10:54:55 jmmv Exp $ --> +<!-- $NetBSD: fixes.xml,v 1.71 2006/09/10 19:27:34 wiz Exp $ --> <chapter id="fixes"> <?dbhtml filename="fixes.html"?> - <title>Making your package work</title> +<title>Making your package work</title> - <sect1 id="general-operation"> - <title>General operation</title> +<sect1 id="general-operation"> + <title>General operation</title> -<sect2 id="portability-of-packages"> -<title>Portability of packages</title> + <sect2 id="portability-of-packages"> + <title>Portability of packages</title> - <para>One appealing feature of pkgsrc is that it runs on many - different platforms. As a result, it is important to ensure, - where possible, that packages in pkgsrc are portable. This - chapter mentions some particular details you should pay - attention to while working on pkgsrc.</para> + <para>One appealing feature of pkgsrc is that it runs on many + different platforms. As a result, it is important to ensure, + where possible, that packages in pkgsrc are portable. This + chapter mentions some particular details you should pay + attention to while working on pkgsrc.</para> -</sect2> - - <sect2 id="pulling-vars-from-etc-mk.conf"> - <title>How to pull in user-settable variables from <filename>mk.conf</filename></title> - - <para>The pkgsrc user can configure pkgsrc by overriding several - variables in the file pointed to by <varname>MAKECONF</varname>, - which is <filename>/etc/mk.conf</filename> by default. When you - want to use those variables in the preprocessor directives of - &man.make.1; (for example <literal>.if</literal> or - <literal>.for</literal>), you need to include the file - <filename>../../mk/bsd.prefs.mk</filename> before, which in turn - loads the user preferences.</para> - - <para>But note that some variables may not be completely defined - after <filename>../../mk/bsd.prefs.mk</filename> has been - included, as they may contain references to variables that are - not yet defined. In shell commands this is no problem, since - variables are actually macros, which are only expanded when they - are used. But in the preprocessor directives mentioned above and - in dependency lines (of the form <literal>target: - dependencies</literal>) the variables are expanded at load - time.</para> - - <note><para>Currently there is no exhaustive list of all - variables that tells you whether they can be used at load time - or only at run time, but it is in preparation.</para></note> - - </sect2> - - <sect2 id="user-interaction"> - <title>User interaction</title> - - <para>Occasionally, packages require interaction from the user, and this can be - in a number of ways:</para> - - <itemizedlist> - - <listitem> - <para>When fetching the distfiles, some packages require user - interaction such as entering username/password or accepting a - license on a web page.</para> - </listitem> - - <listitem> - <para>When extracting the distfiles, some packages may ask for passwords.</para> - </listitem> - - <listitem> - <para>help to configure the package before it is built</para> - </listitem> - - <listitem> - <para>help during the build process</para> - </listitem> - - <listitem> - <para>help during the installation of a package</para> - </listitem> - </itemizedlist> - - <para>The <varname>INTERACTIVE_STAGE</varname> definition is provided to notify - the pkgsrc mechanism of an interactive stage which will be needed, and - this should be set in the package's <filename>Makefile</filename>, e.g.:</para> - -<programlisting> - INTERACTIVE_STAGE= build -</programlisting> - - <para>Multiple interactive stages can be specified:</para> - -<programlisting> - INTERACTIVE_STAGE= configure install -</programlisting> + </sect2> - </sect2> + <sect2 id="pulling-vars-from-etc-mk.conf"> + <title>How to pull in user-settable variables from <filename>mk.conf</filename></title> - <sect2 id="handling-licenses"> - <title>Handling licenses</title> - - <para>A package may be covered by a license which the user has - or has not agreed to accept. For these cases, pkgsrc contains - a mechanism to note that a package is covered by a particular - license, and the package cannot be built unless the user has - accepted the license. (Installation of binary packages are - not currently subject to this mechanism.) Packages with - licenses that are either Open Source according to the Open - Source Initiative or Free according to the Free Software - Foundation will not be marked with a license tag. Packages - with licenses that have not been determined to meet either - definition will be marked with a license tag referring to the - license. This will prevent building unless pkgsrc is informed - that the license is acceptable, and enables displaying the - license.</para> - - <para>The license tag mechanism is intended to address - copyright-related issues surrounding building, installing and - using a package, and not to address redistribution issues (see - <varname>RESTRICTED</varname> and - <varname>NO_SRC_ON_FTP</varname>, etc.). However, the above - definition of licenses for which tags are not needed implies - that packages with redistribution restrictions should have - tags.</para> - - <para> - Denoting that a package is covered by a particular license is - done by placing the license in - <filename>pkgsrc/licenses</filename> and setting the - <varname>LICENSE</varname> variable to a string identifying - the license, e.g. in - <filename role="pkg">graphics/xv</filename>: </para> + <para>The pkgsrc user can configure pkgsrc by overriding several + variables in the file pointed to by <varname>MAKECONF</varname>, + which is <filename>/etc/mk.conf</filename> by default. When you + want to use those variables in the preprocessor directives of + &man.make.1; (for example <literal>.if</literal> or + <literal>.for</literal>), you need to include the file + <filename>../../mk/bsd.prefs.mk</filename> before, which in turn + loads the user preferences.</para> -<programlisting> - LICENSE= xv-license -</programlisting> + <para>But note that some variables may not be completely defined + after <filename>../../mk/bsd.prefs.mk</filename> has been + included, as they may contain references to variables that are + not yet defined. In shell commands this is no problem, since + variables are actually macros, which are only expanded when they + are used. But in the preprocessor directives mentioned above and + in dependency lines (of the form <literal>target: + dependencies</literal>) the variables are expanded at load + time.</para> - <para> - When trying to build, the user will get a notice that the - package is covered by a license which has not been - accepted:</para> + <note><para>Currently there is no exhaustive list of all + variables that tells you whether they can be used at load time + or only at run time, but it is in preparation.</para></note> -<programlisting> - &cprompt; <userinput>make</userinput> - ===> xv-3.10anb9 has an unacceptable license: xv-license. - ===> To view the license, enter "/usr/bin/make show-license". - ===> To indicate acceptance, add this line to your /etc/mk.conf: - ===> ACCEPTABLE_LICENSES+=xv-license - *** Error code 1 -</programlisting> + </sect2> - <para>The license can be viewed with <command>make - show-license</command>, and if it is considered appropriate, - the line printed above can be added to - <filename>/etc/mk.conf</filename> to indicate acceptance of - the particular license:</para> + <sect2 id="user-interaction"> + <title>User interaction</title> -<programlisting> - ACCEPTABLE_LICENSES+=xv-license -</programlisting> - - <para>When adding a package with a new license, the license - text should be added to <filename>pkgsrc/licenses</filename> - for displaying. A list of known licenses can be seen in this - directory as well as by looking at the list of (commented - out) <varname>ACCEPTABLE_LICENSES</varname> variable - settings in - <filename>pkgsrc/mk/defaults/mk.conf</filename>.</para> - - <para>The use of <varname>LICENSE=shareware</varname>, - <varname>LICENSE=no-commercial-use</varname>, and similar - language is deprecated because it does not crisply refer to - a particular license text. Another problem with such usage - is that it does not enable a user to denote acceptance of - the license for a single package without accepting the same - license text for another package. In particular, this can - be inappropriate when e.g. one accepts a particular license to - indicate to pkgsrc that a fee has been paid.</para> - </sect2> + <para>Occasionally, packages require interaction from the user, and this can be + in a number of ways:</para> - <sect2 id="restricted-packages"> - <title>Restricted packages</title> - - <para>Some licenses restrict how software may be re-distributed. - In order to satisfy these restrictions, the package system - defines five make variables that can be set to note these - restrictions:</para> - - <itemizedlist> - <listitem> - <para><varname>RESTRICTED</varname></para> - - <para>This variable should be set whenever a restriction - exists (regardless of its kind). Set this variable to a - string containing the reason for the restriction.</para> - </listitem> - - <listitem> - <para><varname>NO_BIN_ON_CDROM</varname></para> - - <para>Binaries may not be placed on CD-ROM. Set this - variable to <varname>${RESTRICTED}</varname> whenever a - binary package may not be included on a CD-ROM.</para> - </listitem> - - <listitem> - <para><varname>NO_BIN_ON_FTP</varname></para> - - <para>Binaries may not be placed on an FTP server. Set - this variable to <varname>${RESTRICTED}</varname> - whenever a binary package may not not be made available - on the Internet.</para> - </listitem> - - <listitem> - <para><varname>NO_SRC_ON_CDROM</varname></para> + <itemizedlist> - <para>Distfiles may not be placed on CD-ROM. Set this - variable to <varname>${RESTRICTED}</varname> if - re-distribution of the source code or other distfile(s) is - not allowed on CD-ROMs.</para> - </listitem> + <listitem> + <para>When fetching the distfiles, some packages require user + interaction such as entering username/password or accepting a + license on a web page.</para> + </listitem> - <listitem> - <para><varname>NO_SRC_ON_FTP</varname></para> + <listitem> + <para>When extracting the distfiles, some packages may ask for passwords.</para> + </listitem> - <para>Distfiles may not be placed on FTP. Set this variable - to <varname>${RESTRICTED}</varname> if re-distribution of - the source code or other distfile(s) via the Internet is not - allowed.</para> - </listitem> - </itemizedlist> + <listitem> + <para>help to configure the package before it is built</para> + </listitem> - <para>Please note that the use of <varname>NO_PACKAGE</varname>, - <varname>IGNORE</varname>, <varname>NO_CDROM</varname>, or other - generic make variables to denote restrictions is deprecated, - because they unconditionally prevent users from generating - binary packages!</para> - </sect2> + <listitem> + <para>help during the build process</para> + </listitem> + <listitem> + <para>help during the installation of a package</para> + </listitem> + </itemizedlist> + + <para>The <varname>INTERACTIVE_STAGE</varname> definition is provided to notify + the pkgsrc mechanism of an interactive stage which will be needed, and + this should be set in the package's <filename>Makefile</filename>, e.g.:</para> + + <programlisting> + INTERACTIVE_STAGE= build + </programlisting> + + <para>Multiple interactive stages can be specified:</para> + + <programlisting> + INTERACTIVE_STAGE= configure install + </programlisting> + + </sect2> + + <sect2 id="handling-licenses"> + <title>Handling licenses</title> + + <para>A package may be covered by a license which the user has + or has not agreed to accept. For these cases, pkgsrc contains + a mechanism to note that a package is covered by a particular + license, and the package cannot be built unless the user has + accepted the license. (Installation of binary packages are + not currently subject to this mechanism.) Packages with + licenses that are either Open Source according to the Open + Source Initiative or Free according to the Free Software + Foundation will not be marked with a license tag. Packages + with licenses that have not been determined to meet either + definition will be marked with a license tag referring to the + license. This will prevent building unless pkgsrc is informed + that the license is acceptable, and enables displaying the + license.</para> + + <para>The license tag mechanism is intended to address + copyright-related issues surrounding building, installing and + using a package, and not to address redistribution issues (see + <varname>RESTRICTED</varname> and + <varname>NO_SRC_ON_FTP</varname>, etc.). However, the above + definition of licenses for which tags are not needed implies + that packages with redistribution restrictions should have + tags.</para> + + <para>Denoting that a package is covered by a particular license + is done by placing the license in + <filename>pkgsrc/licenses</filename> and setting the + <varname>LICENSE</varname> variable to a string identifying the + license, e.g. in <filename + role="pkg">graphics/xv</filename>:</para> + + <programlisting> + LICENSE= xv-license + </programlisting> + + <para>When trying to build, the user will get a notice that the + package is covered by a license which has not been + accepted:</para> + + <programlisting> + &cprompt; <userinput>make</userinput> + ===> xv-3.10anb9 has an unacceptable license: xv-license. + ===> To view the license, enter "/usr/bin/make show-license". + ===> To indicate acceptance, add this line to your /etc/mk.conf: + ===> ACCEPTABLE_LICENSES+=xv-license + *** Error code 1 + </programlisting> + + <para>The license can be viewed with <command>make + show-license</command>, and if it is considered appropriate, + the line printed above can be added to + <filename>/etc/mk.conf</filename> to indicate acceptance of + the particular license:</para> + + <programlisting> + ACCEPTABLE_LICENSES+=xv-license + </programlisting> + + <para>When adding a package with a new license, the license + text should be added to <filename>pkgsrc/licenses</filename> + for displaying. A list of known licenses can be seen in this + directory as well as by looking at the list of (commented + out) <varname>ACCEPTABLE_LICENSES</varname> variable + settings in + <filename>pkgsrc/mk/defaults/mk.conf</filename>.</para> + + <para>The use of <varname>LICENSE=shareware</varname>, + <varname>LICENSE=no-commercial-use</varname>, and similar + language is deprecated because it does not crisply refer to + a particular license text. Another problem with such usage + is that it does not enable a user to denote acceptance of + the license for a single package without accepting the same + license text for another package. In particular, this can + be inappropriate when e.g. one accepts a particular license to + indicate to pkgsrc that a fee has been paid.</para> + </sect2> + + <sect2 id="restricted-packages"> + <title>Restricted packages</title> + + <para>Some licenses restrict how software may be re-distributed. + In order to satisfy these restrictions, the package system + defines five make variables that can be set to note these + restrictions:</para> + + <itemizedlist> + <listitem> + <para><varname>RESTRICTED</varname></para> - <sect2 id="dependencies"> - <title>Handling dependencies</title> + <para>This variable should be set whenever a restriction + exists (regardless of its kind). Set this variable to a + string containing the reason for the restriction.</para> + </listitem> - <para>Your package may depend on some other package being present - - and there are various ways of expressing this - dependency. pkgsrc supports the <varname>BUILD_DEPENDS</varname> - and <varname>DEPENDS</varname> definitions, the - <varname>USE_TOOLS</varname> definition, as well as - dependencies via <filename>buildlink3.mk</filename>, which is - the preferred way to handle dependencies, and which uses the - variables named above. See <xref linkend="buildlink"/> for more - information.</para> + <listitem> + <para><varname>NO_BIN_ON_CDROM</varname></para> - <para>The basic difference between the two variables is as - follows: The <varname>DEPENDS</varname> definition registers - that pre-requisite in the binary package so it will be pulled in - when the binary package is later installed, whilst the - <varname>BUILD_DEPENDS</varname> definition does not, marking a - dependency that is only needed for building the package. -</para> + <para>Binaries may not be placed on CD-ROM. Set this + variable to <varname>${RESTRICTED}</varname> whenever a + binary package may not be included on a CD-ROM.</para> + </listitem> - <para>This means that if you only need a package present whilst - you are building, it should be noted as a - <varname>BUILD_DEPENDS</varname>.</para> + <listitem> + <para><varname>NO_BIN_ON_FTP</varname></para> - <para>The format for a <varname>BUILD_DEPENDS</varname> and a - <varname>DEPENDS</varname> definition is:</para> + <para>Binaries may not be placed on an FTP server. Set + this variable to <varname>${RESTRICTED}</varname> + whenever a binary package may not not be made available + on the Internet.</para> + </listitem> -<programlisting> - <pre-req-package-name>:../../<category>/<pre-req-package> -</programlisting> + <listitem> + <para><varname>NO_SRC_ON_CDROM</varname></para> - <para>Please note that the <quote>pre-req-package-name</quote> - may include any of the wildcard version numbers recognized by - &man.pkg.info.1;.</para> + <para>Distfiles may not be placed on CD-ROM. Set this + variable to <varname>${RESTRICTED}</varname> if + re-distribution of the source code or other distfile(s) is + not allowed on CD-ROMs.</para> + </listitem> - <orderedlist> - <listitem> - <para>If your package needs another package's binaries or - libraries to build or run, and if that package has a - <filename>buildlink3.mk</filename> file available, use it: -</para> + <listitem> + <para><varname>NO_SRC_ON_FTP</varname></para> -<programlisting> - .include "../../graphics/jpeg/buildlink3.mk" -</programlisting> - </listitem> + <para>Distfiles may not be placed on FTP. Set this variable + to <varname>${RESTRICTED}</varname> if re-distribution of + the source code or other distfile(s) via the Internet is not + allowed. If this variable is not set, the distfile(s) will + be mirrored on ftp.NetBSD.org.</para> + </listitem> + </itemizedlist> + + <para>Please note that the use of <varname>NO_PACKAGE</varname>, + <varname>IGNORE</varname>, <varname>NO_CDROM</varname>, or other + generic make variables to denote restrictions is deprecated, + because they unconditionally prevent users from generating + binary packages!</para> + </sect2> + + + <sect2 id="dependencies"> + <title>Handling dependencies</title> + + <para>Your package may depend on some other package being present + - and there are various ways of expressing this + dependency. pkgsrc supports the <varname>BUILD_DEPENDS</varname> + and <varname>DEPENDS</varname> definitions, the + <varname>USE_TOOLS</varname> definition, as well as + dependencies via <filename>buildlink3.mk</filename>, which is + the preferred way to handle dependencies, and which uses the + variables named above. See <xref linkend="buildlink"/> for more + information.</para> + + <para>The basic difference between the two variables is as + follows: The <varname>DEPENDS</varname> definition registers + that pre-requisite in the binary package so it will be pulled in + when the binary package is later installed, whilst the + <varname>BUILD_DEPENDS</varname> definition does not, marking a + dependency that is only needed for building the package.</para> + + <para>This means that if you only need a package present whilst + you are building, it should be noted as a + <varname>BUILD_DEPENDS</varname>.</para> + + <para>The format for a <varname>BUILD_DEPENDS</varname> and a + <varname>DEPENDS</varname> definition is:</para> + + <programlisting> + <pre-req-package-name>:../../<category>/<pre-req-package> + </programlisting> + + <para>Please note that the <quote>pre-req-package-name</quote> + may include any of the wildcard version numbers recognized by + &man.pkg.info.1;.</para> + + <orderedlist> + <listitem> + <para>If your package needs another package's binaries or + libraries to build or run, and if that package has a + <filename>buildlink3.mk</filename> file available, use it:</para> - <listitem> - <para>If your package needs to use another package to build - itself and there is no <filename>buildlink3.mk</filename> - file available, use the <varname>BUILD_DEPENDS</varname> - definition:</para> + <programlisting> + .include "../../graphics/jpeg/buildlink3.mk" + </programlisting> + </listitem> -<programlisting> - BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf -</programlisting> - </listitem> + <listitem> + <para>If your package needs to use another package to build + itself and there is no <filename>buildlink3.mk</filename> + file available, use the <varname>BUILD_DEPENDS</varname> + definition:</para> + + <programlisting> + BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf + </programlisting> + </listitem> - <listitem> + <listitem> <para>If your package needs a library with which to link and again there is no <filename>buildlink3.mk</filename> file - available, this is specified using the - <varname>DEPENDS</varname> definition. For example:</para> - -<programlisting> - DEPENDS+= xpm-3.4j:../../graphics/xpm -</programlisting> - - <para>You can also use wildcards in package dependences:</para> - -<programlisting> - DEPENDS+= xpm-[0-9]*:../../graphics/xpm -</programlisting> - - <para>Note that such wildcard dependencies are retained when - creating binary packages. The dependency is checked when - installing the binary package and any package which matches - the pattern will be used. Wildcard dependencies should be - used with care.</para> - - <para>The <quote>-[0-9]*</quote> should be used instead of - <quote>-*</quote> to avoid potentially ambiguous matches - such as <quote>tk-postgresql</quote> matching a - <quote>tk-*</quote> <varname>DEPENDS</varname>.</para> - - <para>Wildcards can also be used to specify that a package - will only build against a certain minimum version of a - pre-requisite:</para> - -<programlisting> - DEPENDS+= tiff>=3.5.4:../../graphics/tiff -</programlisting> - - <para>This means that the package will build against version - 3.5.4 of the tiff library or newer. Such a dependency may - be warranted if, for example, the API of the library has - changed with version 3.5.4 and a package would not compile - against an earlier version of tiff.</para> - - <para>Please note that such dependencies should only be - updated if a package requires a newer pre-requisite, but - not to denote recommendations such as - ABI changes that do not prevent a package from building - correctly. Such recommendations can be expressed using - <varname>ABI_DEPENDS</varname>:</para> - -<programlisting> - ABI_DEPENDS+= tiff>=3.6.1:../../graphics/tiff -</programlisting> - - <para>In addition to the above <varname>DEPENDS</varname> - line, this denotes that while a package will build against - tiff>=3.5.4, at least version 3.6.1 is recommended. - <varname>ABI_DEPENDS</varname> entries will be turned into - dependencies unless explicitly ignored (in which case a - warning will be printed).</para> - - <para>To ignore these ABI dependency recommendations and just - use the required <varname>DEPENDS</varname>, set - <varname>USE_ABI_DEPENDS=NO</varname>. This may make - it easier and faster to update packages built using pkgsrc, - since older compatible dependencies can continue to be - used. This is useful for people who watch their rebuilds - very carefully; it is not very good as a general-purpose - hammer. If you use it, you need to be mindful of possible - ABI changes, including those from the underlying OS. -</para> - - <para>Packages that are built with recommendations ignored - may not be uploaded to ftp.NetBSD.org by developers and - should not be used across different systems that may have - different versions of binary packages installed.</para> - - <para>For security fixes, please update the package - vulnerabilities file. See <xref - linkend="security-handling"/> for more - information.</para> - </listitem> - - <listitem> - <para>If your package needs some executable to be able to run - correctly and if there's no - <filename>buildlink3.mk</filename> file, this is specified - using the <varname>DEPENDS</varname> variable. The - <filename role="pkg">print/lyx</filename> package needs to - be able to execute the latex binary from the teTeX package - when it runs, and that is specified:</para> - -<programlisting> - DEPENDS+= teTeX-[0-9]*:../../print/teTeX -</programlisting> - - <para>The comment about wildcard dependencies from previous - paragraph applies here, too.</para> - </listitem> - </orderedlist> - - <para>If your package needs files from another package to build, - add the relevant distribution files to - <varname>DISTFILES</varname>, so they will be extracted - automatically. See the <filename - role="pkg">print/ghostscript</filename> package for an example. - (It relies on the jpeg sources being present in source form - during the build.)</para> - - <para>Please also note the <varname>BUILD_USES_MSGFMT</varname> - and <varname>BUILD_USES_GETTEXT_M4</varname> definitions, which - are provided as convenience definitions. The former works out - whether &man.msgfmt.1; is part of the base system, and, if it isn't, - installs the <filename role="pkg">devel/gettext</filename> package. - The latter adds a build dependency on either an installed - version of an older gettext package, or if it isn't, installs the - <filename role="pkg">devel/gettext-m4</filename> package.</para> - </sect2> - - - <sect2 id="conflicts"> - <title>Handling conflicts with other packages</title> - - <para>Your package may conflict with other packages a user might - already have installed on his system, e.g. if your package - installs the same set of files like another package in our - pkgsrc tree.</para> - - <para>In this case you can set <varname>CONFLICTS</varname> to a - space-separated list of packages (including version string) your - package conflicts with.</para> - - <para>For example, <filename role="pkg">x11/Xaw3d</filename> - and <filename role="pkg">x11/Xaw-Xpm</filename> - install the same shared library, thus you set in - <filename>pkgsrc/x11/Xaw3d/Makefile</filename>:</para> - -<programlisting> - CONFLICTS= Xaw-Xpm-[0-9]* -</programlisting> - - <para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>: -</para> - -<programlisting> - CONFLICTS= Xaw3d-[0-9]* -</programlisting> - - <para>Packages will automatically conflict with other packages - with the name prefix and a different version - string. <quote>Xaw3d-1.5</quote> e.g. will automatically - conflict with the older version <quote>Xaw3d-1.3</quote>. -</para> - </sect2> - - - <sect2 id="not-building-packages"> - <title>Packages that cannot or should not be built</title> - - <para>There are several reasons why a package might be - instructed to not build under certain circumstances. If the - package builds and runs on most platforms, the exceptions - should be noted with <varname>NOT_FOR_PLATFORM</varname>. If - the package builds and runs on a small handful of platforms, - set <varname>ONLY_FOR_PLATFORM</varname> instead. - Both <varname>ONLY_FOR_PLATFORM</varname> and - <varname>NOT_FOR_PLATFORM</varname> are OS triples - (OS-version-platform) that can use glob-style - wildcards.</para> - <para>If the package should be skipped (for example, because it - provides functionality already provided by the system), set - <varname>PKG_SKIP_REASON</varname> to a descriptive message. - If the package should fail because some preconditions are not - met, set <varname>PKG_FAIL_REASON</varname> to a descriptive - message.</para> - </sect2> - - - <sect2 id="undeletable-packages"> - <title>Packages which should not be deleted, once installed</title> - - <para>To ensure that a package may not be deleted, once it has been - installed, the <varname>PKG_PRESERVE</varname> definition should - be set in the package Makefile. This will be carried into any - binary package that is made from this pkgsrc entry. A - <quote>preserved</quote> package will - not be deleted using &man.pkg.delete.1; unless the - <quote>-f</quote> option is used.</para> - </sect2> - - - <sect2 id="security-handling"> - <title>Handling packages with security problems</title> - - <para>When a vulnerability is found, this should be noted in - <filename>localsrc/security/advisories/pkg-vulnerabilities</filename>, - and after committing that file, use <command>make upload</command> - in the same directory to update the file on ftp.NetBSD.org.</para> - - <para>After fixing the vulnerability by a patch, its - <varname>PKGREVISION</varname> should be increased (this - is of course not necessary if the problem is fixed by using - a newer release of the software).</para> - - <para>Also, if the fix should be applied to the stable pkgsrc - branch, be sure to submit a pullup request!</para> - - <para>Binary packages already on ftp.NetBSD.org will be handled - semi-automatically by a weekly cron job.</para> - </sect2> - - - <sect2 id="bumping-pkgrevision"> - <title>How to handle incrementing versions when fixing an existing package</title> - - <para>When making fixes to an existing package it can be useful - to change the version number in <varname>PKGNAME</varname>. To - avoid conflicting with future versions by the original author, a - <quote>nb1</quote>, <quote>nb2</quote>, ... suffix can be used - on package versions by setting <varname>PKGREVISION=1</varname> - (2, ...). The <quote>nb</quote> is treated like a - <quote>.</quote> by the pkg tools. e.g.</para> - -<programlisting> - DISTNAME= foo-17.42 - PKGREVISION= 9 -</programlisting> - - <para>will result in a <varname>PKGNAME</varname> of - <quote>foo-17.42nb9</quote>.</para> - - <para>When a new release of the package is released, the - <varname>PKGREVISION</varname> should be removed, e.g. on a new - minor release of the above package, things should be like:</para> - -<programlisting> - DISTNAME= foo-17.43 -</programlisting> - - <para>PKGREVISION should be incremented for any non-trivial change in the - resulting binary package. Without a PKGREVISION bump, someone with - the previous version installed has no way of knowing that their - package is out of date. Thus, changes without increasing PKGREVISION - are essentially labeled "this is so trivial that no reasonable person - would want to upgrade", and this is the rough test for when increasing - PKGREVISION is appropriate. Examples of changes that do not merit - increasing PKGREVISION are:</para> - -<programlisting> -Changing HOMEPAGE, MAINTAINER, or comments in Makefile. -Changing build variables if the resulting binary package is the same. -Changing DESCR. -Adding PKG_OPTIONS if the default options don't change. -</programlisting> + available, this is specified using the + <varname>DEPENDS</varname> definition. For example:</para> + + <programlisting> + DEPENDS+= xpm-3.4j:../../graphics/xpm + </programlisting> + + <para>You can also use wildcards in package dependences:</para> + + <programlisting> + DEPENDS+= xpm-[0-9]*:../../graphics/xpm + </programlisting> + + <para>Note that such wildcard dependencies are retained when + creating binary packages. The dependency is checked when + installing the binary package and any package which matches + the pattern will be used. Wildcard dependencies should be + used with care.</para> + + <para>The <quote>-[0-9]*</quote> should be used instead of + <quote>-*</quote> to avoid potentially ambiguous matches + such as <quote>tk-postgresql</quote> matching a + <quote>tk-*</quote> <varname>DEPENDS</varname>.</para> + + <para>Wildcards can also be used to specify that a package + will only build against a certain minimum version of a + pre-requisite:</para> + + <programlisting> + DEPENDS+= tiff>=3.5.4:../../graphics/tiff + </programlisting> + + <para>This means that the package will build against version + 3.5.4 of the tiff library or newer. Such a dependency may + be warranted if, for example, the API of the library has + changed with version 3.5.4 and a package would not compile + against an earlier version of tiff.</para> + + <para>Please note that such dependencies should only be + updated if a package requires a newer pre-requisite, but + not to denote recommendations such as + ABI changes that do not prevent a package from building + correctly. Such recommendations can be expressed using + <varname>ABI_DEPENDS</varname>:</para> + + <programlisting> + ABI_DEPENDS+= tiff>=3.6.1:../../graphics/tiff + </programlisting> + + <para>In addition to the above <varname>DEPENDS</varname> + line, this denotes that while a package will build against + tiff>=3.5.4, at least version 3.6.1 is recommended. + <varname>ABI_DEPENDS</varname> entries will be turned into + dependencies unless explicitly ignored (in which case a + warning will be printed).</para> + + <para>To ignore these ABI dependency recommendations and just + use the required <varname>DEPENDS</varname>, set + <varname>USE_ABI_DEPENDS=NO</varname>. This may make + it easier and faster to update packages built using pkgsrc, + since older compatible dependencies can continue to be + used. This is useful for people who watch their rebuilds + very carefully; it is not very good as a general-purpose + hammer. If you use it, you need to be mindful of possible + ABI changes, including those from the underlying OS.</para> + + <para>Packages that are built with recommendations ignored + may not be uploaded to ftp.NetBSD.org by developers and + should not be used across different systems that may have + different versions of binary packages installed.</para> + + <para>For security fixes, please update the package + vulnerabilities file. See <xref + linkend="security-handling"/> for more + information.</para> + </listitem> - <para>Examples of changes that do merit an increase to PKGREVISION - include:</para> -<programlisting> -Security fixes -Changes or additions to a patch file -Changes to the PLIST -</programlisting> + <listitem> + <para>If your package needs some executable to be able to run + correctly and if there's no + <filename>buildlink3.mk</filename> file, this is specified + using the <varname>DEPENDS</varname> variable. The + <filename role="pkg">print/lyx</filename> package needs to + be able to execute the latex binary from the teTeX package + when it runs, and that is specified:</para> + + <programlisting> + DEPENDS+= teTeX-[0-9]*:../../print/teTeX + </programlisting> + + <para>The comment about wildcard dependencies from previous + paragraph applies here, too.</para> + </listitem> + </orderedlist> + + <para>If your package needs files from another package to build, + add the relevant distribution files to + <varname>DISTFILES</varname>, so they will be extracted + automatically. See the <filename + role="pkg">print/ghostscript</filename> package for an example. + (It relies on the jpeg sources being present in source form + during the build.)</para> + + <para>Please also note the <varname>BUILD_USES_MSGFMT</varname> + and <varname>BUILD_USES_GETTEXT_M4</varname> definitions, which + are provided as convenience definitions. The former works out + whether &man.msgfmt.1; is part of the base system, and, if it isn't, + installs the <filename role="pkg">devel/gettext</filename> package. + The latter adds a build dependency on either an installed + version of an older gettext package, or if it isn't, installs the + <filename role="pkg">devel/gettext-m4</filename> package.</para> + </sect2> + + + <sect2 id="conflicts"> + <title>Handling conflicts with other packages</title> + + <para>Your package may conflict with other packages a user might + already have installed on his system, e.g. if your package + installs the same set of files like another package in our + pkgsrc tree.</para> + + <para>In this case you can set <varname>CONFLICTS</varname> to a + space-separated list of packages (including version string) your + package conflicts with.</para> + + <para>For example, <filename role="pkg">x11/Xaw3d</filename> + and <filename role="pkg">x11/Xaw-Xpm</filename> + install the same shared library, thus you set in + <filename>pkgsrc/x11/Xaw3d/Makefile</filename>:</para> + + <programlisting> + CONFLICTS= Xaw-Xpm-[0-9]* + </programlisting> + + <para>and in <filename>pkgsrc/x11/Xaw-Xpm/Makefile</filename>:</para> + + <programlisting> + CONFLICTS= Xaw3d-[0-9]* + </programlisting> + + <para>Packages will automatically conflict with other packages + with the name prefix and a different version + string. <quote>Xaw3d-1.5</quote> e.g. will automatically + conflict with the older version <quote>Xaw3d-1.3</quote>.</para> + </sect2> + + + <sect2 id="not-building-packages"> + <title>Packages that cannot or should not be built</title> + + <para>There are several reasons why a package might be + instructed to not build under certain circumstances. If the + package builds and runs on most platforms, the exceptions + should be noted with <varname>NOT_FOR_PLATFORM</varname>. If + the package builds and runs on a small handful of platforms, + set <varname>ONLY_FOR_PLATFORM</varname> instead. + Both <varname>ONLY_FOR_PLATFORM</varname> and + <varname>NOT_FOR_PLATFORM</varname> are OS triples + (OS-version-platform) that can use glob-style + wildcards.</para> + <para>If the package should be skipped (for example, because it + provides functionality already provided by the system), set + <varname>PKG_SKIP_REASON</varname> to a descriptive message. + If the package should fail because some preconditions are not + met, set <varname>PKG_FAIL_REASON</varname> to a descriptive + message.</para> + </sect2> + + + <sect2 id="undeletable-packages"> + <title>Packages which should not be deleted, once installed</title> + + <para>To ensure that a package may not be deleted, once it has been + installed, the <varname>PKG_PRESERVE</varname> definition should + be set in the package Makefile. This will be carried into any + binary package that is made from this pkgsrc entry. A + <quote>preserved</quote> package will + not be deleted using &man.pkg.delete.1; unless the + <quote>-f</quote> option is used.</para> + </sect2> + + + <sect2 id="security-handling"> + <title>Handling packages with security problems</title> + + <para>When a vulnerability is found, this should be noted in + <filename>localsrc/security/advisories/pkg-vulnerabilities</filename>, + and after committing that file, use <command>make upload</command> + in the same directory to update the file on ftp.NetBSD.org.</para> + + <para>After fixing the vulnerability by a patch, its + <varname>PKGREVISION</varname> should be increased (this + is of course not necessary if the problem is fixed by using + a newer release of the software).</para> + + <para>Also, if the fix should be applied to the stable pkgsrc + branch, be sure to submit a pullup request!</para> + + <para>Binary packages already on ftp.NetBSD.org will be handled + semi-automatically by a weekly cron job.</para> + </sect2> + + + <sect2 id="bumping-pkgrevision"> + <title>How to handle incrementing versions when fixing an existing package</title> + + <para>When making fixes to an existing package it can be useful + to change the version number in <varname>PKGNAME</varname>. To + avoid conflicting with future versions by the original author, a + <quote>nb1</quote>, <quote>nb2</quote>, ... suffix can be used + on package versions by setting <varname>PKGREVISION=1</varname> + (2, ...). The <quote>nb</quote> is treated like a + <quote>.</quote> by the package tools. e.g.</para> + + <programlisting> + DISTNAME= foo-17.42 + PKGREVISION= 9 + </programlisting> + + <para>will result in a <varname>PKGNAME</varname> of + <quote>foo-17.42nb9</quote>. If you want to use the original + value of <varname>PKGNAME</varname> without the <quote>nbX</quote> + suffix, e.g. for setting <varname>DIST_SUBDIR</varname>, use + <varname>PKGNAME_NOREV</varname>.</para> + + <para>When a new release of the package is released, the + <varname>PKGREVISION</varname> should be removed, e.g. on a new + minor release of the above package, things should be like:</para> + + <programlisting> + DISTNAME= foo-17.43 + </programlisting> + + <para><varname>PKGREVISION</varname> should be incremented for any + non-trivial change in the resulting binary package. Without a + <varname>PKGREVISION</varname> bump, someone with the previous + version installed has no way of knowing that their package is out + of date. Thus, changes without increasing + <varname>PKGREVISION</varname> are essentially labeled "this is so + trivial that no reasonable person would want to upgrade", and this + is the rough test for when increasing + <varname>PKGREVISION</varname> is appropriate. Examples of + changes that do not merit increasing + <varname>PKGREVISION</varname> are:</para> + + <programlisting> + Changing <varname>HOMEPAGE</varname>, <varname>MAINTAINER</varname>, + or comments in Makefile. + Changing build variables if the resulting binary package is the same. + Changing <filename>DESCR</filename>. + Adding <varname>PKG_OPTIONS</varname> if the default options don't change. + </programlisting> + + <para>Examples of changes that do merit an increase to + <varname>PKGREVISION</varname> include:</para> + <programlisting> + Security fixes + Changes or additions to a patch file + Changes to the <filename>PLIST</filename> + </programlisting> <para>PKGREVISION must also be incremented when dependencies have ABI changes.</para> - </sect2> - -<sect2 id="fixes.subst"> -<title>Substituting variable text in the package files (the SUBST framework)</title> - - <para>When you want to replace the same text in multiple files - or when the replacement text varies, patches alone cannot help. - This is where the SUBST framework comes in. It provides an - easy-to-use interface for replacing text in files. - Example:</para> - -<programlisting> - SUBST_CLASSES+= fix-paths - SUBST_STAGE.fix-paths= pre-configure - SUBST_MESSAGE.fix-paths= Fixing absolute paths. - SUBST_FILES.fix-paths= src/*.c - SUBST_FILES.fix-paths+= scripts/*.sh - SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g' - SUBST_SED.fix-paths+= -e 's,"/var/log,"${VARBASE}/log,g' -</programlisting> - - <para><varname>SUBST_CLASSES</varname> is a list of identifiers - that are used to identify the different SUBST blocks that are - defined. The SUBST framework is heavily used by pkgsrc, so it is - important to always use the <literal>+=</literal> operator with - this variable. Otherwise some substitutions may be - skipped.</para> - - <para>The remaining variables of each SUBST block are - parameterized with the identifier from the first line - (<literal>fix-paths</literal> in this case.) They can be seen as - parameters to a function call.</para> - - <para><varname>SUBST_STAGE.*</varname> specifies the stage at - which the replacement will take place. All combinations of - <literal>pre-</literal>, <literal>do-</literal> and - <literal>post-</literal> together with a phase name are - possible, though only few are actually used. Most commonly used - are <literal>post-patch</literal> and - <literal>pre-configure</literal>. Of these two, - <literal>pre-configure</literal> should be preferred because - then it is possible to run <command>bmake patch</command> and - have the state after applying the patches but before making any - other changes. This is especially useful when you are debugging - a package in order to create new patches for it. Similarly, - <literal>post-build</literal> is preferred over - <literal>pre-install</literal>, because the install phase should - generally be kept as simple as possible. When you use - <literal>post-build</literal>, you have the same files in the - working directory that will be installed later, so you can check - if the substitution has succeeded.</para> - - <para><varname>SUBST_MESSAGE.*</varname> is an optional text - that is printed just before the substitution is done.</para> - - <para><varname>SUBST_FILES.*</varname> is the list of shell - globbing patterns that specifies the files in which the - substitution will take place. The patterns are interpreted - relatively to the <varname>WRKSRC</varname> directory.</para> - - <para><varname>SUBST_SED.*</varname> is a list of arguments to - &man.sed.1; that specify the actual substitution. Every sed - command should be prefixed with <literal>-e</literal>, so that - all SUBST blocks look uniform.</para> - - <para>There are some more variables, but they are so seldomly - used that they are only documented in the - <filename>mk/subst.mk</filename> file.</para> - -</sect2> + </sect2> + + <sect2 id="fixes.subst"> + <title>Substituting variable text in the package files (the SUBST framework)</title> + + <para>When you want to replace the same text in multiple files + or when the replacement text varies, patches alone cannot help. + This is where the SUBST framework comes in. It provides an + easy-to-use interface for replacing text in files. + Example:</para> + + <programlisting> + SUBST_CLASSES+= fix-paths + SUBST_STAGE.fix-paths= pre-configure + SUBST_MESSAGE.fix-paths= Fixing absolute paths. + SUBST_FILES.fix-paths= src/*.c + SUBST_FILES.fix-paths+= scripts/*.sh + SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g' + SUBST_SED.fix-paths+= -e 's,"/var/log,"${VARBASE}/log,g' + </programlisting> + + <para><varname>SUBST_CLASSES</varname> is a list of identifiers + that are used to identify the different SUBST blocks that are + defined. The SUBST framework is heavily used by pkgsrc, so it is + important to always use the <literal>+=</literal> operator with + this variable. Otherwise some substitutions may be + skipped.</para> + + <para>The remaining variables of each SUBST block are + parameterized with the identifier from the first line + (<literal>fix-paths</literal> in this case.) They can be seen as + parameters to a function call.</para> + + <para><varname>SUBST_STAGE.*</varname> specifies the stage at + which the replacement will take place. All combinations of + <literal>pre-</literal>, <literal>do-</literal> and + <literal>post-</literal> together with a phase name are + possible, though only few are actually used. Most commonly used + are <literal>post-patch</literal> and + <literal>pre-configure</literal>. Of these two, + <literal>pre-configure</literal> should be preferred because + then it is possible to run <command>bmake patch</command> and + have the state after applying the patches but before making any + other changes. This is especially useful when you are debugging + a package in order to create new patches for it. Similarly, + <literal>post-build</literal> is preferred over + <literal>pre-install</literal>, because the install phase should + generally be kept as simple as possible. When you use + <literal>post-build</literal>, you have the same files in the + working directory that will be installed later, so you can check + if the substitution has succeeded.</para> + + <para><varname>SUBST_MESSAGE.*</varname> is an optional text + that is printed just before the substitution is done.</para> + + <para><varname>SUBST_FILES.*</varname> is the list of shell + globbing patterns that specifies the files in which the + substitution will take place. The patterns are interpreted + relatively to the <varname>WRKSRC</varname> directory.</para> + + <para><varname>SUBST_SED.*</varname> is a list of arguments to + &man.sed.1; that specify the actual substitution. Every sed + command should be prefixed with <literal>-e</literal>, so that + all SUBST blocks look uniform.</para> + + <para>There are some more variables, but they are so seldomly + used that they are only documented in the + <filename>mk/subst.mk</filename> file.</para> + + </sect2> </sect1> <sect1 id="fixes.fetch"> -<title>Fixing problems in the <emphasis>fetch</emphasis> phase</title> - - <sect2 id="no-plain-download"> - <title>Packages whose distfiles aren't available for plain downloading</title> - - <para>If you need to download from a dynamic URL you can set - <varname>DYNAMIC_MASTER_SITES</varname> and a <command>make - fetch</command> will call <filename>files/getsite.sh</filename> - with the name of each file to download as an argument, expecting - it to output the URL of the directory from which to download - it. <filename role="pkg">graphics/ns-cult3d</filename> is an - example of this usage.</para> - - <para>If the download can't be automated, because the user must - submit personal information to apply for a password, or must pay - for the source, or whatever, you can set - <varname>FETCH_MESSAGE</varname> to a list of lines that are - displayed to the user before aborting the build. Example:</para> - -<programlisting> - FETCH_MESSAGE= "Please download the files" - FETCH_MESSAGE+= " "${DISTFILES:Q} - FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"." -</programlisting> - - </sect2> - - - <sect2 id="modified-distfiles-same-name"> - <title>How to handle modified distfiles with the 'old' name</title> - - <para>Sometimes authors of a software package make some - modifications after the software was released, and they put up a - new distfile without changing the package's version number. If a - package is already in pkgsrc at that time, the checksum will - no longer match. The contents of the new distfile should be - compared against the old one before changing anything, to make - sure the distfile was really updated on purpose, and that - no trojan horse or so crept in. - Then, the correct way to work around this is to - set <varname>DIST_SUBDIR</varname> to a unique directory name, - usually based on <varname>PKGNAME_NOREV</varname>. In case this - happens more often, <varname>PKGNAME</varname> can be used (thus - including the <filename>nbX</filename> suffix) or a date stamp - can be appended, like <varname>${PKGNAME_NOREV}-YYYYMMDD</varname>. - Do not forget regenerating the <filename>distinfo</filename> file - after that, since it contains the <varname>DIST_SUBDIR</varname> - path in the filenames. - Furthermore, a mail to the package's authors seems appropriate - telling them that changing distfiles after releases without - changing the file names is not good practice.</para> - </sect2> - </sect1> + <title>Fixing problems in the <emphasis>fetch</emphasis> phase</title> + + <sect2 id="no-plain-download"> + <title>Packages whose distfiles aren't available for plain downloading</title> + + <para>If you need to download from a dynamic URL you can set + <varname>DYNAMIC_MASTER_SITES</varname> and a <command>make + fetch</command> will call <filename>files/getsite.sh</filename> + with the name of each file to download as an argument, expecting + it to output the URL of the directory from which to download + it. <filename role="pkg">graphics/ns-cult3d</filename> is an + example of this usage.</para> + + <para>If the download can't be automated, because the user must + submit personal information to apply for a password, or must pay + for the source, or whatever, you can set + <varname>FETCH_MESSAGE</varname> to a list of lines that are + displayed to the user before aborting the build. Example:</para> + + <programlisting> + FETCH_MESSAGE= "Please download the files" + FETCH_MESSAGE+= " "${DISTFILES:Q} + FETCH_MESSAGE+= "manually from "${MASTER_SITES:Q}"." + </programlisting> + + </sect2> + + + <sect2 id="modified-distfiles-same-name"> + <title>How to handle modified distfiles with the 'old' name</title> + + <para>Sometimes authors of a software package make some + modifications after the software was released, and they put up a + new distfile without changing the package's version number. If a + package is already in pkgsrc at that time, the checksum will + no longer match. The contents of the new distfile should be + compared against the old one before changing anything, to make + sure the distfile was really updated on purpose, and that + no trojan horse or so crept in. + Then, the correct way to work around this is to + set <varname>DIST_SUBDIR</varname> to a unique directory name, + usually based on <varname>PKGNAME_NOREV</varname>. All + <varname>DISTFILES</varname> and + <varname>PATCHFILES</varname> for this package will be put in that + subdirectory of the local distfiles directory. In case this + happens more often, <varname>PKGNAME</varname> can be used (thus + including the <filename>nbX</filename> suffix) or a date stamp + can be appended, like <varname>${PKGNAME_NOREV}-YYYYMMDD</varname>. + Do not forget regenerating the <filename>distinfo</filename> file + after that, since it contains the <varname>DIST_SUBDIR</varname> + path in the filenames. + Furthermore, a mail to the package's authors seems appropriate + telling them that changing distfiles after releases without + changing the file names is not good practice.</para> + </sect2> +</sect1> <sect1 id="fixes.configure"> -<title>Fixing problems in the <emphasis>configure</emphasis> phase</title> - - <sect2 id="fixes.libtool"> - <title>Shared libraries - libtool</title> - - <para>pkgsrc supports many different machines, with different - object formats like a.out and ELF, and varying abilities to do - shared library and dynamic loading at all. To accompany this, - varying commands and options have to be passed to the - compiler, linker, etc. to get the Right Thing, which can be - pretty annoying especially if you don't have all the machines - at your hand to test things. The - <filename role="pkg">devel/libtool</filename> pkg - can help here, as it just <quote>knows</quote> how to build - both static and dynamic libraries from a set of source files, - thus being platform-independent.</para> - - <para>Here's how to use libtool in a pkg in seven simple - steps:</para> - - <orderedlist> - <listitem> - <para>Add <varname>USE_LIBTOOL=yes</varname> to the package - Makefile.</para> - </listitem> - - <listitem> - <para>For library objects, use <quote>${LIBTOOL} --mode=compile - ${CC}</quote> in place of <quote>${CC}</quote>. You could even - add it to the definition of <varname>CC</varname>, if only - libraries are being built in a given Makefile. This one command - will build both PIC and non-PIC library objects, so you need not - have separate shared and non-shared library rules.</para> - </listitem> - - <listitem> - <para>For the linking of the library, remove any - <quote>ar</quote>, <quote>ranlib</quote>, and <quote>ld - -Bshareable</quote> commands, and instead use:</para> - -<programlisting> - ${LIBTOOL} --mode=link ${CC} -o ${.TARGET:.a=.la} ${OBJS:.o=.lo} \ - -rpath ${PREFIX}/lib -version-info major:minor -</programlisting> - - <para>Note that the library is changed to have a - <filename>.la</filename> extension, and the objects are - changed to have a <filename>.lo</filename> - extension. Change <varname>OBJS</varname> as - necessary. This automatically creates all of the - <filename>.a</filename>, - <filename>.so.major.minor</filename>, and ELF symlinks (if - necessary) in the build directory. Be sure to include - <quote>-version-info</quote>, especially when major and - minor are zero, as libtool will otherwise strip off the - shared library version.</para> - - <para>From the libtool manual:</para> - -<programlisting> - So, libtool library versions are described by three integers: - - CURRENT - The most recent interface number that this library implements. - - REVISION - The implementation number of the CURRENT interface. - - AGE - The difference between the newest and oldest interfaces that - this library implements. In other words, the library implements - all the interface numbers in the range from number `CURRENT - - AGE' to `CURRENT'. - - If two libraries have identical CURRENT and AGE numbers, then the - dynamic linker chooses the library with the greater REVISION number. -</programlisting> - - <para>The <quote>-release</quote> option will produce - different results for a.out and ELF (excluding symlinks) - in only one case. An ELF library of the form - <quote>libfoo-release.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> - will have a symlink of - <quote>libfoo.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> - on an a.out platform. This is handled - automatically.</para> - - <para>The <quote>-rpath argument</quote> is the install - directory of the library being built.</para> - - <para>In the <filename>PLIST</filename>, include only the - <filename>.la</filename> file, the other files will be - added automatically.</para> - </listitem> - - <listitem> - <para>When linking shared object (<filename>.so</filename>) - files, i.e. files that are loaded via &man.dlopen.3;, NOT - shared libraries, use <quote>-module - -avoid-version</quote> to prevent them getting version - tacked on.</para> - - <para>The <filename>PLIST</filename> file gets the - <filename>foo.so</filename> entry.</para> - </listitem> - - <listitem> - <para>When linking programs that depend on these libraries - <emphasis>before</emphasis> they are installed, preface - the &man.cc.1; or &man.ld.1; line with <quote>${LIBTOOL} - --mode=link</quote>, and it will find the correct - libraries (static or shared), but please be aware that - libtool will not allow you to specify a relative path in - -L (such as <quote>-L../somelib</quote>), because it - expects you to change that argument to be the - <filename>.la</filename> file. e.g.</para> - -<programlisting> - ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib -</programlisting> + <title>Fixing problems in the <emphasis>configure</emphasis> phase</title> + + <sect2 id="fixes.libtool"> + <title>Shared libraries - libtool</title> + + <para>pkgsrc supports many different machines, with different + object formats like a.out and ELF, and varying abilities to do + shared library and dynamic loading at all. To accompany this, + varying commands and options have to be passed to the + compiler, linker, etc. to get the Right Thing, which can be + pretty annoying especially if you don't have all the machines + at your hand to test things. The + <filename role="pkg">devel/libtool</filename> pkg + can help here, as it just <quote>knows</quote> how to build + both static and dynamic libraries from a set of source files, + thus being platform-independent.</para> + + <para>Here's how to use libtool in a package in seven simple + steps:</para> + + <orderedlist> + <listitem> + <para>Add <varname>USE_LIBTOOL=yes</varname> to the package + Makefile.</para> + </listitem> - <para>should be changed to:</para> + <listitem> + <para>For library objects, use <quote>${LIBTOOL} --mode=compile + ${CC}</quote> in place of <quote>${CC}</quote>. You could even + add it to the definition of <varname>CC</varname>, if only + libraries are being built in a given Makefile. This one command + will build both PIC and non-PIC library objects, so you need not + have separate shared and non-shared library rules.</para> + </listitem> -<programlisting> - ${LIBTOOL} --mode=link ${CC} -o <replaceable>someprog</replaceable> <replaceable>../somelib/somelib.la</replaceable> -</programlisting> + <listitem> + <para>For the linking of the library, remove any + <quote>ar</quote>, <quote>ranlib</quote>, and <quote>ld + -Bshareable</quote> commands, and instead use:</para> + + <programlisting> + ${LIBTOOL} --mode=link ${CC} -o ${.TARGET:.a=.la} ${OBJS:.o=.lo} \ + -rpath ${PREFIX}/lib -version-info major:minor + </programlisting> + + <para>Note that the library is changed to have a + <filename>.la</filename> extension, and the objects are + changed to have a <filename>.lo</filename> + extension. Change <varname>OBJS</varname> as + necessary. This automatically creates all of the + <filename>.a</filename>, + <filename>.so.major.minor</filename>, and ELF symlinks (if + necessary) in the build directory. Be sure to include + <quote>-version-info</quote>, especially when major and + minor are zero, as libtool will otherwise strip off the + shared library version.</para> + + <para>From the libtool manual:</para> + + <programlisting> + So, libtool library versions are described by three integers: + + CURRENT + The most recent interface number that this library implements. + + REVISION + The implementation number of the CURRENT interface. + + AGE + The difference between the newest and oldest interfaces that + this library implements. In other words, the library implements + all the interface numbers in the range from number `CURRENT - + AGE' to `CURRENT'. + + If two libraries have identical CURRENT and AGE numbers, then the + dynamic linker chooses the library with the greater REVISION number. + </programlisting> + + <para>The <quote>-release</quote> option will produce + different results for a.out and ELF (excluding symlinks) + in only one case. An ELF library of the form + <quote>libfoo-release.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> + will have a symlink of + <quote>libfoo.so.<emphasis>x</emphasis>.<emphasis>y</emphasis></quote> + on an a.out platform. This is handled + automatically.</para> + + <para>The <quote>-rpath argument</quote> is the install + directory of the library being built.</para> + + <para>In the <filename>PLIST</filename>, include only the + <filename>.la</filename> file, the other files will be + added automatically.</para> + </listitem> - <para>and it will do the right thing with the libraries.</para> - </listitem> + <listitem> + <para>When linking shared object (<filename>.so</filename>) + files, i.e. files that are loaded via &man.dlopen.3;, NOT + shared libraries, use <quote>-module + -avoid-version</quote> to prevent them getting version + tacked on.</para> + + <para>The <filename>PLIST</filename> file gets the + <filename>foo.so</filename> entry.</para> + </listitem> - <listitem> - <para>When installing libraries, preface the &man.install.1; - or &man.cp.1; command with <quote>${LIBTOOL} - --mode=install</quote>, and change the library name to - <filename>.la</filename>. e.g.</para> + <listitem> + <para>When linking programs that depend on these libraries + <emphasis>before</emphasis> they are installed, preface + the &man.cc.1; or &man.ld.1; line with <quote>${LIBTOOL} + --mode=link</quote>, and it will find the correct + libraries (static or shared), but please be aware that + libtool will not allow you to specify a relative path in + -L (such as <quote>-L../somelib</quote>), because it + expects you to change that argument to be the + <filename>.la</filename> file. e.g.</para> + + <programlisting> + ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib + </programlisting> + + <para>should be changed to:</para> + + <programlisting> + ${LIBTOOL} --mode=link ${CC} -o <replaceable>someprog</replaceable> <replaceable>../somelib/somelib.la</replaceable> + </programlisting> + + <para>and it will do the right thing with the libraries.</para> + </listitem> -<programlisting> - ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib -</programlisting> + <listitem> + <para>When installing libraries, preface the &man.install.1; + or &man.cp.1; command with <quote>${LIBTOOL} + --mode=install</quote>, and change the library name to + <filename>.la</filename>. e.g.</para> + + <programlisting> + ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib + </programlisting> + + <para>This will install the static <filename>.a</filename>, + shared library, any needed symlinks, and run + &man.ldconfig.8;.</para> + </listitem> - <para>This will install the static <filename>.a</filename>, - shared library, any needed symlinks, and run - &man.ldconfig.8;.</para> - </listitem> + <listitem> + <para>In your <filename>PLIST</filename>, include only + the <filename>.la</filename> + file (this is a change from previous behaviour).</para> + </listitem> + </orderedlist> + </sect2> - <listitem> - <para>In your <filename>PLIST</filename>, include only - the <filename>.la</filename> - file (this is a change from previous behaviour).</para> - </listitem> - </orderedlist> - </sect2> + <sect2 id="using-libtool"> + <title>Using libtool on GNU packages that already support libtool</title> - <sect2 id="using-libtool"> - <title>Using libtool on GNU packages that already support libtool</title> + <para>Add <varname>USE_LIBTOOL=yes</varname> to the + package Makefile. This will override the package's own libtool + in most cases. For older libtool using packages, libtool is + made by ltconfig script during the do-configure step; you can + check the libtool script location by doing <command>make + configure; find work*/ -name libtool</command>.</para> - <para>Add <varname>USE_LIBTOOL=yes</varname> to the - package Makefile. This will override the package's own libtool - in most cases. For older libtool using packages, libtool is - made by ltconfig script during the do-configure step; you can - check the libtool script location by doing <command>make - configure; find work*/ -name libtool</command>.</para> + <para><varname>LIBTOOL_OVERRIDE</varname> specifies which libtool + scripts, relative to <varname>WRKSRC</varname>, to override. By + default, it is set to <quote>libtool */libtool + */*/libtool</quote>. If this does not match the location of the + package's libtool script(s), set it as appropriate.</para> - <para><varname>LIBTOOL_OVERRIDE</varname> specifies which libtool - scripts, relative to <varname>WRKSRC</varname>, to override. By - default, it is set to <quote>libtool */libtool - */*/libtool</quote>. If this does not match the location of the - package's libtool script(s), set it as appropriate.</para> + <para>If you do not need <filename>*.a</filename> static + libraries built and installed, then use + <varname>SHLIBTOOL_OVERRIDE</varname> instead.</para> - <para>If you do not need <filename>*.a</filename> static - libraries built and installed, then use - <varname>SHLIBTOOL_OVERRIDE</varname> instead.</para> + <para>If your package makes use of the platform-independent library + for loading dynamic shared objects, that comes with libtool + (libltdl), you should include devel/libltdl/buildlink3.mk.</para> - <para>If your package makes use of the platform-independent library - for loading dynamic shared objects, that comes with libtool - (libltdl), you should include devel/libltdl/buildlink3.mk.</para> + <para>Some packages use libtool incorrectly so that the package + may not work or build in some circumstances. Some of the more + common errors are:</para> - <para>Some packages use libtool incorrectly so that the package may not work or - build in some circumstances. Some of the more common errors are:</para> + <itemizedlist> + <listitem> + <para>The inclusion of a shared object (-module) as a dependent library in an + executable or library. This in itself isn't a problem if one of two things + has been done:</para> + + <orderedlist> + <listitem> + <para>The shared object is named correctly, i.e. + <filename>libfoo.la</filename>, not + <filename>foo.la</filename></para> + </listitem> + + <listitem> + <para>The -dlopen option is used when linking an executable.</para> + </listitem> + </orderedlist> + </listitem> - <itemizedlist> - <listitem> - <para>The inclusion of a shared object (-module) as a dependent library in an - executable or library. This in itself isn't a problem if one of two things - has been done:</para> - - <orderedlist> - <listitem> - <para>The shared object is named correctly, i.e. - <filename>libfoo.la</filename>, not - <filename>foo.la</filename></para> - </listitem> - - <listitem> - <para>The -dlopen option is used when linking an executable.</para> - </listitem> - </orderedlist> - </listitem> + <listitem> + <para>The use of libltdl without the correct calls to initialisation routines. + The function lt_dlinit() should be called and the macro + <varname>LTDL_SET_PRELOADED_SYMBOLS</varname> included in + executables.</para> + </listitem> + </itemizedlist> + </sect2> - <listitem> - <para>The use of libltdl without the correct calls to initialisation routines. - The function lt_dlinit() should be called and the macro - <varname>LTDL_SET_PRELOADED_SYMBOLS</varname> included in - executables.</para> - </listitem> - </itemizedlist> - </sect2> + <sect2 id="autoconf-automake"> + <title>GNU Autoconf/Automake</title> - <sect2 id="autoconf-automake"> - <title>GNU Autoconf/Automake</title> + <para>If a package needs GNU autoconf or automake to be executed + to regenerate the configure script and Makefile.in makefile + templates, then they should be executed in a pre-configure + target.</para> - <para>If a package needs GNU autoconf or automake to be executed - to regenerate the configure script and Makefile.in makefile - templates, then they should be executed in a pre-configure - target.</para> + <para>For packages that need only autoconf:</para> - <para>For packages that need only autoconf:</para> + <programlisting> + AUTOCONF_REQD= 2.50 # if default version is not good enough + USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13 + ... -<programlisting> - AUTOCONF_REQD= 2.50 # if default version is not good enough - USE_TOOLS+= autoconf # use "autoconf213" for autoconf-2.13 - ... + pre-configure: + cd ${WRKSRC}; autoconf - pre-configure: - cd ${WRKSRC}; autoconf + ... + </programlisting> - ... -</programlisting> + <para>and for packages that need automake and autoconf:</para> - <para>and for packages that need automake and autoconf:</para> + <programlisting> + AUTOMAKE_REQD= 1.7.1 # if default version is not good enough + USE_TOOLS+= automake # use "automake14" for automake-1.4 + ... -<programlisting> - AUTOMAKE_REQD= 1.7.1 # if default version is not good enough - USE_TOOLS+= automake # use "automake14" for automake-1.4 - ... + pre-configure: + cd ${WRKSRC}; \ + aclocal; autoheader; \ + automake -a --foreign -i; autoconf - pre-configure: - cd ${WRKSRC}; \ - aclocal; autoheader; \ - automake -a --foreign -i; autoconf + ... + </programlisting> - ... -</programlisting> + <para>Packages which use GNU Automake will almost certainly + require GNU Make.</para> - <para>Packages which use GNU Automake will almost certainly - require GNU Make.</para> + <para>There are times when the configure process makes + additional changes to the generated files, which then causes + the build process to try to re-execute the automake sequence. + This is prevented by touching various files in the configure + stage. If this causes problems with your package you can set + <varname>AUTOMAKE_OVERRIDE=NO</varname> in the package + Makefile.</para> + </sect2> +</sect1> - <para>There are times when the configure process makes - additional changes to the generated files, which then causes - the build process to try to re-execute the automake sequence. - This is prevented by touching various files in the configure - stage. If this causes problems with your package you can set - <varname>AUTOMAKE_OVERRIDE=NO</varname> in the package - Makefile.</para> - </sect2> - </sect1> +<sect1 id="programming-languages"> + <title>Programming languages</title> + + <sect2 id="basic-programming-languages"> + <title>C, C++, and Fortran</title> + + <para>Compilers for the C, C++, and Fortran languages comes with + the NetBSD base system. By default, pkgsrc assumes that a package + is written in C and will hide all other compilers (via the wrapper + framework, see <xref linkend="buildlink" />).</para> + + <para>To declare which language's compiler a package needs, set + the <varname>USE_LANGUAGES</varname> variable. Allowed values + currently are <quote>c</quote>, <quote>c++</quote>, and + <quote>fortran</quote> (and any combination). The default is + <quote>c</quote>. Packages using GNU configure scripts, even if + written in C++, usually need a C compiler for the configure + phase.</para> + </sect2> + + <sect2 id="java-programming-language"> + <title>Java</title> + + <para>If a program is written in Java, use the Java framework in + pkgsrc. The package must include + <filename>../../mk/java-vm.mk</filename>. This Makefile fragment + provides the following variables:</para> + + <itemizedlist> + <listitem><para><varname>USE_JAVA</varname> defines if a build + dependency on the JDK is added. If + <varname>USE_JAVA</varname> is set to <quote>run</quote>, then + there is only a runtime dependency on the JDK. The default is + <quote>yes</quote>, which also adds a build dependency on the + JDK.</para></listitem> + + <listitem><para>Set <varname>USE_JAVA2</varname> to declare that + a package needs a Java2 implementation. The supported values + are <quote>yes</quote>, <quote>1.4</quote>, and + <quote>1.5</quote>. <quote>yes</quote> accepts any Java2 + implementation, <quote>1.4</quote> insists on versions 1.4 or + above, and <quote>1.5</quote> only accepts versions 1.5 or + above. This variable is not set by default.</para></listitem> + <!-- XXX: describe PKG_JVM_DEFAULT and PKG_JVMS_ACCEPTED, but + not here --> + </itemizedlist> + </sect2> + + <sect2 id="perl-scripts"> + <title>Packages containing perl scripts</title> + + <para>If your package contains interpreted perl scripts, add + <quote>perl</quote> to the <varname>USE_TOOLS</varname> variable + and set <varname>REPLACE_PERL</varname> to ensure that the proper + interpreter path is set. <varname>REPLACE_PERL</varname> should + contain a list of scripts, relative to <varname>WRKSRC</varname>, + that you want adjusted. Every occurrence of + <filename>*/bin/perl</filename> will be replaced with the full + path to the perl executable.</para> + + <para>If a particular version of perl is needed, set the + <varname>PERL5_REQD</varname> variable to the version number. The + default is <quote>5.0</quote>.</para> + + <para>See <xref linkend="perl-modules" /> for information + about handling perl modules.</para> + </sect2> + + <sect2 id="other-programming-languages"> + <title>Other programming languages</title> + + <para>Currently, there is no special handling for other languages + in pkgsrc. If a compiler package provides a + <filename>buildlink3.mk</filename> file, include that, otherwise + just add a (build) dependency on the appropriate compiler + package.</para> + </sect2> +</sect1> <sect1 id="fixes.build"> -<title>Fixing problems in the <emphasis>build</emphasis> phase</title> + <title>Fixing problems in the <emphasis>build</emphasis> phase</title> <para>The most common failures when building a package are that some platforms do not provide certain header files, functions or @@ -1031,16 +1115,16 @@ Changes to the PLIST <title>How to handle compiler bugs</title> <para>Some source files trigger bugs in the compiler, based on - combinations of compiler version and architecture and almost - always relation to optimisation being enabled. Common symptoms - are gcc internal errors or never finishing compiling a + combinations of compiler version and architecture and almost + always relation to optimisation being enabled. Common symptoms + are gcc internal errors or never finishing compiling a file.</para> <para>Typically, a workaround involves testing the <varname>MACHINE_ARCH</varname> and compiler version, disabling optimisation for that combination of file, <varname>MACHINE_ARCH</varname> and compiler, and documenting it - in <filename>pkgsrc/doc/HACKS</filename>. See that file for a + in <filename>pkgsrc/doc/HACKS</filename>. See that file for a number of examples.</para> </sect2> @@ -1052,614 +1136,612 @@ Changes to the PLIST link to a shared library it needs. The following functions are known to cause this error message over and over.</para> - <informaltable id="undefined-reference-functions"> - <tgroup cols="3"> + <informaltable id="undefined-reference-functions"> + <tgroup cols="3"> <thead><row><entry>Function</entry><entry>Library</entry><entry>Affected platforms</entry></row></thead> <tbody> - <row><entry>accept, bind, connect</entry><entry>-lsocket</entry><entry>Solaris</entry></row> - <row><entry>crypt</entry><entry>-lcrypt</entry><entry>DragonFly, NetBSD</entry></row> - <row><entry>dlopen, dlsym</entry><entry>-ldl</entry><entry>Linux</entry></row> - <row><entry>gethost*</entry><entry>-lnsl</entry><entry>Solaris</entry></row> - <row><entry>inet_aton</entry><entry>-lresolv</entry><entry>Solaris</entry></row> - <row><entry>nanosleep, sem_*, timer_*</entry><entry>-lrt</entry><entry>Solaris</entry></row> - <row><entry>openpty</entry><entry>-lutil</entry><entry>Linux</entry></row> + <row><entry>accept, bind, connect</entry><entry>-lsocket</entry><entry>Solaris</entry></row> + <row><entry>crypt</entry><entry>-lcrypt</entry><entry>DragonFly, NetBSD</entry></row> + <row><entry>dlopen, dlsym</entry><entry>-ldl</entry><entry>Linux</entry></row> + <row><entry>gethost*</entry><entry>-lnsl</entry><entry>Solaris</entry></row> + <row><entry>inet_aton</entry><entry>-lresolv</entry><entry>Solaris</entry></row> + <row><entry>nanosleep, sem_*, timer_*</entry><entry>-lrt</entry><entry>Solaris</entry></row> + <row><entry>openpty</entry><entry>-lutil</entry><entry>Linux</entry></row> </tbody> - </tgroup> - </informaltable> - - <para>To fix these linker errors, it is often sufficient to say - <literal>LIBS.<replaceable>OperatingSystem</replaceable>+= - -l<replaceable>foo</replaceable></literal> to the package - <filename>Makefile</filename> and then say <command>bmake clean; - bmake</command>.</para> - -</sect2> + </tgroup> + </informaltable> + + <para>To fix these linker errors, it is often sufficient to say + <literal>LIBS.<replaceable>OperatingSystem</replaceable>+= + -l<replaceable>foo</replaceable></literal> to the package + <filename>Makefile</filename> and then say <command>bmake clean; + bmake</command>.</para> + + </sect2> + + <sect2 id="out-of-memory"> + <title>Running out of memory</title> + + <para>Sometimes packages fail to build because the compiler runs + into an operating system specific soft limit. With the + <variable>UNLIMIT_RESOURCES</variable> variable pkgsrc can be told + to unlimit the resources. Currently, the allowed values are + <quote>datasize</quote> and <quote>stacksize</quote> (or both). + Setting this variable is similar to running the shell builtin + <command>ulimit</command> command to raise the maximum data + segment size or maximum stack size of a process, respectively, to + their hard limits.</para> + </sect2> </sect1> <sect1 id="fixes.install"> -<title>Fixing problems in the <emphasis>install</emphasis> phase</title> - -<sect2 id="install-scripts"> -<title>Creating needed directories</title> - - <para>The BSD-compatible <command>install</command> supplied - with some operating systems cannot create more than one - directory at a time. As such, you should call - <literal>${INSTALL_*_DIR}</literal> like this:</para> - -<programlisting> - ${INSTALL_DATA_DIR} ${PREFIX}/dir1 - ${INSTALL_DATA_DIR} ${PREFIX}/dir2 -</programlisting> - - <para>You can also just append <quote><literal>dir1 - dir2</literal></quote> to the - <varname>INSTALLATION_DIRS</varname> variable, which will - automatically do the right thing.</para> - -</sect2> -<sect2 id="where-to-install-documentation"> -<title>Where to install documentation</title> - - <para>In general, documentation should be installed into - <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or - <filename>${PREFIX}/share/doc/${PKGNAME}</filename> (the - latter includes the version number of the package).</para> - - <para>Many modern packages using GNU autoconf allow to set the - directory where HTML documentation is installed with the - <quote>--with-html-dir</quote> option. Sometimes using this - flag is needed because otherwise the documentation ends up in - <filename>${PREFIX}/share/doc/html</filename> or other - places.</para> - - <para>An exception to the above is that library API - documentation generated with the <filename - role="pkg">textproc/gtk-doc</filename> tools, for use by - special browsers (devhelp) should be left at their default - location, which is - <filename>${PREFIX}/share/gtk-doc</filename>. Such - documentation can be recognized from files ending in - <filename>.devhelp</filename> or - <filename>.devhelp2</filename>. (It is also acceptable to - install such files in - <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or - <filename>${PREFIX}/share/doc/${PKGNAME}</filename>; the - <filename>.devhelp*</filename> file must be directly in that - directory then, no additional - subdirectory level is allowed in this case. This is usually - achieved by using - <quote>--with-html-dir=${PREFIX}/share/doc</quote>. - <filename>${PREFIX}/share/gtk-doc</filename> is preferred - though.)</para> - -</sect2> - - <sect2 id="installing-score-files"> - <title>Installing score files</title> - - <para>Certain packages, most of them in the games category, install - a score file that allows all users on the system to record their - highscores. In order for this to work, the binaries need to be - installed setgid and the score files owned by the appropriate - group and/or owner (traditionally the "games" user/group). The - following variables, documented in more detail in - <filename>mk/defaults/mk.conf</filename>, control this - behaviour: <varname>SETGIDGAME</varname>, - <varname>GAMEDATAMODE</varname>, <varname>GAMEGRP</varname>, - <varname>GAMEMODE</varname>, <varname>GAMEOWN</varname>.</para> - - <para>Note that per default, setgid installation of games is - disabled; setting <varname>SETGIDGAME=YES</varname> will set all - the other variables accordingly.</para> - - <para>A package should therefor never hard code file ownership or - access permissions but rely on <varname>INSTALL_GAME</varname> and - <varname>INSTALL_GAME_DATA</varname> to set these - correctly.</para> - </sect2> - - - <sect2 id="perl-scripts"> - <title>Packages containing perl scripts</title> - - <para> - If your package contains interpreted perl scripts, set - <varname>REPLACE_PERL</varname> to ensure that the proper - interpreter path is set. <varname>REPLACE_PERL</varname> should - contain a list of scripts, relative to - <varname>WRKSRC</varname>, that you want adjusted.</para> - </sect2> - - - <sect2 id="hardcoded-paths"> - <title>Packages with hardcoded paths to other interpreters</title> - - <para> - Your package may also contain scripts with hardcoded paths to - other interpreters besides (or as well as) perl. To correct the - full pathname to the script interpreter, you need to set the - following definitions in your <filename>Makefile</filename> (we - shall use <command>tclsh</command> in this example):</para> - -<programlisting> - REPLACE_INTERPRETER+= tcl - REPLACE.tcl.old= .*/bin/tclsh - REPLACE.tcl.new= ${PREFIX}/bin/tclsh - REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed, - # relative to ${WRKSRC}, just as in REPLACE_PERL -</programlisting> - - <note><para>Before March 2006, these variables were called - <varname>_REPLACE.*</varname> and - <varname>_REPLACE_FILES.*</varname>.</para></note> - - </sect2> - - - <sect2 id="perl-modules"> - <title>Packages installing perl modules</title> - - <para>Makefiles of packages providing perl5 modules should include - the Makefile fragment - <filename>../../lang/perl5/module.mk</filename>. It provides a - <command>do-configure</command> target for the standard perl - configuration for such modules as well as various hooks to tune - this configuration. See comments in this file for - details.</para> - - <para>Perl5 modules will install into different places depending - on the version of perl used during the build process. To - address this, pkgsrc will append lines to the - <filename>PLIST</filename> corresponding to the files listed in - the installed <filename>.packlist</filename> file generated by - most perl5 modules. This is invoked by defining - <varname>PERL5_PACKLIST</varname> to a space-separated list of - paths to packlist files, e.g.:</para> - -<programlisting> - PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist -</programlisting> - - <para>The variables <varname>PERL5_SITELIB</varname>, - <varname>PERL5_SITEARCH</varname>, and - <varname>PERL5_ARCHLIB</varname> represent the three locations - in which perl5 modules may be installed, and may be used by - perl5 packages that don't have a packlist. These three - variables are also substituted for in the - <filename>PLIST</filename>.</para> - </sect2> - - - <sect2 id="faq.info-files"> - <title>Packages installing info files</title> - - <para>Some packages install info files or use the - <quote>makeinfo</quote> or <quote>install-info</quote> - commands. <varname>INFO_FILES</varname> should be defined in - the package Makefile so that <filename>INSTALL</filename> and - <filename>DEINSTALL</filename> scripts will be generated to - handle registration of the info files in the Info directory - file. The <quote>install-info</quote> command used for the info - files registration is either provided by the system, or by a - special purpose package automatically added as dependency if - needed.</para> - - <para><varname>PKGINFODIR</varname> is the directory under - <filename>${PREFIX}</filename> where info files are primarily - located. <varname>PKGINFODIR</varname> defaults to - <quote>info</quote> and can be overridden by the user.</para> - - <para>The info files for the package should be listed in the - package <filename>PLIST</filename>; however any split info files - need not be listed.</para> - - <para>A package which needs the <quote>makeinfo</quote> command - at build time must add <quote>makeinfo</quote> to - <varname>USE_TOOLS</varname> in its Makefile. If a minimum - version of the <quote>makeinfo</quote> command is needed it - should be noted with the <varname>TEXINFO_REQD</varname> - variable in the package <filename>Makefile</filename>. By - default, a minimum version of 3.12 is required. If the system - does not provide a <command>makeinfo</command> command or if it - does not match the required minimum, a build dependency on the - <filename role="pkg">devel/gtexinfo</filename> package will - be added automatically.</para> - - <para>The build and installation process of the software provided - by the package should not use the - <command>install-info</command> command as the registration of - info files is the task of the package - <filename>INSTALL</filename> script, and it must use the - appropriate <command>makeinfo</command> command.</para> - - <para>To achieve this goal, the pkgsrc infrastructure creates - overriding scripts for the <command>install-info</command> and - <command>makeinfo</command> commands in a directory listed early - in <varname>PATH</varname>.</para> - - <para>The script overriding <command>install-info</command> has - no effect except the logging of a message. The script overriding - <command>makeinfo</command> logs a message and according to the - value of <varname>TEXINFO_REQD</varname> either runs the appropriate - <command>makeinfo</command> command or exit on error.</para> - </sect2> - - <sect2 id="manpages"> - <title>Packages installing man pages</title> - - <para>All packages that install manual pages should install them - into the same directory, so that there is one common place to - look for them. In pkgsrc, this place is - <literal>${PREFIX}/${PKGMANDIR}</literal>, and this expression - should be used in packages. The default for - <varname>PKGMANDIR</varname> is - <quote><filename>man</filename></quote>. Another often-used - value is <quote><filename>share/man</filename></quote>.</para> - - <note><para>The support for a custom - <varname>PKGMANDIR</varname> is far from complete.</para></note> - - <para>The <filename>PLIST</filename> files can just use - <filename>man/</filename> as the top level directory for the man - page file entries, and the pkgsrc framework will convert as - needed. In all other places, the correct - <varname>PKGMANDIR</varname> must be used.</para> - - <para> Packages that are - configured with <varname>GNU_CONFIGURE</varname> set as - <quote>yes</quote>, by default will use the - <filename>./configure</filename> - --mandir switch to set where the man pages should be installed. - The path is <varname>GNU_CONFIGURE_MANDIR</varname> which defaults - to <varname>${PREFIX}/${PKGMANDIR}</varname>. - </para> - - <para> - Packages that use <varname>GNU_CONFIGURE</varname> but do not - use --mandir, can set <varname>CONFIGURE_HAS_MANDIR</varname> - to <quote>no</quote>. - Or if the <filename>./configure</filename> script uses - a non-standard use of --mandir, you can set - <varname>GNU_CONFIGURE_MANDIR</varname> as needed. - </para> - - <para>See <xref linkend="manpage-compression"/> for - information on installation of compressed manual pages. - </para> - - </sect2> - - <sect2 id="gconf2-data-files"> - <title>Packages installing GConf2 data files</title> - - <para> - If a package installs <filename>.schemas</filename> or - <filename>.entries</filename> files, used by GConf2, - you need to take some extra steps to make sure they get registered - in the database: -</para> - - <orderedlist> + <title>Fixing problems in the <emphasis>install</emphasis> phase</title> + + <sect2 id="install-scripts"> + <title>Creating needed directories</title> + + <para>The BSD-compatible <command>install</command> supplied + with some operating systems cannot create more than one + directory at a time. As such, you should call + <literal>${INSTALL_*_DIR}</literal> like this:</para> + + <programlisting> + ${INSTALL_DATA_DIR} ${PREFIX}/dir1 + ${INSTALL_DATA_DIR} ${PREFIX}/dir2 + </programlisting> + + <para>You can also just append <quote><literal>dir1 + dir2</literal></quote> to the + <varname>INSTALLATION_DIRS</varname> variable, which will + automatically do the right thing.</para> + + </sect2> + <sect2 id="where-to-install-documentation"> + <title>Where to install documentation</title> + + <para>In general, documentation should be installed into + <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or + <filename>${PREFIX}/share/doc/${PKGNAME}</filename> (the latter + includes the version number of the package).</para> + + <para>Many modern packages using GNU autoconf allow to set the + directory where HTML documentation is installed with the + <quote>--with-html-dir</quote> option. Sometimes using this flag + is needed because otherwise the documentation ends up in + <filename>${PREFIX}/share/doc/html</filename> or other + places.</para> + + <para>An exception to the above is that library API documentation + generated with the <filename + role="pkg">textproc/gtk-doc</filename> tools, for use by special + browsers (devhelp) should be left at their default location, which + is <filename>${PREFIX}/share/gtk-doc</filename>. Such + documentation can be recognized from files ending in + <filename>.devhelp</filename> or <filename>.devhelp2</filename>. + (It is also acceptable to install such files in + <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or + <filename>${PREFIX}/share/doc/${PKGNAME}</filename>; the + <filename>.devhelp*</filename> file must be directly in that + directory then, no additional subdirectory level is allowed in + this case. This is usually achieved by using + <quote>--with-html-dir=${PREFIX}/share/doc</quote>. + <filename>${PREFIX}/share/gtk-doc</filename> is preferred + though.)</para> + + </sect2> + + <sect2 id="installing-score-files"> + <title>Installing score files</title> + + <para>Certain packages, most of them in the games category, install + a score file that allows all users on the system to record their + highscores. In order for this to work, the binaries need to be + installed setgid and the score files owned by the appropriate + group and/or owner (traditionally the "games" user/group). The + following variables, documented in more detail in + <filename>mk/defaults/mk.conf</filename>, control this + behaviour: <varname>SETGIDGAME</varname>, + <varname>GAMEDATAMODE</varname>, <varname>GAMEGRP</varname>, + <varname>GAMEMODE</varname>, <varname>GAMEOWN</varname>.</para> + + <para>Note that per default, setgid installation of games is + disabled; setting <varname>SETGIDGAME=YES</varname> will set all + the other variables accordingly.</para> + + <para>A package should therefor never hard code file ownership or + access permissions but rely on <varname>INSTALL_GAME</varname> and + <varname>INSTALL_GAME_DATA</varname> to set these + correctly.</para> + </sect2> + + + <sect2 id="hardcoded-paths"> + <title>Packages with hardcoded paths to other interpreters</title> + + <para>Your package may also contain scripts with hardcoded paths to + other interpreters besides (or as well as) perl. To correct the + full pathname to the script interpreter, you need to set the + following definitions in your <filename>Makefile</filename> (we + shall use <command>tclsh</command> in this example):</para> + + <programlisting> + REPLACE_INTERPRETER+= tcl + REPLACE.tcl.old= .*/bin/tclsh + REPLACE.tcl.new= ${PREFIX}/bin/tclsh + REPLACE_FILES.tcl= # list of tcl scripts which need to be fixed, + # relative to ${WRKSRC}, just as in REPLACE_PERL + </programlisting> + + <note><para>Before March 2006, these variables were called + <varname>_REPLACE.*</varname> and + <varname>_REPLACE_FILES.*</varname>.</para></note> + + </sect2> + + + <sect2 id="perl-modules"> + <title>Packages installing perl modules</title> + + <para>Makefiles of packages providing perl5 modules should include + the Makefile fragment + <filename>../../lang/perl5/module.mk</filename>. It provides a + <command>do-configure</command> target for the standard perl + configuration for such modules as well as various hooks to tune + this configuration. See comments in this file for + details.</para> + + <para>Perl5 modules will install into different places depending + on the version of perl used during the build process. To + address this, pkgsrc will append lines to the + <filename>PLIST</filename> corresponding to the files listed in + the installed <filename>.packlist</filename> file generated by + most perl5 modules. This is invoked by defining + <varname>PERL5_PACKLIST</varname> to a space-separated list of + paths to packlist files, e.g.:</para> + + <programlisting> + PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist + </programlisting> + + <para>The variables <varname>PERL5_SITELIB</varname>, + <varname>PERL5_SITEARCH</varname>, and + <varname>PERL5_ARCHLIB</varname> represent the three locations + in which perl5 modules may be installed, and may be used by + perl5 packages that don't have a packlist. These three + variables are also substituted for in the + <filename>PLIST</filename>.</para> + </sect2> + + + <sect2 id="faq.info-files"> + <title>Packages installing info files</title> + + <para>Some packages install info files or use the + <quote>makeinfo</quote> or <quote>install-info</quote> + commands. <varname>INFO_FILES</varname> should be defined in + the package Makefile so that <filename>INSTALL</filename> and + <filename>DEINSTALL</filename> scripts will be generated to + handle registration of the info files in the Info directory + file. The <quote>install-info</quote> command used for the info + files registration is either provided by the system, or by a + special purpose package automatically added as dependency if + needed.</para> + + <para><varname>PKGINFODIR</varname> is the directory under + <filename>${PREFIX}</filename> where info files are primarily + located. <varname>PKGINFODIR</varname> defaults to + <quote>info</quote> and can be overridden by the user.</para> + + <para>The info files for the package should be listed in the + package <filename>PLIST</filename>; however any split info files + need not be listed.</para> + + <para>A package which needs the <quote>makeinfo</quote> command + at build time must add <quote>makeinfo</quote> to + <varname>USE_TOOLS</varname> in its Makefile. If a minimum + version of the <quote>makeinfo</quote> command is needed it + should be noted with the <varname>TEXINFO_REQD</varname> + variable in the package <filename>Makefile</filename>. By + default, a minimum version of 3.12 is required. If the system + does not provide a <command>makeinfo</command> command or if it + does not match the required minimum, a build dependency on the + <filename role="pkg">devel/gtexinfo</filename> package will + be added automatically.</para> + + <para>The build and installation process of the software provided + by the package should not use the + <command>install-info</command> command as the registration of + info files is the task of the package + <filename>INSTALL</filename> script, and it must use the + appropriate <command>makeinfo</command> command.</para> + + <para>To achieve this goal, the pkgsrc infrastructure creates + overriding scripts for the <command>install-info</command> and + <command>makeinfo</command> commands in a directory listed early + in <varname>PATH</varname>.</para> + + <para>The script overriding <command>install-info</command> has + no effect except the logging of a message. The script overriding + <command>makeinfo</command> logs a message and according to the + value of <varname>TEXINFO_REQD</varname> either runs the appropriate + <command>makeinfo</command> command or exit on error.</para> + </sect2> + + <sect2 id="manpages"> + <title>Packages installing man pages</title> + + <para>All packages that install manual pages should install them + into the same directory, so that there is one common place to look + for them. In pkgsrc, this place is + <literal>${PREFIX}/${PKGMANDIR}</literal>, and this expression + should be used in packages. The default for + <varname>PKGMANDIR</varname> is + <quote><filename>man</filename></quote>. Another often-used value + is <quote><filename>share/man</filename></quote>.</para> + + <note><para>The support for a custom <varname>PKGMANDIR</varname> + is far from complete.</para></note> + + <para>The <filename>PLIST</filename> files can just use + <filename>man/</filename> as the top level directory for the man + page file entries, and the pkgsrc framework will convert as + needed. In all other places, the correct + <varname>PKGMANDIR</varname> must be used.</para> + + <para>Packages that are + configured with <varname>GNU_CONFIGURE</varname> set as + <quote>yes</quote>, by default will use the + <filename>./configure</filename> + --mandir switch to set where the man pages should be installed. + The path is <varname>GNU_CONFIGURE_MANDIR</varname> which defaults + to <varname>${PREFIX}/${PKGMANDIR}</varname>.</para> + + <para>Packages that use <varname>GNU_CONFIGURE</varname> but do not + use --mandir, can set <varname>CONFIGURE_HAS_MANDIR</varname> + to <quote>no</quote>. + Or if the <filename>./configure</filename> script uses + a non-standard use of --mandir, you can set + <varname>GNU_CONFIGURE_MANDIR</varname> as needed.</para> + + <para>See <xref linkend="manpage-compression"/> for + information on installation of compressed manual pages.</para> + + </sect2> + + <sect2 id="gconf2-data-files"> + <title>Packages installing GConf2 data files</title> + + <para>If a package installs <filename>.schemas</filename> or + <filename>.entries</filename> files, used by GConf2, + you need to take some extra steps to make sure they get registered + in the database:</para> + + <orderedlist> <listitem> - <para>Include <filename>../../devel/GConf2/schemas.mk</filename> - instead of its <filename>buildlink3.mk</filename> file. This - takes care of rebuilding the GConf2 database at installation and - deinstallation time, and tells the package where to install - GConf2 data files using some standard configure arguments. It - also disallows any access to the database directly from the - package.</para> + <para>Include <filename>../../devel/GConf2/schemas.mk</filename> + instead of its <filename>buildlink3.mk</filename> file. This + takes care of rebuilding the GConf2 database at installation and + deinstallation time, and tells the package where to install + GConf2 data files using some standard configure arguments. It + also disallows any access to the database directly from the + package.</para> </listitem> <listitem> - <para>Ensure that the package installs its - <filename>.schemas</filename> files under - <filename>${PREFIX}/share/gconf/schemas</filename>. If they get - installed under <filename>${PREFIX}/etc</filename>, you will - need to manually patch the package.</para> + <para>Ensure that the package installs its + <filename>.schemas</filename> files under + <filename>${PREFIX}/share/gconf/schemas</filename>. If they get + installed under <filename>${PREFIX}/etc</filename>, you will + need to manually patch the package.</para> </listitem> <listitem> - <para>Check the PLIST and remove any entries under the etc/gconf - directory, as they will be handled automatically. See - <xref linkend="faq.conf"/> for more information.</para> + <para>Check the PLIST and remove any entries under the etc/gconf + directory, as they will be handled automatically. See + <xref linkend="faq.conf"/> for more information.</para> </listitem> <listitem> - <para>Define the <varname>GCONF2_SCHEMAS</varname> variable in - your <filename>Makefile</filename> with a list of all - <filename>.schemas</filename> files installed by the package, if - any. Names must not contain any directories in them.</para> + <para>Define the <varname>GCONF2_SCHEMAS</varname> variable in + your <filename>Makefile</filename> with a list of all + <filename>.schemas</filename> files installed by the package, if + any. Names must not contain any directories in them.</para> </listitem> <listitem> - <para>Define the <varname>GCONF2_ENTRIES</varname> variable in - your <filename>Makefile</filename> with a - list of all <filename>.entries</filename> files installed by the - package, if any. Names must not contain any directories in - them.</para> + <para>Define the <varname>GCONF2_ENTRIES</varname> variable in + your <filename>Makefile</filename> with a + list of all <filename>.entries</filename> files installed by the + package, if any. Names must not contain any directories in + them.</para> </listitem> - </orderedlist> - </sect2> + </orderedlist> + </sect2> - <sect2 id="scrollkeeper-data-files"> - <title>Packages installing scrollkeeper data files</title> + <sect2 id="scrollkeeper-data-files"> + <title>Packages installing scrollkeeper data files</title> - <para> - If a package installs <filename>.omf</filename> files, used by - scrollkeeper, you need to take some extra steps to make sure they - get registered in the database: -</para> + <para>If a package installs <filename>.omf</filename> files, used by + scrollkeeper, you need to take some extra steps to make sure they + get registered in the database:</para> - <orderedlist> - <listitem> - <para>Include - <filename>../../textproc/scrollkeeper/omf.mk</filename> - instead of its <filename>buildlink3.mk</filename> file. This - takes care of rebuilding the scrollkeeper database at - installation and deinstallation time, and disallows any access - to it directly from the package. -</para> - </listitem> + <orderedlist> + <listitem> + <para>Include + <filename>../../textproc/scrollkeeper/omf.mk</filename> + instead of its <filename>buildlink3.mk</filename> file. This + takes care of rebuilding the scrollkeeper database at + installation and deinstallation time, and disallows any access + to it directly from the package.</para> + </listitem> - <listitem> - <para>Check the PLIST and remove any entries under the - <filename>libdata/scrollkeeper</filename> directory, as they - will be handled automatically.</para> - </listitem> + <listitem> + <para>Check the PLIST and remove any entries under the + <filename>libdata/scrollkeeper</filename> directory, as they + will be handled automatically.</para> + </listitem> - <listitem> - <para>Remove the <filename>share/omf</filename> directory from - the PLIST. It will be handled by scrollkeeper.</para> - </listitem> - </orderedlist> - </sect2> + <listitem> + <para>Remove the <filename>share/omf</filename> directory from + the PLIST. It will be handled by scrollkeeper.</para> + </listitem> + </orderedlist> + </sect2> - <sect2 id="x11-fonts"> - <title>Packages installing X11 fonts</title> + <sect2 id="x11-fonts"> + <title>Packages installing X11 fonts</title> - <para>If a package installs font files, you will need to rebuild - the fonts database in the directory where they get installed at - installation and deinstallation time. This can be automatically - done by using the pkginstall framework.</para> + <para>If a package installs font files, you will need to rebuild + the fonts database in the directory where they get installed at + installation and deinstallation time. This can be automatically + done by using the pkginstall framework.</para> - <para>You can list the directories where fonts are installed in the - <varname>FONTS_DIRS.<replaceable>type</replaceable></varname> - variables, where <replaceable>type</replaceable> can be one of - <quote>ttf</quote>, <quote>type1</quote> or <quote>x11</quote>. - Also make sure that the database file - <filename>fonts.dir</filename> is not listed in the PLIST.</para> + <para>You can list the directories where fonts are installed in the + <varname>FONTS_DIRS.<replaceable>type</replaceable></varname> + variables, where <replaceable>type</replaceable> can be one of + <quote>ttf</quote>, <quote>type1</quote> or <quote>x11</quote>. + Also make sure that the database file + <filename>fonts.dir</filename> is not listed in the PLIST.</para> - <para>Note that you should not create new directories for fonts; - instead use the standard ones to avoid that the user needs to - manually configure his X server to find them.</para> - </sect2> + <para>Note that you should not create new directories for fonts; + instead use the standard ones to avoid that the user needs to + manually configure his X server to find them.</para> + </sect2> - <sect2 id="gtk2-modules"> - <title>Packages installing GTK2 modules</title> + <sect2 id="gtk2-modules"> + <title>Packages installing GTK2 modules</title> - <para>If a package installs GTK2 immodules or loaders, you need to - take some extra steps to get them registered in the GTK2 database - properly:</para> + <para>If a package installs GTK2 immodules or loaders, you need to + take some extra steps to get them registered in the GTK2 database + properly:</para> - <orderedlist> - <listitem> <para>Include - <filename>../../x11/gtk2/modules.mk</filename> instead of its - <filename>buildlink3.mk</filename> file. This takes care of - rebuilding the database at installation and deinstallation time. -</para> + <orderedlist> + <listitem><para>Include + <filename>../../x11/gtk2/modules.mk</filename> instead of its + <filename>buildlink3.mk</filename> file. This takes care of + rebuilding the database at installation and deinstallation time.</para> </listitem> - <listitem> <para> - Set <varname>GTK2_IMMODULES=YES</varname> if - your package installs GTK2 immodules.</para> + <listitem><para>Set <varname>GTK2_IMMODULES=YES</varname> if + your package installs GTK2 immodules.</para> </listitem> - <listitem> <para> - Set <varname>GTK2_LOADERS=YES</varname> if your package installs - GTK2 loaders.</para> + <listitem><para>Set <varname>GTK2_LOADERS=YES</varname> if your package installs + GTK2 loaders.</para> </listitem> - <listitem> <para> - Patch the package to not touch any of the GTK2 databases directly. - These are: + <listitem><para>Patch the package to not touch any of the GTK2 + databases directly. These are:</para> - <itemizedlist> - <listitem><para><filename>libdata/gtk-2.0/gdk-pixbuf.loaders</filename></para></listitem> - <listitem><para><filename>libdata/gtk-2.0/gtk.immodules</filename></para></listitem> - </itemizedlist> -</para> - </listitem> + <itemizedlist> + <listitem><para><filename>libdata/gtk-2.0/gdk-pixbuf.loaders</filename></para></listitem> + <listitem><para><filename>libdata/gtk-2.0/gtk.immodules</filename></para></listitem> + </itemizedlist> - <listitem> <para> - Check the PLIST and remove any entries under the - <filename>libdata/gtk-2.0</filename> directory, as they will be - handled automatically.</para> </listitem> - </orderedlist> - </sect2> - - - <sect2 id="sgml-xml-data"> - <title>Packages installing SGML or XML data</title> - - <para>If a package installs SGML or XML data files that need to be - registered in system-wide catalogs (like DTDs, sub-catalogs, - etc.), you need to take some extra steps: -</para> - - <orderedlist> - <listitem> - <para>Include - <filename>../../textproc/xmlcatmgr/catalogs.mk</filename> in - your <filename>Makefile</filename>, which takes care of - registering those files in system-wide catalogs at - installation and deinstallation time.</para> - </listitem> - - <listitem> - <para>Set <varname>SGML_CATALOGS</varname> to the full path of - any SGML catalogs installed by the package.</para> - </listitem> - - <listitem> - <para>Set <varname>XML_CATALOGS</varname> to the full path of - any XML catalogs installed by the package.</para> - </listitem> - - <listitem> - <para>Set <varname>SGML_ENTRIES</varname> to individual entries - to be added to the SGML catalog. These come in groups of - three strings; see xmlcatmgr(1) for more information - (specifically, arguments recognized by the 'add' action). - Note that you will normally not use this variable.</para> - </listitem> - - <listitem> - <para>Set <varname>XML_ENTRIES</varname> to individual entries - to be added to the XML catalog. These come in groups of three - strings; see xmlcatmgr(1) for more information (specifically, - arguments recognized by the 'add' action). Note that you will - normally not use this variable. -</para> - </listitem> - </orderedlist> - </sect2> + <listitem><para>Check the <filename>PLIST</filename> and remove + any entries under the <filename>libdata/gtk-2.0</filename> + directory, as they will be handled automatically.</para> + </listitem> + </orderedlist> + </sect2> - <sect2 id="mime-database"> - <title>Packages installing extensions to the MIME database</title> - <para>If a package provides extensions to the MIME database by - installing <filename>.xml</filename> files inside - <filename>${PREFIX}/share/mime/packages</filename>, you - need to take some extra steps to ensure that the database is kept - consistent with respect to these new files: -</para> + <sect2 id="sgml-xml-data"> + <title>Packages installing SGML or XML data</title> - <orderedlist> - <listitem> - <para>Include - <filename>../../databases/shared-mime-info/mimedb.mk</filename> - (avoid using the <filename>buildlink3.mk</filename> file from - this same directory, which is reserved for inclusion from - other <filename>buildlink3.mk</filename> files). It takes - care of rebuilding the MIME database at installation and - deinstallation time, and disallows any access to it directly - from the package.</para> - </listitem> - - <listitem> - <para>Check the PLIST and remove any entries under the - <filename>share/mime</filename> directory, - <emphasis>except</emphasis> for files saved under - <filename>share/mime/packages</filename>. The former are - handled automatically by - the update-mime-database program, but the latter are - package-dependent and must be removed by the package that - installed them in the first place.</para> - </listitem> - - <listitem> - <para>Remove any <filename>share/mime/*</filename> directories - from the PLIST. They will be handled by the shared-mime-info - package.</para> - </listitem> - </orderedlist> - </sect2> + <para>If a package installs SGML or XML data files that need to be + registered in system-wide catalogs (like DTDs, sub-catalogs, + etc.), you need to take some extra steps:</para> + <orderedlist> + <listitem> + <para>Include + <filename>../../textproc/xmlcatmgr/catalogs.mk</filename> in + your <filename>Makefile</filename>, which takes care of + registering those files in system-wide catalogs at + installation and deinstallation time.</para> + </listitem> - <sect2 id="intltool"> - <title>Packages using intltool</title> + <listitem> + <para>Set <varname>SGML_CATALOGS</varname> to the full path of + any SGML catalogs installed by the package.</para> + </listitem> - <para>If a package uses intltool during its build, include the - <filename>../../textproc/intltool/buildlink3.mk</filename> file, - which forces it to use the intltool package provided by pkgsrc, - instead of the one bundled with the distribution file. -</para> + <listitem> + <para>Set <varname>XML_CATALOGS</varname> to the full path of + any XML catalogs installed by the package.</para> + </listitem> - <para>This tracks intltool's build-time dependencies and uses the - latest available version; this way, the package benefits of any - bug fixes that may have appeared since it was released. -</para> - </sect2> + <listitem> + <para>Set <varname>SGML_ENTRIES</varname> to individual entries + to be added to the SGML catalog. These come in groups of + three strings; see xmlcatmgr(1) for more information + (specifically, arguments recognized by the 'add' action). + Note that you will normally not use this variable.</para> + </listitem> + <listitem> + <para>Set <varname>XML_ENTRIES</varname> to individual entries + to be added to the XML catalog. These come in groups of three + strings; see xmlcatmgr(1) for more information (specifically, + arguments recognized by the 'add' action). Note that you will + normally not use this variable.</para> + </listitem> + </orderedlist> + </sect2> - <sect2 id="startup-scripts"> - <title>Packages installing startup scripts</title> - <para>If a package contains a rc.d script, it won't be copied into - the startup directory by default, but you can enable it, by adding - the option <varname>PKG_RCD_SCRIPTS=YES</varname> in - <filename>/etc/mk.conf</filename>. This option will copy the scripts - into <filename>/etc/rc.d</filename> when a package is installed, and - it will automatically remove the scripts when the package is - deinstalled.</para> - </sect2> - <sect2 id="tex-packages"> - <title>Packages installing TeX modules</title> + <sect2 id="mime-database"> + <title>Packages installing extensions to the MIME database</title> - <para>If a package installs TeX packages into the texmf tree, - the <filename>ls-R</filename> database of the tree needs to be - updated.</para> - <note><para>Except the main TeX packages such as teTeX-texmf, - packages should install files - into <varname>PKG_LOCALTEXMFPREFIX</varname>, - not <varname>PKG_TEXMFPREFIX</varname>.</para></note> + <para>If a package provides extensions to the MIME database by + installing <filename>.xml</filename> files inside + <filename>${PREFIX}/share/mime/packages</filename>, you + need to take some extra steps to ensure that the database is kept + consistent with respect to these new files:</para> - <orderedlist> - <listitem><para>Include - <filename>../../print/teTeX/module.mk</filename> instead - of <filename>../../mk/tex.buildlink3.mk</filename>. This - takes care of rebuilding the <filename>ls-R</filename> - database at installation and deinstallation time.</para> - </listitem> - - <listitem><para>If your package installs files into a texmf - tree other than the one - at <varname>PKG_LOCALTEXMFPREFIX</varname>, - set <varname>TEXMFDIRS</varname> to the list of all texmf - trees that need database update.</para> - <para>If your package also installs font map files that need - to be registered using <command>updmap</command>, - set <varname>TEX_FONTMAPS</varname> to the list of all - such font map files. Then <command>updmap</command> will - be run automatically at installation/deinstallation to - enable/disable font map files for TeX output - drivers.</para> - </listitem> - - <listitem><para>Make sure that none of <filename>ls-R</filename> - databases are included in <filename>PLIST</filename>, as - they will be removed only by the teTeX-bin package.</para> - </listitem> - </orderedlist> - </sect2> + <orderedlist> + <listitem> + <para>Include + <filename>../../databases/shared-mime-info/mimedb.mk</filename> + (avoid using the <filename>buildlink3.mk</filename> file from + this same directory, which is reserved for inclusion from + other <filename>buildlink3.mk</filename> files). It takes + care of rebuilding the MIME database at installation and + deinstallation time, and disallows any access to it directly + from the package.</para> + </listitem> + <listitem> + <para>Check the PLIST and remove any entries under the + <filename>share/mime</filename> directory, + <emphasis>except</emphasis> for files saved under + <filename>share/mime/packages</filename>. The former are + handled automatically by + the update-mime-database program, but the latter are + package-dependent and must be removed by the package that + installed them in the first place.</para> + </listitem> - <sect2 id="hicolor-theme"> - <title>Packages installing hicolor theme icons</title> + <listitem> + <para>Remove any <filename>share/mime/*</filename> directories + from the PLIST. They will be handled by the shared-mime-info + package.</para> + </listitem> + </orderedlist> + </sect2> + + + <sect2 id="intltool"> + <title>Packages using intltool</title> + + <para>If a package uses intltool during its build, include the + <filename>../../textproc/intltool/buildlink3.mk</filename> file, + which forces it to use the intltool package provided by pkgsrc, + instead of the one bundled with the distribution file.</para> + + <para>This tracks intltool's build-time dependencies and uses the + latest available version; this way, the package benefits of any + bug fixes that may have appeared since it was released.</para> + </sect2> + + + <sect2 id="startup-scripts"> + <title>Packages installing startup scripts</title> + <para>If a package contains a rc.d script, it won't be copied into + the startup directory by default, but you can enable it, by adding + the option <varname>PKG_RCD_SCRIPTS=YES</varname> in + <filename>/etc/mk.conf</filename>. This option will copy the scripts + into <filename>/etc/rc.d</filename> when a package is installed, and + it will automatically remove the scripts when the package is + deinstalled.</para> + </sect2> + + <sect2 id="tex-packages"> + <title>Packages installing TeX modules</title> + + <para>If a package installs TeX packages into the texmf tree, + the <filename>ls-R</filename> database of the tree needs to be + updated.</para> + <note><para>Except the main TeX packages such as teTeX-texmf, + packages should install files + into <varname>PKG_LOCALTEXMFPREFIX</varname>, + not <varname>PKG_TEXMFPREFIX</varname>.</para></note> + + <orderedlist> + <listitem><para>Include + <filename>../../print/teTeX/module.mk</filename> instead + of <filename>../../mk/tex.buildlink3.mk</filename>. This + takes care of rebuilding the <filename>ls-R</filename> + database at installation and deinstallation time.</para> + </listitem> - <para>If a package installs images under the - <filename>share/icons/hicolor</filename> and/or updates the - <filename>share/icons/hicolor/icon-theme.cache</filename> database, - you need to take some extra steps to make sure that the shared - theme directory is handled appropriately and that the cache - database is rebuilt:</para> + <listitem><para>If your package installs files into a texmf + tree other than the one + at <varname>PKG_LOCALTEXMFPREFIX</varname>, + set <varname>TEXMFDIRS</varname> to the list of all texmf + trees that need database update.</para> + <para>If your package also installs font map files that need + to be registered using <command>updmap</command>, + set <varname>TEX_FONTMAPS</varname> to the list of all + such font map files. Then <command>updmap</command> will + be run automatically at installation/deinstallation to + enable/disable font map files for TeX output + drivers.</para> + </listitem> - <orderedlist> - <listitem> - <para>Include - <filename>../../graphics/hicolor-icon-theme/buildlink3.mk</filename>.</para> - </listitem> + <listitem><para>Make sure that none of <filename>ls-R</filename> + databases are included in <filename>PLIST</filename>, as + they will be removed only by the teTeX-bin package.</para> + </listitem> + </orderedlist> + </sect2> + + <sect2 id="emulation-packages"> + <title>Packages supporting running binaries in + emulation</title> + + <para>There are some packages that provide libraries and + executables for running binaries from a one operating system + on a different one (if the latter supports it). One example + is running Linux binaries on NetBSD.</para> + + <para>The <filename role="pkg">pkgtools/rpm2pkg</filename> + helps in extracting and packaging Linux rpm packages.</para> + + <para>The <varname>CHECK_SHLIBS</varname> can be set to no to + avoid the <command>check-shlibs</command> target, which tests + if all libraries for each installed executable can be found by + the dynamic linker. Since the standard dynamic linker is run, + this fails for emulation packages, because the libraries used + by the emulation are not in the standard directories.</para> + </sect2> + + <sect2 id="hicolor-theme"> + <title>Packages installing hicolor theme icons</title> + + <para>If a package installs images under the + <filename>share/icons/hicolor</filename> and/or updates the + <filename>share/icons/hicolor/icon-theme.cache</filename> + database, you need to take some extra steps to make sure that the + shared theme directory is handled appropriately and that the cache + database is rebuilt:</para> + + <orderedlist> + <listitem> + <para>Include + <filename>../../graphics/hicolor-icon-theme/buildlink3.mk</filename>.</para> + </listitem> - <listitem> - <para>Check the PLIST and remove the entry that refers to the - theme cache.</para> - </listitem> + <listitem> + <para>Check the <filename>PLIST</filename> and remove the + entry that refers to the theme cache.</para> + </listitem> <listitem> <para>Ensure that the PLIST does not remove the shared icon @@ -1699,7 +1781,34 @@ Changes to the PLIST respect to the last point is to regenerate it using <command>make print-PLIST</command>.</para> </sect2> +</sect1> - </sect1> +<sect1 id="punting"> + <title>Marking packages as having problems</title> + + <para>In some cases one does not have the time to solve a problem + immediately. There are currently two ways to declare that one knows + that a package has problems.</para> + <itemizedlist> + <listitem><para>The first way is to plainly mark it as broken. For + this, one just sets the variable <varname>BROKEN</varname> to the + reason why the package is broken (similar to the + <varname>RESTRICTED</varname> variable). A user trying to build + the package will immediately be shown this message, and the build + will not be even tried.</para></listitem> + + <listitem><para>After each pkgsrc freeze period (a time when the + tree is stabilized and a new pkgsrc branch is cut), the packages + that were not building in the official branch build on the latest + NetBSD release will be marked as broken on that branch. This is + done by setting the <varname>BROKEN_IN</varname> variable to the + branch name (or appending the branch name to it). If a user tries + to build such a package and the build fails, the user gets a + message that says that the package was broken on the respective + branch(es).</para></listitem> + </itemizedlist> + <para>Both types of packages are removed from pkgsrc in irregular + intervals.</para> +</sect1> </chapter> |