diff options
| author | rillig <rillig@pkgsrc.org> | 2006-05-10 20:59:39 +0000 |
|---|---|---|
| committer | rillig <rillig@pkgsrc.org> | 2006-05-10 20:59:39 +0000 |
| commit | 044ea4f40736f21ff2593be6f036e26d172ad175 (patch) | |
| tree | a3b591f6ce733e639b7f3775b402c457fc1f7447 /doc | |
| parent | e300a151d927f0c3655b2d2b972165dc38c45e1f (diff) | |
| download | pkgsrc-044ea4f40736f21ff2593be6f036e26d172ad175.tar.gz | |
regen.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/pkgsrc.html | 927 | ||||
| -rw-r--r-- | doc/pkgsrc.txt | 427 |
2 files changed, 1052 insertions, 302 deletions
diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html index e2cbc7d9c45..82184ab8077 100644 --- a/doc/pkgsrc.html +++ b/doc/pkgsrc.html @@ -66,8 +66,8 @@ alink="#0000FF"> </div> <div xmlns="http://www.w3.org/TR/xhtml1/transitional"> - <p xmlns="" class="pubdate">$NetBSD: pkgsrc.xml,v 1.12 - 2006/02/18 01:46:43 rillig Exp $</p> + <p xmlns="" class="pubdate">$NetBSD: pkgsrc.xml,v 1.14 + 2006/05/10 20:56:00 rillig Exp $</p> </div> <div> @@ -549,7 +549,7 @@ alink="#0000FF"> <dt><span class="sect2"><a href= "#updating-buildlink-depends">11.2.2. Updating <code class= - "varname">BUILDLINK_DEPENDS.<em class= + "varname">BUILDLINK_API_DEPENDS.<em class= "replaceable"><code>pkg</code></em></code> in <code xmlns= "http://www.w3.org/TR/xhtml1/transitional" @@ -1023,17 +1023,58 @@ alink="#0000FF"> </dl> </dd> - <dt><span class="chapter"><a href="#porting">19. + <dt><span class="chapter"><a href="#devfaq">19. + Frequently Asked Questions</a></span></dt> + </dl> + </dd> + + <dt><span class="part"><a href="#infrastructure">III. The + pkgsrc infrastructure</a></span></dt> + + <dd> + <dl> + <dt><span class="chapter"><a href="#regression">20. + Regression tests</a></span></dt> + + <dd> + <dl> + <dt><span class="sect1"><a href= + "#regression.descr">20.1. The regression tests + framework</a></span></dt> + + <dt><span class="sect1"><a href= + "#regression.run">20.2. Running the regression + tests</a></span></dt> + + <dt><span class="sect1"><a href= + "#regression.new">20.3. Adding a new regression + test</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#regression.fun.override">20.3.1. Overridable + functions</a></span></dt> + + <dt><span class="sect2"><a href= + "#regression.fun.helper">20.3.2. Helper + functions</a></span></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><span class="chapter"><a href="#porting">21. Porting pkgsrc</a></span></dt> <dd> <dl> <dt><span class="sect1"><a href= - "#porting.opsys">19.1. Porting pkgsrc to a new + "#porting.opsys">21.1. Porting pkgsrc to a new operating system</a></span></dt> <dt><span class="sect1"><a href= - "#porting.compiler">19.2. Adding support for a new + "#porting.compiler">21.2. Adding support for a new compiler</a></span></dt> </dl> </dd> @@ -3196,7 +3237,15 @@ alink="#0000FF"> <tbody> <tr> - <td>Solaris 5.10</td> + <td>Solaris 9</td> + + <td><code xmlns= + "http://www.w3.org/TR/xhtml1/transitional" class= + "filename">ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/bootstrap-pkgsrc/</code></td> + </tr> + + <tr> + <td>Solaris 10</td> <td><code xmlns= "http://www.w3.org/TR/xhtml1/transitional" class= @@ -3271,7 +3320,16 @@ alink="#0000FF"> <tbody> <tr> - <td>Solaris 5.10</td> + <td>Solaris 9</td> + + <td><code xmlns= + "http://www.w3.org/TR/xhtml1/transitional" + class= + "filename">ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/</code></td> + </tr> + + <tr> + <td>Solaris 10</td> <td><code xmlns= "http://www.w3.org/TR/xhtml1/transitional" @@ -3282,11 +3340,14 @@ alink="#0000FF"> </table> </div> - <p>In each of these directories, there is a - subdirectory <code xmlns= + <p>Most of these directories contain the pkgsrc + distribution for multiple platforms. Select the + appropriate subdirectories, according to your machine + architecture and operating system, until you find a + directory called <code xmlns= "http://www.w3.org/TR/xhtml1/transitional" class= - "filename">All</code> that contains all the binary - packages. Further, there are subdirectories for + "filename">All</code>. This directory contains all the + binary packages. Further, there are subdirectories for categories that contain symbolic links that point to the actual binary package in <code xmlns= "http://www.w3.org/TR/xhtml1/transitional" class= @@ -5921,8 +5982,8 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> NetBSD-compatible <a href= "http://netbsd.gw.com/cgi-bin/man-cgi?ftp+1+NetBSD-current"> <span class="citerefentry"><span class= - "refentrytitle">ftp</span>(1)</span></a> (like lukemftp) - at work, don't forget to set <code class= + "refentrytitle">ftp</span>(1)</span></a> (like tnftp) at + work, don't forget to set <code class= "varname">FETCH_CMD</code> to something that fetches a URL:</p> @@ -6359,8 +6420,9 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> <dt><span class="sect2"><a href= "#updating-buildlink-depends">11.2.2. Updating <code class= - "varname">BUILDLINK_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> - in <code xmlns= + "varname">BUILDLINK_API_DEPENDS.<em class= + "replaceable"><code>pkg</code></em></code> in + <code xmlns= "http://www.w3.org/TR/xhtml1/transitional" class= "filename">buildlink3.mk</code> files</a></span></dt> @@ -6821,20 +6883,8 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> </dl> </dd> - <dt><span class="chapter"><a href="#porting">19. Porting - pkgsrc</a></span></dt> - - <dd> - <dl> - <dt><span class="sect1"><a href= - "#porting.opsys">19.1. Porting pkgsrc to a new - operating system</a></span></dt> - - <dt><span class="sect1"><a href= - "#porting.compiler">19.2. Adding support for a new - compiler</a></span></dt> - </dl> - </dd> + <dt><span class="chapter"><a href="#devfaq">19. + Frequently Asked Questions</a></span></dt> </dl> </div> @@ -7008,7 +7058,7 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> <p>If the package has multiple <code class= "varname">DISTFILES</code> or multiple <code class= "varname">PATCHFILES</code> from different sites, - set <code class="varname">SITES_foo</code> to a + set <code class="varname">SITES.foo</code> to a list of URIs where file “<span class= "quote">foo</span>” may be found. “<span class="quote">foo</span>” @@ -7016,7 +7066,7 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> <pre class="programlisting"> DISTFILES= ${DISTNAME}${EXTRACT_SUFX} DISTFILES+= foo-file.tar.gz - SITES_foo-file.tar.gz= \ + SITES.foo-file.tar.gz= \ http://www.somewhere.com/somehow/ \ http://www.somewhereelse.com/mirror/somehow/ </pre> @@ -8319,24 +8369,6 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> </ul> </div> </dd> - - <dt><span class="term"><code class= - "varname">${PKGLOCALEDIR}</code></span></dt> - - <dd> - <p>Packages that install locale files should list - them in the PLIST as “<span class= - "quote">${PKGLOCALEDIR}/locale/de/LC_MESSAGES/...</span>” - instead of “<span class= - "quote">share/locale/de/LC_MESSAGES/...</span>”. - This properly handles the fact that different - operating systems expect locale files to be either - in <code xmlns= - "http://www.w3.org/TR/xhtml1/transitional" class= - "filename">share</code> or <code xmlns= - "http://www.w3.org/TR/xhtml1/transitional" class= - "filename">lib</code> by default.</p> - </dd> </dl> </div> @@ -8590,7 +8622,8 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> <dt><span class="sect2"><a href= "#updating-buildlink-depends">11.2.2. Updating - <code class="varname">BUILDLINK_DEPENDS.<em class= + <code class= + "varname">BUILDLINK_API_DEPENDS.<em class= "replaceable"><code>pkg</code></em></code> in <code xmlns= "http://www.w3.org/TR/xhtml1/transitional" class= @@ -8728,7 +8761,7 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> dependency when using buildlink3.mk files, then you can define it in your Makefile; for example:</p> <pre class="programlisting"> - BUILDLINK_DEPENDS.foo+= foo>=1.1.0 + BUILDLINK_API_DEPENDS.foo+= foo>=1.1.0 .include "../../category/foo/buildlink3.mk" </pre> @@ -8912,7 +8945,7 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> BUILDLINK_PACKAGES+= tiff .if !empty(TIFF_BUILDLINK3_MK:M+) - BUILDLINK_DEPENDS.tiff+= tiff>=3.6.1 + BUILDLINK_API_DEPENDS.tiff+= tiff>=3.6.1 BUILDLINK_PKGSRCDIR.tiff?= ../../graphics/tiff .endif # TIFF_BUILDLINK3_MK @@ -8961,7 +8994,7 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> <ul type="disc"> <li> <p><code class= - "varname">BUILDLINK_DEPENDS.<em class= + "varname">BUILDLINK_API_DEPENDS.<em class= "replaceable"><code>pkg</code></em></code> is the actual dependency recorded in the installed package; this should always be set using @@ -8969,9 +9002,7 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> to ensure that we're appending to any pre-existing list of values. This variable should be set to the first version of the package that - had the last change in the major number of a - shared library or that had a major API - change.</p> + had an API change.</p> </li> <li> @@ -9150,37 +9181,24 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> <h3 class="title"><a name= "updating-buildlink-depends"></a>11.2.2. Updating <code class= - "varname">BUILDLINK_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> - in <code xmlns= + "varname">BUILDLINK_API_DEPENDS.<em class= + "replaceable"><code>pkg</code></em></code> in + <code xmlns= "http://www.w3.org/TR/xhtml1/transitional" class= "filename">buildlink3.mk</code> files</h3> </div> </div> </div> - <p>There are two situations that require increasing the + <p>The situation that requires increasing the dependency listed in <code class= - "varname">BUILDLINK_DEPENDS.<em class= + "varname">BUILDLINK_API_DEPENDS.<em class= "replaceable"><code>pkg</code></em></code> after a - package update:</p> - - <div class="orderedlist"> - <ol type="1"> - <li> - <p>if the sonames (major number of the library - version) of any installed shared libraries - change.</p> - </li> - - <li> - <p>if the API or interface to the header files - change.</p> - </li> - </ol> - </div> + package update is when the API or interface to the + header files change.</p> - <p>In these cases, <code class= - "varname">BUILDLINK_DEPENDS.<em class= + <p>In this case, <code class= + "varname">BUILDLINK_API_DEPENDS.<em class= "replaceable"><code>pkg</code></em></code> should be adjusted to require at least the new package version. In some cases, the packages that depend on this new @@ -9189,26 +9207,45 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> have <code xmlns= "http://www.w3.org/TR/xhtml1/transitional" class= "filename">buildlink3.mk</code> files, their - <code class="varname">BUILDLINK_DEPENDS.<em class= + <code class="varname">BUILDLINK_API_DEPENDS.<em class= "replaceable"><code>pkg</code></em></code> adjusted, - too. This is needed so that binary packages made using - it will require the correct package dependency and not - settle for an older one which will not contain the - necessary shared libraries.</p> + too. This is needed so pkgsrc will require the correct + package dependency and not settle for an older one when + building the source.</p> - <p>Please take careful consideration before adjusting - <code class="varname">BUILDLINK_DEPENDS.<em class= - "replaceable"><code>pkg</code></em></code> as we don't - want to cause unneeded package deletions and rebuilds. - In many cases, new versions of packages work just fine - with older dependencies. See <a href="#dependencies" - title= + <p><code class= + "varname">BUILDLINK_ABI_DEPENDS.<em class= + "replaceable"><code>pkg</code></em></code> should be + increased when the binary interface or sonames (major + number of the library version) of any installed shared + libraries change. This is needed so that binary + packages made using it will require the correct package + dependency and not settle for an older one which will + not contain the necessary shared libraries.</p> + + <p>See <a href="#dependencies" title= "16.1.4. Handling dependencies">Section 16.1.4, “Handling dependencies”</a> for more information about dependencies on other packages, including the <code class= - "varname">BUILDLINK_RECOMMENDED</code> and <code class= - "varname">RECOMMENDED</code> definitions.</p> + "varname">BUILDLINK_ABI_DEPENDS</code> and <code class= + "varname">ABI_DEPENDS</code> definitions.</p> + + <p>Please take careful consideration before adjusting + <code class="varname">BUILDLINK_API_DEPENDS.<em class= + "replaceable"><code>pkg</code></em></code> or + <code class="varname">BUILDLINK_ABI_DEPENDS.<em class= + "replaceable"><code>pkg</code></em></code> as we don't + want to cause unneeded package deletions and rebuilds. + In many cases, new versions of packages work just fine + with older dependencies.</p> + + <p>Also it is not needed to set <code class= + "varname">BUILDLINK_ABI_DEPENDS.<em class= + "replaceable"><code>pkg</code></em></code> when it is + identical to <code class= + "varname">BUILDLINK_API_DEPENDS.<em class= + "replaceable"><code>pkg</code></em></code>.</p> </div> </div> @@ -9305,7 +9342,7 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> .if !defined(USE_BUILTIN.foo) USE_BUILTIN.foo?= ${IS_BUILTIN.foo} . if defined(BUILTIN_PKG.foo) - . for _depend_ in ${BUILDLINK_DEPENDS.foo} + . for _depend_ in ${BUILDLINK_API_DEPENDS.foo} . if !empty(USE_BUILTIN.foo:M[yY][eE][sS]) USE_BUILTIN.foo!= \ if ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo}; then \ @@ -9363,13 +9400,13 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> this section must make the determination whether the built-in software is adequate to satisfy the dependencies listed in <code class= - "varname">BUILDLINK_DEPENDS.<em class= + "varname">BUILDLINK_API_DEPENDS.<em class= "replaceable"><code>pkg</code></em></code>. This is typically done by comparing <code class= "varname">BUILTIN_PKG.<em class= "replaceable"><code>pkg</code></em></code> against each of the dependencies in <code class= - "varname">BUILDLINK_DEPENDS.<em class= + "varname">BUILDLINK_API_DEPENDS.<em class= "replaceable"><code>pkg</code></em></code>. <code class="varname">USE_BUILTIN.<em class= "replaceable"><code>pkg</code></em></code> <span class= @@ -10143,37 +10180,50 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> <p>Users can be created by adding entries to the <code class="varname">PKG_USERS</code> variable. Each - entry has the following syntax, which mimics <code xmlns= - "http://www.w3.org/TR/xhtml1/transitional" class= - "filename">/etc/passwd</code>:</p> + entry has the following syntax:</p> <pre class="programlisting"> - user:group[:[userid][:[descr][:[home][:shell]]]] + user:group </pre> - <p>Only the user and group are required; everything else - is optional, but the colons must be in the right places - when specifying optional bits. By default, a new user - will have home directory <code xmlns= + <p>Further specification of user details may be done by + setting per-user variables. <code class= + "varname">PKG_UID.<em class= + "replaceable"><code>user</code></em></code> is the + numeric UID for the user. <code class= + "varname">PKG_GECOS.<em class= + "replaceable"><code>user</code></em></code> is the user's + description or comment. <code class= + "varname">PKG_HOME.<em class= + "replaceable"><code>user</code></em></code> is the user's + home directory, and defaults to <code xmlns= "http://www.w3.org/TR/xhtml1/transitional" class= - "filename">/nonexistent</code>, and login shell - <code xmlns="http://www.w3.org/TR/xhtml1/transitional" - class="filename">/sbin/nologin</code> unless they are - specified as part of the user element. Note that if the - description contains spaces, then spaces should be - backslash-escaped, as in:</p> - <pre class="programlisting"> - foo:foogrp::The\ Foomister -</pre> + "filename">/nonexistent</code> if not specified. + <code class="varname">PKG_SHELL.<em class= + "replaceable"><code>user</code></em></code> is the user's + shell, and defaults to <code xmlns= + "http://www.w3.org/TR/xhtml1/transitional" class= + "filename">/sbinno/login</code> if not specified.</p> - <p>Similarly, groups can be created using the - <code class="varname">PKG_GROUPS</code> variable, whose - syntax is:</p> + <p>Similarly, groups can be created by adding entries to + the <code class="varname">PKG_GROUPS</code> variable, + whose syntax is:</p> <pre class="programlisting"> - group[:groupid] + group </pre> - <p>As before, only the group name is required; the - numeric identifier is optional.</p> + <p>The numeric GID of the group may be set by defining + <code class="varname">PKG_GID.<em class= + "replaceable"><code>group</code></em></code>.</p> + + <p>If a package needs to create the users and groups at + an earlier stage, then it can set <code class= + "varname">USERGROUP_PHASE</code> to either <code class= + "literal">configure</code> or <code class= + "literal">build</code> to indicate the phase before which + the users and groups are created. In this case, the + numeric UIDs and GIDs of the created users and groups are + automatically hardcoded into the final installation + scripts.</p> </div> <div class="sect1" lang="en"> @@ -11035,7 +11085,7 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> turn: first, <code class= "varname">MASTER_SITE_OVERRIDE</code> is tried, then the sites specified in either <code class= - "varname">SITES_file</code> if defined, else <code class= + "varname">SITES.file</code> if defined, else <code class= "varname">MASTER_SITES</code> or <code class= "varname">PATCH_SITES</code>, as applies, then finally the value of <code class= @@ -11214,7 +11264,70 @@ nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> </div> </div> - <p>[TODO]</p> + <p>This phase creates wrapper programs for the compilers + and linkers. The following variables can be used to tweak + the wrappers.</p> + + <div class="variablelist"> + <dl> + <dt><span class="term"><code class= + "varname">ECHO_WRAPPER_MSG</code></span></dt> + + <dd> + <p>The command used to print progress messages. + Does nothing by default. Set to <code class= + "literal">${ECHO}</code> to see the progress + messages.</p> + </dd> + + <dt><span class="term"><code class= + "varname">WRAPPER_DEBUG</code></span></dt> + + <dd> + <p>This variable can be set to <code class= + "literal">yes</code> (default) or <code class= + "literal">no</code>, depending on whether you want + additional information in the wrapper log file.</p> + </dd> + + <dt><span class="term"><code class= + "varname">WRAPPER_UPDATE_CACHE</code></span></dt> + + <dd> + <p>This variable can be set to <code class= + "literal">yes</code> or <code class= + "literal">no</code>, depending on whether the + wrapper should use its cache, which will improve + the speed. The default value is <code class= + "literal">yes</code>, but is forced to <code class= + "literal">no</code> if the platform does not + support it.</p> + </dd> + + <dt><span class="term"><code class= + "varname">WRAPPER_REORDER_CMDS</code></span></dt> + + <dd> + <p>A list of reordering commands. A reordering + command has the form <code class= + "literal">reorder:l:<em class= + "replaceable"><code>lib1</code></em>:<em class= + "replaceable"><code>lib2</code></em></code>. It + ensures that that <code class= + "literal">-l<em class="replaceable"><code>lib1</code></em></code> + occurs before <code class="literal">-l<em class= + "replaceable"><code>lib2</code></em></code>.</p> + </dd> + + <dt><span class="term"><code class= + "varname">WRAPPER_TRANSFORM_CMDS</code></span></dt> + + <dd> + <p>A list of transformation commands. [TODO: + investigate further]</p> + </dd> + </dl> + </div> </div> <div class="sect1" lang="en"> @@ -12714,12 +12827,12 @@ TOOLS_PLATFORM.true?= true # shell builtin <p>Please note that such dependencies should only be updated if a package requires a newer pre-requisite, but not to denote recommendations - such as security updates or ABI changes that do - not prevent a package from building correctly. - Such recommendations can be expressed using - <code class="varname">RECOMMENDED</code>:</p> + such as ABI changes that do not prevent a package + from building correctly. Such recommendations can + be expressed using <code class= + "varname">ABI_DEPENDS</code>:</p> <pre class="programlisting"> - RECOMMENDED+= tiff>=3.6.1:../../graphics/tiff + ABI_DEPENDS+= tiff>=3.6.1:../../graphics/tiff </pre> <p>In addition to the above <code class= @@ -12727,15 +12840,15 @@ TOOLS_PLATFORM.true?= true # shell builtin while a package will build against tiff>=3.5.4, at least version 3.6.1 is recommended. <code class= - "varname">RECOMMENDED</code> entries will be + "varname">ABI_DEPENDS</code> entries will be turned into dependencies unless explicitly ignored (in which case a warning will be printed).</p> - <p>To ignore these dependency recommendations and - just use the required <code class= + <p>To ignore these ABI dependency recommendations + and just use the required <code class= "varname">DEPENDS</code>, set <code class= - "varname">IGNORE_RECOMMENDED=YES</code>. This may + "varname">USE_ABI_DEPENDS=NO</code>. This may make it easier and faster to update packages built using pkgsrc, since older compatible dependencies can continue to be used. This is @@ -12752,9 +12865,8 @@ TOOLS_PLATFORM.true?= true # shell builtin versions of binary packages installed.</p> <p>For security fixes, please update the package - vulnerabilities file as well as setting - <code class="varname">RECOMMENDED</code>, see - <a href="#security-handling" title= + vulnerabilities file. See <a href= + "#security-handling" title= "16.1.8. Handling packages with security problems"> Section 16.1.8, “Handling packages with security problems”</a> for more @@ -12954,13 +13066,7 @@ TOOLS_PLATFORM.true?= true # shell builtin <code class="varname">PKGREVISION</code> should be increased (this is of course not necessary if the problem is fixed by using a newer release of the - software). In addition, if a <code xmlns= - "http://www.w3.org/TR/xhtml1/transitional" class= - "filename">buildlink3.mk</code> file exists for an - affected package, a corresponding <code class= - "varname">BUILDLINK_RECOMMENDED.<em class= - "replaceable"><code>pkg</code></em></code> entry should - be added or updated in it.</p> + software).</p> <p>Also, if the fix should be applied to the stable pkgsrc branch, be sure to submit a pullup request!</p> @@ -14088,37 +14194,10 @@ TOOLS_PLATFORM.true?= true # shell builtin <p>Some packages install info files or use the “<span class="quote">makeinfo</span>” or “<span class="quote">install-info</span>” - commands. Each of the info files:</p> - - <div class="itemizedlist"> - <ul type="disc"> - <li> - <p>is considered to be installed in the directory - <code xmlns= - "http://www.w3.org/TR/xhtml1/transitional" class= - "filename">${PREFIX}/${INFO_DIR}</code>,</p> - </li> - - <li> - <p>is registered in the Info directory file - <code xmlns= - "http://www.w3.org/TR/xhtml1/transitional" class= - "filename">${PREFIX}/${INFO_DIR}/dir</code>,</p> - </li> - - <li> - <p>and must be listed as a filename in the - <code class="varname">INFO_FILES</code> variable - in the package Makefile.</p> - </li> - </ul> - </div> - - <p><code class="varname">INFO_DIR</code> defaults to - “<span class="quote">info</span>” and can - be overridden in the package Makefile. <code xmlns= - "http://www.w3.org/TR/xhtml1/transitional" class= - "filename">INSTALL</code> and <code xmlns= + commands. <code class="varname">INFO_FILES</code> + should be defined in the package Makefile so that + <code xmlns="http://www.w3.org/TR/xhtml1/transitional" + class="filename">INSTALL</code> and <code xmlns= "http://www.w3.org/TR/xhtml1/transitional" class= "filename">DEINSTALL</code> scripts will be generated to handle registration of the info files in the Info @@ -14128,10 +14207,26 @@ TOOLS_PLATFORM.true?= true # shell builtin system, or by a special purpose package automatically added as dependency if needed.</p> + <p><code class="varname">PKGINFODIR</code> is the + directory under <code xmlns= + "http://www.w3.org/TR/xhtml1/transitional" class= + "filename">${PREFIX}</code> where info files are + primarily located. <code class= + "varname">PKGINFODIR</code> defaults to + “<span class="quote">info</span>” and can + be overridden by the user.</p> + + <p>The info files for the package should be listed in + the package <code xmlns= + "http://www.w3.org/TR/xhtml1/transitional" class= + "filename">PLIST</code>; however any split info files + need not be listed.</p> + <p>A package which needs the “<span class= "quote">makeinfo</span>” command at build time - must define the variable <code class= - "varname">USE_MAKEINFO</code> in its Makefile. If a + must add “<span class= + "quote">makeinfo</span>” to <code class= + "varname">USE_TOOLS</code> in its Makefile. If a minimum version of the “<span class= "quote">makeinfo</span>” command is needed it should be noted with the <code class= @@ -14171,8 +14266,7 @@ TOOLS_PLATFORM.true?= true # shell builtin except the logging of a message. The script overriding <span><strong class="command">makeinfo</strong></span> logs a message and according to the value of - <code class="varname">USE_MAKEINFO</code> and - <code class="varname">TEXINFO_REQD</code> either run + <code class="varname">TEXINFO_REQD</code> either runs the appropriate <span><strong class= "command">makeinfo</strong></span> command or exit on error.</p> @@ -15357,7 +15451,480 @@ TOOLS_PLATFORM.true?= true # shell builtin <div> <div> <h2 class="title"><a name= - "porting"></a>Chapter 19. Porting + "devfaq"></a>Chapter 19. Frequently Asked + Questions</h2> + </div> + </div> + </div> + + <p>This section contains the answers to questions that may + arise when you are writing a package. If you don't find + your question answered here, first have a look in the other + chapters, and if you still don't have the answer, ask on + the <code class="literal">pkgsrc-users</code> mailing + list.</p> + + <div class="qandaset"> + <dl> + <dt>19.1. <a href="#id2654337">What is the difference + between MAKEFLAGS, .MAKEFLAGS and MAKE_FLAGS?</a></dt> + + <dt>19.2. <a href="#id2654373">What is the difference + between MAKE, GMAKE and MAKE_PROGRAM?</a></dt> + + <dt>19.3. <a href="#id2654411">What is the difference + between CC, PKG_CC and PKGSRC_COMPILER?</a></dt> + + <dt>19.4. <a href="#id2654449">What is the difference + between BUILDLINK_LDFLAGS, BUILDLINK_LDADD and + BUILDLINK_LIBS?</a></dt> + + <dt>19.5. <a href="#id2654467">Why does make show-var + VARNAME=BUILDLINK_PREFIX.foo say it's empty?</a></dt> + </dl> + + <table border="0" summary="Q and A Set"> + <col align="left" width="1%" /> + + <tbody> + <tr class="question"> + <td align="left" valign="top"><a name= + "id2654337"></a><a name= + "id2654338"></a><b>19.1.</b></td> + + <td align="left" valign="top"> + <p>What is the difference between <code class= + "varname">MAKEFLAGS</code>, <code class= + "varname">.MAKEFLAGS</code> and <code class= + "varname">MAKE_FLAGS</code>?</p> + </td> + </tr> + + <tr class="answer"> + <td align="left" valign="top"></td> + + <td align="left" valign="top"> + <p><code class="varname">MAKEFLAGS</code> are the + flags passed to the pkgsrc-internal invocations + of <a href= + "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"> + <span class="citerefentry"><span class= + "refentrytitle">make</span>(1)</span></a>, while + <code class="varname">MAKE_FLAGS</code> are the + flags that are passed to the <code class= + "varname">MAKE_PROGRAM</code> when building the + package. [FIXME: What is .MAKEFLAGS for?]</p> + </td> + </tr> + + <tr class="question"> + <td align="left" valign="top"><a name= + "id2654373"></a><a name= + "id2654374"></a><b>19.2.</b></td> + + <td align="left" valign="top"> + <p>What is the difference between <code class= + "varname">MAKE</code>, <code class= + "varname">GMAKE</code> and <code class= + "varname">MAKE_PROGRAM</code>?</p> + </td> + </tr> + + <tr class="answer"> + <td align="left" valign="top"></td> + + <td align="left" valign="top"> + <p><code class="varname">MAKE</code> is the path + to the <a href= + "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current"> + <span class="citerefentry"><span class= + "refentrytitle">make</span>(1)</span></a> program + that is used in the pkgsrc infrastructure. + <code class="varname">GMAKE</code> is the path to + GNU Make, but you need to say <code class= + "varname">USE_TOOLS+=gmake</code> to use that. + <code class="varname">MAKE_PROGRAM</code> is the + path to the Make program that is used for + building the package.</p> + </td> + </tr> + + <tr class="question"> + <td align="left" valign="top"><a name= + "id2654411"></a><a name= + "id2654412"></a><b>19.3.</b></td> + + <td align="left" valign="top"> + <p>What is the difference between <code class= + "varname">CC</code>, <code class= + "varname">PKG_CC</code> and <code class= + "varname">PKGSRC_COMPILER</code>?</p> + </td> + </tr> + + <tr class="answer"> + <td align="left" valign="top"></td> + + <td align="left" valign="top"> + <p><code class="varname">CC</code> is the path to + the real C compiler, which can be configured by + the pkgsrc user. <code class= + "varname">PKG_CC</code> is the path to the + compiler wrapper. <code class= + "varname">PKGSRC_COMPILER</code> is <span class= + "emphasis"><em>not</em></span> a path to a + compiler, but the type of compiler that should be + used. See <code xmlns= + "http://www.w3.org/TR/xhtml1/transitional" class= + "filename">mk/compiler.mk</code> for more + information about the latter variable.</p> + </td> + </tr> + + <tr class="question"> + <td align="left" valign="top"><a name= + "id2654449"></a><a name= + "id2654450"></a><b>19.4.</b></td> + + <td align="left" valign="top"> + <p>What is the difference between <code class= + "varname">BUILDLINK_LDFLAGS</code>, <code class= + "varname">BUILDLINK_LDADD</code> and <code class= + "varname">BUILDLINK_LIBS</code>?</p> + </td> + </tr> + + <tr class="answer"> + <td align="left" valign="top"></td> + + <td align="left" valign="top"> + <p>[FIXME]</p> + </td> + </tr> + + <tr class="question"> + <td align="left" valign="top"><a name= + "id2654467"></a><a name= + "id2654468"></a><b>19.5.</b></td> + + <td align="left" valign="top"> + <p>Why does <span><strong class="command">make + show-var VARNAME=BUILDLINK_PREFIX.<em class= + "replaceable"><code>foo</code></em></strong></span> + say it's empty?</p> + </td> + </tr> + + <tr class="answer"> + <td align="left" valign="top"></td> + + <td align="left" valign="top"> + <p>For optimization reasons, some variables are + only available in the “<span class= + "quote">wrapper</span>” phase and later. To + “<span class="quote">simulate</span>” + the wrapper phase, append <span><strong class= + "command">PKG_PHASE=wrapper</strong></span> to + the above command.</p> + </td> + </tr> + </tbody> + </table> + </div> + </div> + </div> + + <div class="part" lang="en"> + <div class="titlepage"> + <div> + <div> + <h1 class="title"><a name= + "infrastructure"></a>Part III. The pkgsrc + infrastructure</h1> + </div> + </div> + </div> + + <div class="toc"> + <p><b>Table of Contents</b></p> + + <dl> + <dt><span class="chapter"><a href="#regression">20. + Regression tests</a></span></dt> + + <dd> + <dl> + <dt><span class="sect1"><a href= + "#regression.descr">20.1. The regression tests + framework</a></span></dt> + + <dt><span class="sect1"><a href= + "#regression.run">20.2. Running the regression + tests</a></span></dt> + + <dt><span class="sect1"><a href= + "#regression.new">20.3. Adding a new regression + test</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#regression.fun.override">20.3.1. Overridable + functions</a></span></dt> + + <dt><span class="sect2"><a href= + "#regression.fun.helper">20.3.2. Helper + functions</a></span></dt> + </dl> + </dd> + </dl> + </dd> + + <dt><span class="chapter"><a href="#porting">21. Porting + pkgsrc</a></span></dt> + + <dd> + <dl> + <dt><span class="sect1"><a href= + "#porting.opsys">21.1. Porting pkgsrc to a new + operating system</a></span></dt> + + <dt><span class="sect1"><a href= + "#porting.compiler">21.2. Adding support for a new + compiler</a></span></dt> + </dl> + </dd> + </dl> + </div> + + <div class="chapter" lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title"><a name= + "regression"></a>Chapter 20. Regression + tests</h2> + </div> + </div> + </div> + + <div class="toc"> + <p><b>Table of Contents</b></p> + + <dl> + <dt><span class="sect1"><a href= + "#regression.descr">20.1. The regression tests + framework</a></span></dt> + + <dt><span class="sect1"><a href="#regression.run">20.2. + Running the regression tests</a></span></dt> + + <dt><span class="sect1"><a href="#regression.new">20.3. + Adding a new regression test</a></span></dt> + + <dd> + <dl> + <dt><span class="sect2"><a href= + "#regression.fun.override">20.3.1. Overridable + functions</a></span></dt> + + <dt><span class="sect2"><a href= + "#regression.fun.helper">20.3.2. Helper + functions</a></span></dt> + </dl> + </dd> + </dl> + </div> + + <p>The pkgsrc infrastructure consists of a large codebase, + and there are many corners where every little bit of a file + is well thought out, making pkgsrc likely to fail as soon + as anything is changed near those parts. To prevent most + changes from breaking anything, a suite of regression tests + should go along with every important part of the pkgsrc + infrastructure. This chapter describes how regression tests + work in pkgsrc and how you can add new tests.</p> + + <div class="sect1" lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title" style="clear: both"><a name= + "regression.descr"></a>20.1. The regression + tests framework</h2> + </div> + </div> + </div> + </div> + + <div class="sect1" lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title" style="clear: both"><a name= + "regression.run"></a>20.2. Running the + regression tests</h2> + </div> + </div> + </div> + + <p>You first need to install the <a xmlns= + "http://www.w3.org/TR/xhtml1/transitional" href= + "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_regress/README.html" + target="_top"><code xmlns="" class= + "filename">pkgtools/pkg_regress</code></a> package, which + provides the <span><strong class= + "command">pkg_regress</strong></span> command. Then you + can simply run that command, which will run all tests in + the <code xmlns= + "http://www.w3.org/TR/xhtml1/transitional" class= + "filename">regress</code> category.</p> + </div> + + <div class="sect1" lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title" style="clear: both"><a name= + "regression.new"></a>20.3. Adding a new + regression test</h2> + </div> + </div> + </div> + + <p>Every directory in the <code xmlns= + "http://www.w3.org/TR/xhtml1/transitional" class= + "filename">regress</code> category that contains a file + called <code xmlns= + "http://www.w3.org/TR/xhtml1/transitional" class= + "filename">spec</code> is considered a regression test. + This file is a shell program that is included by the + <span><strong class="command">pkg_regress</strong></span> + command. The following functions can be overridden to + suit your needs.</p> + + <div class="sect2" lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a name= + "regression.fun.override"></a>20.3.1. Overridable + functions</h3> + </div> + </div> + </div> + + <p>These functions do not take any parameters. They are + all called in “<span class="quote">set + -e</span>” mode, so you should be careful to + check the exitcodes of any commands you run in the + test.</p> + + <div class="variablelist"> + <dl> + <dt><span class="term"><code class= + "varname">do_setup()</code></span></dt> + + <dd> + <p>This function prepares the environment for the + test. By default it does nothing.</p> + </dd> + + <dt><span class="term"><code class= + "varname">do_test()</code></span></dt> + + <dd> + <p>This function runs the actual test. By + default, it calls <code class= + "varname">TEST_MAKE</code> with the arguments + <code class="varname">MAKEARGS_TEST</code> and + writes its output including error messages into + the file <code class= + "varname">TEST_OUTFILE</code>.</p> + </dd> + + <dt><span class="term"><code class= + "varname">check_result()</code></span></dt> + + <dd> + <p>This function is run after the test and is + typically used to compare the actual output from + the one that is expected. It can make use of the + various helper functions from the next + section.</p> + </dd> + + <dt><span class="term"><code class= + "varname">do_cleanup()</code></span></dt> + + <dd> + <p>This function cleans everything up after the + test has been run. By default it does + nothing.</p> + </dd> + </dl> + </div> + </div> + + <div class="sect2" lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a name= + "regression.fun.helper"></a>20.3.2. Helper + functions</h3> + </div> + </div> + </div> + + <div class="variablelist"> + <dl> + <dt><span class="term"><code class= + "varname">exit_status(expected)</code></span></dt> + + <dd> + <p>This function compares the exitcode of the + <span><strong class= + "command">do_test()</strong></span> function with + its first parameter. If they differ, the test + will fail.</p> + </dd> + + <dt><span class="term"><code class= + "varname">output_require(regex...)</code></span></dt> + + <dd> + <p>This function checks for each of its + parameters if the output from + <span><strong class="command">do_test()</strong></span> + matches the extended regular expression. If it + does not, the test will fail.</p> + </dd> + + <dt><span class="term"><code class= + "varname">output_prohibit(regex...)</code></span></dt> + + <dd> + <p>This function checks for each of its + parameters if the output from + <span><strong class="command">do_test()</strong></span> + does <span class="emphasis"><em>not</em></span> + match the extended regular expression. If any of + the regular expressions matches, the test will + fail.</p> + </dd> + </dl> + </div> + </div> + </div> + </div> + + <div class="chapter" lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title"><a name= + "porting"></a>Chapter 21. Porting pkgsrc</h2> </div> </div> @@ -15367,12 +15934,12 @@ TOOLS_PLATFORM.true?= true # shell builtin <p><b>Table of Contents</b></p> <dl> - <dt><span class="sect1"><a href="#porting.opsys">19.1. + <dt><span class="sect1"><a href="#porting.opsys">21.1. Porting pkgsrc to a new operating system</a></span></dt> <dt><span class="sect1"><a href= - "#porting.compiler">19.2. Adding support for a new + "#porting.compiler">21.2. Adding support for a new compiler</a></span></dt> </dl> </div> @@ -15387,7 +15954,7 @@ TOOLS_PLATFORM.true?= true # shell builtin <div> <div> <h2 class="title" style="clear: both"><a name= - "porting.opsys"></a>19.1. Porting pkgsrc to a + "porting.opsys"></a>21.1. Porting pkgsrc to a new operating system</h2> </div> </div> @@ -15510,7 +16077,7 @@ TOOLS_PLATFORM.true?= true # shell builtin <div> <div> <h2 class="title" style="clear: both"><a name= - "porting.compiler"></a>19.2. Adding support + "porting.compiler"></a>21.2. Adding support for a new compiler</h2> </div> </div> diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt index a3dec6a0b73..aebb802e54e 100644 --- a/doc/pkgsrc.txt +++ b/doc/pkgsrc.txt @@ -14,7 +14,7 @@ The pkgsrc Developers Copyright (C) 1994-2005 The NetBSD Foundation, Inc -$NetBSD: pkgsrc.xml,v 1.12 2006/02/18 01:46:43 rillig Exp $ +$NetBSD: pkgsrc.xml,v 1.14 2006/05/10 20:56:00 rillig Exp $ Abstract @@ -158,7 +158,7 @@ II. The pkgsrc developer's guide 11.2. Writing buildlink3.mk files 11.2.1. Anatomy of a buildlink3.mk file - 11.2.2. Updating BUILDLINK_DEPENDS.pkg in buildlink3.mk files + 11.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files 11.3. Writing builtin.mk files @@ -289,10 +289,23 @@ II. The pkgsrc developer's guide 18.4. Updating a package to a newer version 18.5. Moving a package in pkgsrc - 19. Porting pkgsrc + 19. Frequently Asked Questions - 19.1. Porting pkgsrc to a new operating system - 19.2. Adding support for a new compiler +III. The pkgsrc infrastructure + + 20. Regression tests + + 20.1. The regression tests framework + 20.2. Running the regression tests + 20.3. Adding a new regression test + + 20.3.1. Overridable functions + 20.3.2. Helper functions + + 21. Porting pkgsrc + + 21.1. Porting pkgsrc to a new operating system + 21.2. Adding support for a new compiler A. A simple example package: bison @@ -1165,11 +1178,13 @@ install them first. For the following platforms, prebuilt versions of the package tools are available and can simply be downloaded and unpacked in the / directory: -+--------------------------------------------------------------------+ -| Platform | URL | -|------------+-------------------------------------------------------| -|Solaris 5.10|http://public.enst.fr/pkgsrc/packages/bootstrap-pkgsrc/| -+--------------------------------------------------------------------+ ++------------------------------------------------------------------------+ +| Platform | URL | +|----------+-------------------------------------------------------------| +|Solaris 9 |ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/bootstrap-pkgsrc/| +|----------+-------------------------------------------------------------| +|Solaris 10|http://public.enst.fr/pkgsrc/packages/bootstrap-pkgsrc/ | ++------------------------------------------------------------------------+ These prebuilt package tools use /usr/pkg for the base directory, and /var/db/ pkg for the database of installed packages. If you cannot use these directories @@ -1189,17 +1204,22 @@ you should insert the output of uname -r, and for ARCH the output of uname -p. For some other platforms, binary packages can be found at the following locations: -+---------------------------------------------------+ -| Platform | URL | -|------------+--------------------------------------| -|Solaris 5.10|http://public.enst.fr/pkgsrc/packages/| -+---------------------------------------------------+ - -In each of these directories, there is a subdirectory All that contains all the -binary packages. Further, there are subdirectories for categories that contain -symbolic links that point to the actual binary package in ../All. This -directory layout is used for all package repositories, no matter if they are -accessed via HTTP, FTP, NFS, CD-ROM, or the local filesystem. ++-------------------------------------------------------+ +| Platform | URL | +|----------+--------------------------------------------| +|Solaris 9 |ftp://ftp0.mh.bbc.co.uk/pub/pkgsrc/packages/| +|----------+--------------------------------------------| +|Solaris 10|http://public.enst.fr/pkgsrc/packages/ | ++-------------------------------------------------------+ + +Most of these directories contain the pkgsrc distribution for multiple +platforms. Select the appropriate subdirectories, according to your machine +architecture and operating system, until you find a directory called All. This +directory contains all the binary packages. Further, there are subdirectories +for categories that contain symbolic links that point to the actual binary +package in ../All. This directory layout is used for all package repositories, +no matter if they are accessed via HTTP, FTP, NFS, CD-ROM, or the local +filesystem. 4.1.2. Installing binary packages @@ -2198,7 +2218,7 @@ on ftp.NetBSD.org, but downloading the entire directory may not be appropriate. The answer here is to do a make fetch-list in /usr/pkgsrc or one of its subdirectories, carry the resulting list to your machine at work/school and use -it there. If you don't have a NetBSD-compatible ftp(1) (like lukemftp) at work, +it there. If you don't have a NetBSD-compatible ftp(1) (like tnftp) at work, don't forget to set FETCH_CMD to something that fetches a URL: At home: @@ -2354,7 +2374,7 @@ Table of Contents 11.2. Writing buildlink3.mk files 11.2.1. Anatomy of a buildlink3.mk file - 11.2.2. Updating BUILDLINK_DEPENDS.pkg in buildlink3.mk files + 11.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files 11.3. Writing builtin.mk files @@ -2484,10 +2504,7 @@ Table of Contents 18.4. Updating a package to a newer version 18.5. Moving a package in pkgsrc -19. Porting pkgsrc - - 19.1. Porting pkgsrc to a new operating system - 19.2. Adding support for a new compiler +19. Frequently Asked Questions Chapter 8. Package components - files, directories and contents @@ -2577,12 +2594,12 @@ exactly in the order given here. Note the trailing slash after the subdirectory name. If the package has multiple DISTFILES or multiple PATCHFILES from different - sites, set SITES_foo to a list of URIs where file "foo" may be found. "foo" + sites, set SITES.foo to a list of URIs where file "foo" may be found. "foo" includes the suffix, e.g.: DISTFILES= ${DISTNAME}${EXTRACT_SUFX} DISTFILES+= foo-file.tar.gz - SITES_foo-file.tar.gz= \ + SITES.foo-file.tar.gz= \ http://www.somewhere.com/somehow/ \ http://www.somewhereelse.com/mirror/somehow/ @@ -3112,13 +3129,6 @@ ${OPSYS}, ${LOWER_OPSYS}, ${OS_VERSION} * ${OS_VERSION} - "uname -r" -${PKGLOCALEDIR} - - Packages that install locale files should list them in the PLIST as "$ - {PKGLOCALEDIR}/locale/de/LC_MESSAGES/..." instead of "share/locale/de/ - LC_MESSAGES/...". This properly handles the fact that different operating - systems expect locale files to be either in share or lib by default. - For a complete list of values which are replaced by default, please look in bsd.pkg.mk (and search for PLIST_SUBST). @@ -3215,7 +3225,7 @@ Table of Contents 11.2. Writing buildlink3.mk files 11.2.1. Anatomy of a buildlink3.mk file - 11.2.2. Updating BUILDLINK_DEPENDS.pkg in buildlink3.mk files + 11.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files 11.3. Writing builtin.mk files @@ -3271,7 +3281,7 @@ The buildlink3.mk files usually define the required dependencies. If you need a newer version of the dependency when using buildlink3.mk files, then you can define it in your Makefile; for example: - BUILDLINK_DEPENDS.foo+= foo>=1.1.0 + BUILDLINK_API_DEPENDS.foo+= foo>=1.1.0 .include "../../category/foo/buildlink3.mk" There are several buildlink3.mk files in pkgsrc/mk that handle special package @@ -3338,7 +3348,7 @@ tiff: BUILDLINK_PACKAGES+= tiff .if !empty(TIFF_BUILDLINK3_MK:M+) - BUILDLINK_DEPENDS.tiff+= tiff>=3.6.1 + BUILDLINK_API_DEPENDS.tiff+= tiff>=3.6.1 BUILDLINK_PKGSRCDIR.tiff?= ../../graphics/tiff .endif # TIFF_BUILDLINK3_MK @@ -3362,11 +3372,10 @@ within a buildlink3.mk file. The third section is protected from multiple inclusion and controls how the dependency on pkg is added. Several important variables are set in the section: - * BUILDLINK_DEPENDS.pkg is the actual dependency recorded in the installed - package; this should always be set using += to ensure that we're appending - to any pre-existing list of values. This variable should be set to the - first version of the package that had the last change in the major number - of a shared library or that had a major API change. + * BUILDLINK_API_DEPENDS.pkg is the actual dependency recorded in the + installed package; this should always be set using += to ensure that we're + appending to any pre-existing list of values. This variable should be set + to the first version of the package that had an API change. * BUILDLINK_PKGSRCDIR.pkg is the location of the pkg pkgsrc directory. @@ -3415,29 +3424,36 @@ dependencies. Including these buildlink3.mk files means that the headers and libraries for these dependencies are also symlinked into ${BUILDLINK_DIR} whenever the pkg buildlink3.mk file is included. -11.2.2. Updating BUILDLINK_DEPENDS.pkg in buildlink3.mk files - -There are two situations that require increasing the dependency listed in -BUILDLINK_DEPENDS.pkg after a package update: +11.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files - 1. if the sonames (major number of the library version) of any installed - shared libraries change. +The situation that requires increasing the dependency listed in +BUILDLINK_API_DEPENDS.pkg after a package update is when the API or interface +to the header files change. - 2. if the API or interface to the header files change. - -In these cases, BUILDLINK_DEPENDS.pkg should be adjusted to require at least +In this case, BUILDLINK_API_DEPENDS.pkg should be adjusted to require at least the new package version. In some cases, the packages that depend on this new version may need their PKGREVISIONs increased and, if they have buildlink3.mk -files, their BUILDLINK_DEPENDS.pkg adjusted, too. This is needed so that binary -packages made using it will require the correct package dependency and not -settle for an older one which will not contain the necessary shared libraries. +files, their BUILDLINK_API_DEPENDS.pkg adjusted, too. This is needed so pkgsrc +will require the correct package dependency and not settle for an older one +when building the source. + +BUILDLINK_ABI_DEPENDS.pkg should be increased when the binary interface or +sonames (major number of the library version) of any installed shared libraries +change. This is needed so that binary packages made using it will require the +correct package dependency and not settle for an older one which will not +contain the necessary shared libraries. + +See Section 16.1.4, "Handling dependencies" for more information about +dependencies on other packages, including the BUILDLINK_ABI_DEPENDS and +ABI_DEPENDS definitions. -Please take careful consideration before adjusting BUILDLINK_DEPENDS.pkg as we -don't want to cause unneeded package deletions and rebuilds. In many cases, new -versions of packages work just fine with older dependencies. See -Section 16.1.4, "Handling dependencies" for more information about dependencies -on other packages, including the BUILDLINK_RECOMMENDED and RECOMMENDED -definitions. +Please take careful consideration before adjusting BUILDLINK_API_DEPENDS.pkg or +BUILDLINK_ABI_DEPENDS.pkg as we don't want to cause unneeded package deletions +and rebuilds. In many cases, new versions of packages work just fine with older +dependencies. + +Also it is not needed to set BUILDLINK_ABI_DEPENDS.pkg when it is identical to +BUILDLINK_API_DEPENDS.pkg. 11.3. Writing builtin.mk files @@ -3479,7 +3495,7 @@ The following is the recommended template for builtin.mk files: .if !defined(USE_BUILTIN.foo) USE_BUILTIN.foo?= ${IS_BUILTIN.foo} . if defined(BUILTIN_PKG.foo) - . for _depend_ in ${BUILDLINK_DEPENDS.foo} + . for _depend_ in ${BUILDLINK_API_DEPENDS.foo} . if !empty(USE_BUILTIN.foo:M[yY][eE][sS]) USE_BUILTIN.foo!= \ if ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo}; then \ @@ -3512,13 +3528,13 @@ internally within the builtin.mk file. The third section sets USE_BUILTIN.pkg and is required in all builtin.mk files. The code in this section must make the determination whether the built-in -software is adequate to satisfy the dependencies listed in BUILDLINK_DEPENDS. -pkg. This is typically done by comparing BUILTIN_PKG.pkg against each of the -dependencies in BUILDLINK_DEPENDS.pkg. USE_BUILTIN.pkg must be set to the -correct value by the end of the builtin.mk file. Note that USE_BUILTIN.pkg may -be "yes" even if IS_BUILTIN.pkg is "no" because we may make the determination -that the built-in version of the software is similar enough to be used as a -replacement. +software is adequate to satisfy the dependencies listed in +BUILDLINK_API_DEPENDS.pkg. This is typically done by comparing BUILTIN_PKG.pkg +against each of the dependencies in BUILDLINK_API_DEPENDS.pkg. USE_BUILTIN.pkg +must be set to the correct value by the end of the builtin.mk file. Note that +USE_BUILTIN.pkg may be "yes" even if IS_BUILTIN.pkg is "no" because we may make +the determination that the built-in version of the software is similar enough +to be used as a replacement. The last section is guarded by CHECK_BUILTIN.pkg, and includes code that uses the value of USE_BUILTIN.pkg set in the previous section. This typically @@ -3813,24 +3829,28 @@ If a package needs to create special users and/or groups during installation, it can do so by using the pkginstall framework. Users can be created by adding entries to the PKG_USERS variable. Each entry -has the following syntax, which mimics /etc/passwd: +has the following syntax: - user:group[:[userid][:[descr][:[home][:shell]]]] + user:group -Only the user and group are required; everything else is optional, but the -colons must be in the right places when specifying optional bits. By default, a -new user will have home directory /nonexistent, and login shell /sbin/nologin -unless they are specified as part of the user element. Note that if the -description contains spaces, then spaces should be backslash-escaped, as in: +Further specification of user details may be done by setting per-user +variables. PKG_UID.user is the numeric UID for the user. PKG_GECOS.user is the +user's description or comment. PKG_HOME.user is the user's home directory, and +defaults to /nonexistent if not specified. PKG_SHELL.user is the user's shell, +and defaults to /sbinno/login if not specified. - foo:foogrp::The\ Foomister +Similarly, groups can be created by adding entries to the PKG_GROUPS variable, +whose syntax is: -Similarly, groups can be created using the PKG_GROUPS variable, whose syntax -is: + group - group[:groupid] +The numeric GID of the group may be set by defining PKG_GID.group. -As before, only the group name is required; the numeric identifier is optional. +If a package needs to create the users and groups at an earlier stage, then it +can set USERGROUP_PHASE to either configure or build to indicate the phase +before which the users and groups are created. In this case, the numeric UIDs +and GIDs of the created users and groups are automatically hardcoded into the +final installation scripts. 12.5. System shells @@ -4196,7 +4216,7 @@ them using commands of the form: ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS} where ${site} varies through several possibilities in turn: first, -MASTER_SITE_OVERRIDE is tried, then the sites specified in either SITES_file if +MASTER_SITE_OVERRIDE is tried, then the sites specified in either SITES.file if defined, else MASTER_SITES or PATCH_SITES, as applies, then finally the value of MASTER_SITE_BACKUP. The order of all except the first can be optionally sorted by the user, via setting either MASTER_SORT_AWK or MASTER_SORT_REGEX. @@ -4261,7 +4281,33 @@ This is covered in Chapter 15, Tools needed for building or running. 14.10. The wrapper phase -[TODO] +This phase creates wrapper programs for the compilers and linkers. The +following variables can be used to tweak the wrappers. + +ECHO_WRAPPER_MSG + + The command used to print progress messages. Does nothing by default. Set + to ${ECHO} to see the progress messages. + +WRAPPER_DEBUG + + This variable can be set to yes (default) or no, depending on whether you + want additional information in the wrapper log file. + +WRAPPER_UPDATE_CACHE + + This variable can be set to yes or no, depending on whether the wrapper + should use its cache, which will improve the speed. The default value is + yes, but is forced to no if the platform does not support it. + +WRAPPER_REORDER_CMDS + + A list of reordering commands. A reordering command has the form reorder:l: + lib1:lib2. It ensures that that -llib1 occurs before -llib2. + +WRAPPER_TRANSFORM_CMDS + + A list of transformation commands. [TODO: investigate further] 14.11. The configure phase @@ -4903,18 +4949,18 @@ version numbers recognized by pkg_info(1). Please note that such dependencies should only be updated if a package requires a newer pre-requisite, but not to denote recommendations such as - security updates or ABI changes that do not prevent a package from building - correctly. Such recommendations can be expressed using RECOMMENDED: + ABI changes that do not prevent a package from building correctly. Such + recommendations can be expressed using ABI_DEPENDS: - RECOMMENDED+= tiff>=3.6.1:../../graphics/tiff + ABI_DEPENDS+= tiff>=3.6.1:../../graphics/tiff In addition to the above DEPENDS line, this denotes that while a package will build against tiff>=3.5.4, at least version 3.6.1 is recommended. - RECOMMENDED entries will be turned into dependencies unless explicitly + ABI_DEPENDS entries will be turned into dependencies unless explicitly ignored (in which case a warning will be printed). - To ignore these dependency recommendations and just use the required - DEPENDS, set IGNORE_RECOMMENDED=YES. This may make it easier and faster to + To ignore these ABI dependency recommendations and just use the required + DEPENDS, set USE_ABI_DEPENDS=NO. 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 @@ -4925,9 +4971,9 @@ version numbers recognized by pkg_info(1). ftp.NetBSD.org by developers and should not be used across different systems that may have different versions of binary packages installed. - For security fixes, please update the package vulnerabilities file as well - as setting RECOMMENDED, see Section 16.1.8, "Handling packages with - security problems" for more information. + For security fixes, please update the package vulnerabilities file. See + Section 16.1.8, "Handling packages with security problems" for more + information. 4. If your package needs some executable to be able to run correctly and if there's no buildlink3.mk file, this is specified using the DEPENDS @@ -5003,9 +5049,7 @@ in the same directory to update the file on ftp.NetBSD.org. After fixing the vulnerability by a patch, its PKGREVISION should be increased (this is of course not necessary if the problem is fixed by using a newer -release of the software). In addition, if a buildlink3.mk file exists for an -affected package, a corresponding BUILDLINK_RECOMMENDED.pkg entry should be -added or updated in it. +release of the software). Also, if the fix should be applied to the stable pkgsrc branch, be sure to submit a pullup request! @@ -5494,28 +5538,24 @@ substituted for in the PLIST. 16.5.7. Packages installing info files Some packages install info files or use the "makeinfo" or "install-info" -commands. Each of the info files: - - * is considered to be installed in the directory ${PREFIX}/${INFO_DIR}, - - * is registered in the Info directory file ${PREFIX}/${INFO_DIR}/dir, +commands. INFO_FILES should be defined in the package Makefile so that INSTALL +and DEINSTALL scripts will be generated to handle registration of the info +files in the Info directory file. The "install-info" 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. - * and must be listed as a filename in the INFO_FILES variable in the package - Makefile. +PKGINFODIR is the directory under ${PREFIX} where info files are primarily +located. PKGINFODIR defaults to "info" and can be overridden by the user. -INFO_DIR defaults to "info" and can be overridden in the package Makefile. -INSTALL and DEINSTALL scripts will be generated to handle registration of the -info files in the Info directory file. The "install-info" 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. +The info files for the package should be listed in the package PLIST; however +any split info files need not be listed. -A package which needs the "makeinfo" command at build time must define the -variable USE_MAKEINFO in its Makefile. If a minimum version of the "makeinfo" -command is needed it should be noted with the TEXINFO_REQD variable in the -package Makefile. By default, a minimum version of 3.12 is required. If the -system does not provide a makeinfo command or if it does not match the required -minimum, a build dependency on the devel/gtexinfo package will be added -automatically. +A package which needs the "makeinfo" command at build time must add "makeinfo" +to USE_TOOLS in its Makefile. If a minimum version of the "makeinfo" command is +needed it should be noted with the TEXINFO_REQD variable in the package +Makefile. By default, a minimum version of 3.12 is required. If the system does +not provide a makeinfo command or if it does not match the required minimum, a +build dependency on the devel/gtexinfo package will be added automatically. The build and installation process of the software provided by the package should not use the install-info command as the registration of info files is @@ -5527,8 +5567,8 @@ the install-info and makeinfo commands in a directory listed early in PATH. The script overriding install-info has no effect except the logging of a message. The script overriding makeinfo logs a message and according to the -value of USE_MAKEINFO and TEXINFO_REQD either run the appropriate makeinfo -command or exit on error. +value of TEXINFO_REQD either runs the appropriate makeinfo command or exit on +error. 16.5.8. Packages installing man pages @@ -5967,18 +6007,161 @@ possibly untested features. (and any packages from step 5, of course). -Chapter 19. Porting pkgsrc +Chapter 19. Frequently Asked Questions + +This section contains the answers to questions that may arise when you are +writing a package. If you don't find your question answered here, first have a +look in the other chapters, and if you still don't have the answer, ask on the +pkgsrc-users mailing list. + +19.1. What is the difference between MAKEFLAGS, .MAKEFLAGS and MAKE_FLAGS? +19.2. What is the difference between MAKE, GMAKE and MAKE_PROGRAM? +19.3. What is the difference between CC, PKG_CC and PKGSRC_COMPILER? +19.4. What is the difference between BUILDLINK_LDFLAGS, BUILDLINK_LDADD and + BUILDLINK_LIBS? +19.5. Why does make show-var VARNAME=BUILDLINK_PREFIX.foo say it's empty? + +19.1. What is the difference between MAKEFLAGS, .MAKEFLAGS and MAKE_FLAGS? + + MAKEFLAGS are the flags passed to the pkgsrc-internal invocations of make + (1), while MAKE_FLAGS are the flags that are passed to the MAKE_PROGRAM + when building the package. [FIXME: What is .MAKEFLAGS for?] + +19.2. What is the difference between MAKE, GMAKE and MAKE_PROGRAM? + + MAKE is the path to the make(1) program that is used in the pkgsrc + infrastructure. GMAKE is the path to GNU Make, but you need to say + USE_TOOLS+=gmake to use that. MAKE_PROGRAM is the path to the Make + program that is used for building the package. + +19.3. What is the difference between CC, PKG_CC and PKGSRC_COMPILER? + + CC is the path to the real C compiler, which can be configured by the + pkgsrc user. PKG_CC is the path to the compiler wrapper. PKGSRC_COMPILER + is not a path to a compiler, but the type of compiler that should be + used. See mk/compiler.mk for more information about the latter variable. + +19.4. What is the difference between BUILDLINK_LDFLAGS, BUILDLINK_LDADD and + BUILDLINK_LIBS? + + [FIXME] + +19.5. Why does make show-var VARNAME=BUILDLINK_PREFIX.foo say it's empty? + + For optimization reasons, some variables are only available in the + "wrapper" phase and later. To "simulate" the wrapper phase, append + PKG_PHASE=wrapper to the above command. + +Part III. The pkgsrc infrastructure + +Table of Contents + +20. Regression tests + + 20.1. The regression tests framework + 20.2. Running the regression tests + 20.3. Adding a new regression test + + 20.3.1. Overridable functions + 20.3.2. Helper functions + +21. Porting pkgsrc + + 21.1. Porting pkgsrc to a new operating system + 21.2. Adding support for a new compiler + +Chapter 20. Regression tests + +Table of Contents + +20.1. The regression tests framework +20.2. Running the regression tests +20.3. Adding a new regression test + + 20.3.1. Overridable functions + 20.3.2. Helper functions + +The pkgsrc infrastructure consists of a large codebase, and there are many +corners where every little bit of a file is well thought out, making pkgsrc +likely to fail as soon as anything is changed near those parts. To prevent most +changes from breaking anything, a suite of regression tests should go along +with every important part of the pkgsrc infrastructure. This chapter describes +how regression tests work in pkgsrc and how you can add new tests. + +20.1. The regression tests framework + +20.2. Running the regression tests + +You first need to install the pkgtools/pkg_regress package, which provides the +pkg_regress command. Then you can simply run that command, which will run all +tests in the regress category. + +20.3. Adding a new regression test + +Every directory in the regress category that contains a file called spec is +considered a regression test. This file is a shell program that is included by +the pkg_regress command. The following functions can be overridden to suit your +needs. + +20.3.1. Overridable functions + +These functions do not take any parameters. They are all called in "set -e" +mode, so you should be careful to check the exitcodes of any commands you run +in the test. + +do_setup() + + This function prepares the environment for the test. By default it does + nothing. + +do_test() + + This function runs the actual test. By default, it calls TEST_MAKE with the + arguments MAKEARGS_TEST and writes its output including error messages into + the file TEST_OUTFILE. + +check_result() + + This function is run after the test and is typically used to compare the + actual output from the one that is expected. It can make use of the various + helper functions from the next section. + +do_cleanup() + + This function cleans everything up after the test has been run. By default + it does nothing. + +20.3.2. Helper functions + +exit_status(expected) + + This function compares the exitcode of the do_test() function with its + first parameter. If they differ, the test will fail. + +output_require(regex...) + + This function checks for each of its parameters if the output from do_test + () matches the extended regular expression. If it does not, the test will + fail. + +output_prohibit(regex...) + + This function checks for each of its parameters if the output from do_test + () does not match the extended regular expression. If any of the regular + expressions matches, the test will fail. + +Chapter 21. Porting pkgsrc Table of Contents -19.1. Porting pkgsrc to a new operating system -19.2. Adding support for a new compiler +21.1. Porting pkgsrc to a new operating system +21.2. Adding support for a new compiler The pkgsrc system has already been ported to many operating systems, hardware architectures and compilers. This chapter explains the necessary steps to make pkgsrc even more portable. -19.1. Porting pkgsrc to a new operating system +21.1. Porting pkgsrc to a new operating system To port pkgsrc to a new operating system (called MyOS in this example), you need to touch the following files: @@ -6026,7 +6209,7 @@ mk/tools/MyOS.mk Now, you should be able to build some basic packages, like lang/perl5, shells/ bash. -19.2. Adding support for a new compiler +21.2. Adding support for a new compiler TODO |