Sat Jan 11 12:36:56 2020 UTC ()
doc/pkgsrc.*: regen


(rillig)
diff -r1.282 -r1.283 pkgsrc/doc/pkgsrc.html
diff -r1.280 -r1.281 pkgsrc/doc/pkgsrc.txt

cvs diff -r1.282 -r1.283 pkgsrc/doc/pkgsrc.html (expand / switch to unified diff)

--- pkgsrc/doc/pkgsrc.html 2020/01/06 21:35:51 1.282
+++ pkgsrc/doc/pkgsrc.html 2020/01/11 12:36:55 1.283
@@ -9020,27 +9020,27 @@ place.

 @@ -9020,27 +9020,27 @@ place.

9020</li> 9020</li>
9021</ol></div> 9021</ol></div>
9022</div> 9022</div>
9023</div> 9023</div>
9024<div class="chapter"> 9024<div class="chapter">
9025<div class="titlepage"><div><div><h2 class="title"> 9025<div class="titlepage"><div><div><h2 class="title">
9026<a name="devfaq"></a>Chapter 24. Frequently Asked Questions</h2></div></div></div> 9026<a name="devfaq"></a>Chapter 24. Frequently Asked Questions</h2></div></div></div>
9027<p>This section contains the answers to questions that may 9027<p>This section contains the answers to questions that may
9028 arise when you are writing a package. If you don't find your 9028 arise when you are writing a package. If you don't find your
9029 question answered here, first have a look in the other chapters, 9029 question answered here, first have a look in the other chapters,
9030 and if you still don't have the answer, ask on the 9030 and if you still don't have the answer, ask on the
9031 <code class="literal">pkgsrc-users</code> mailing list.</p> 9031 <code class="literal">pkgsrc-users</code> mailing list.</p>
9032<div class="qandaset"> 9032<div class="qandaset">
9033<a name="idm75601104"></a><dl> 9033<a name="idm79113968"></a><dl>
9034<dt>24.1. <a href="#devfaq.makeflags">What is the difference between 9034<dt>24.1. <a href="#devfaq.makeflags">What is the difference between
9035 MAKEFLAGS, .MAKEFLAGS and 9035 MAKEFLAGS, .MAKEFLAGS and
9036 MAKE_FLAGS?</a> 9036 MAKE_FLAGS?</a>
9037</dt> 9037</dt>
9038<dt>24.2. <a href="#devfaq.make">What is the difference between 9038<dt>24.2. <a href="#devfaq.make">What is the difference between
9039 MAKE, GMAKE and 9039 MAKE, GMAKE and
9040 MAKE_PROGRAM?</a> 9040 MAKE_PROGRAM?</a>
9041</dt> 9041</dt>
9042<dt>24.3. <a href="#devfaq.cc">What is the difference between 9042<dt>24.3. <a href="#devfaq.cc">What is the difference between
9043 CC, PKG_CC and 9043 CC, PKG_CC and
9044 PKGSRC_COMPILER?</a> 9044 PKGSRC_COMPILER?</a>
9045</dt> 9045</dt>
9046<dt>24.4. <a href="#devfaq.bl3flags">What is the difference between 9046<dt>24.4. <a href="#devfaq.bl3flags">What is the difference between
@@ -9065,157 +9065,157 @@ place.

 @@ -9065,157 +9065,157 @@ place.

9065</dt> 9065</dt>
9066<dt>24.9. <a href="#devfaq.too-much-time">I have a little time to kill. What shall I 9066<dt>24.9. <a href="#devfaq.too-much-time">I have a little time to kill. What shall I
9067do?</a> 9067do?</a>
9068</dt> 9068</dt>
9069</dl> 9069</dl>
9070<table border="0" style="width: 100%;"> 9070<table border="0" style="width: 100%;">
9071<colgroup> 9071<colgroup>
9072<col align="left" width="1%"> 9072<col align="left" width="1%">
9073<col> 9073<col>
9074</colgroup> 9074</colgroup>
9075<tbody> 9075<tbody>
9076<tr class="question"> 9076<tr class="question">
9077<td align="left" valign="top"> 9077<td align="left" valign="top">
9078<a name="devfaq.makeflags"></a><a name="idm75600720"></a><p><b>24.1.</b></p> 9078<a name="devfaq.makeflags"></a><a name="idm79113584"></a><p><b>24.1.</b></p>
9079</td> 9079</td>
9080<td align="left" valign="top"><p>What is the difference between 9080<td align="left" valign="top"><p>What is the difference between
9081 <code class="varname">MAKEFLAGS</code>, <code class="varname">.MAKEFLAGS</code> and 9081 <code class="varname">MAKEFLAGS</code>, <code class="varname">.MAKEFLAGS</code> and
9082 <code class="varname">MAKE_FLAGS</code>?</p></td> 9082 <code class="varname">MAKE_FLAGS</code>?</p></td>
9083</tr> 9083</tr>
9084<tr class="answer"> 9084<tr class="answer">
9085<td align="left" valign="top"></td> 9085<td align="left" valign="top"></td>
9086<td align="left" valign="top"><p><code class="varname">MAKEFLAGS</code> are the flags passed 9086<td align="left" valign="top"><p><code class="varname">MAKEFLAGS</code> are the flags passed
9087 to the pkgsrc-internal invocations of <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>, while 9087 to the pkgsrc-internal invocations of <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a>, while
9088 <code class="varname">MAKE_FLAGS</code> are the flags that are passed to 9088 <code class="varname">MAKE_FLAGS</code> are the flags that are passed to
9089 the <code class="varname">MAKE_PROGRAM</code> when building the 9089 the <code class="varname">MAKE_PROGRAM</code> when building the
9090 package. [FIXME: What is .MAKEFLAGS for?]</p></td> 9090 package. [FIXME: What is .MAKEFLAGS for?]</p></td>
9091</tr> 9091</tr>
9092<tr class="question"> 9092<tr class="question">
9093<td align="left" valign="top"> 9093<td align="left" valign="top">
9094<a name="devfaq.make"></a><a name="idm75604944"></a><p><b>24.2.</b></p> 9094<a name="devfaq.make"></a><a name="idm79109488"></a><p><b>24.2.</b></p>
9095</td> 9095</td>
9096<td align="left" valign="top"><p>What is the difference between 9096<td align="left" valign="top"><p>What is the difference between
9097 <code class="varname">MAKE</code>, <code class="varname">GMAKE</code> and 9097 <code class="varname">MAKE</code>, <code class="varname">GMAKE</code> and
9098 <code class="varname">MAKE_PROGRAM</code>?</p></td> 9098 <code class="varname">MAKE_PROGRAM</code>?</p></td>
9099</tr> 9099</tr>
9100<tr class="answer"> 9100<tr class="answer">
9101<td align="left" valign="top"></td> 9101<td align="left" valign="top"></td>
9102<td align="left" valign="top"><p><code class="varname">MAKE</code> is the path to the 9102<td align="left" valign="top"><p><code class="varname">MAKE</code> is the path to the
9103 <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> program that is used in the pkgsrc 9103 <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> program that is used in the pkgsrc
9104 infrastructure. <code class="varname">GMAKE</code> is the path to GNU 9104 infrastructure. <code class="varname">GMAKE</code> is the path to GNU
9105 Make, but you need to say <code class="varname">USE_TOOLS+=gmake</code> to 9105 Make, but you need to say <code class="varname">USE_TOOLS+=gmake</code> to
9106 use that. <code class="varname">MAKE_PROGRAM</code> is the path to the 9106 use that. <code class="varname">MAKE_PROGRAM</code> is the path to the
9107 Make program that is used for building the 9107 Make program that is used for building the
9108 package.</p></td> 9108 package.</p></td>
9109</tr> 9109</tr>
9110<tr class="question"> 9110<tr class="question">
9111<td align="left" valign="top"> 9111<td align="left" valign="top">
9112<a name="devfaq.cc"></a><a name="idm75608784"></a><p><b>24.3.</b></p> 9112<a name="devfaq.cc"></a><a name="idm79105136"></a><p><b>24.3.</b></p>
9113</td> 9113</td>
9114<td align="left" valign="top"><p>What is the difference between 9114<td align="left" valign="top"><p>What is the difference between
9115 <code class="varname">CC</code>, <code class="varname">PKG_CC</code> and 9115 <code class="varname">CC</code>, <code class="varname">PKG_CC</code> and
9116 <code class="varname">PKGSRC_COMPILER</code>?</p></td> 9116 <code class="varname">PKGSRC_COMPILER</code>?</p></td>
9117</tr> 9117</tr>
9118<tr class="answer"> 9118<tr class="answer">
9119<td align="left" valign="top"></td> 9119<td align="left" valign="top"></td>
9120<td align="left" valign="top"><p><code class="varname">CC</code> is the path to the real C 9120<td align="left" valign="top"><p><code class="varname">CC</code> is the path to the real C
9121 compiler, which can be configured by the pkgsrc user. 9121 compiler, which can be configured by the pkgsrc user.
9122 <code class="varname">PKG_CC</code> is the path to the compiler wrapper. 9122 <code class="varname">PKG_CC</code> is the path to the compiler wrapper.
9123 <code class="varname">PKGSRC_COMPILER</code> is <span class="emphasis"><em>not</em></span> a 9123 <code class="varname">PKGSRC_COMPILER</code> is <span class="emphasis"><em>not</em></span> a
9124 path to a compiler, but the type of compiler that should be 9124 path to a compiler, but the type of compiler that should be
9125 used. See <code class="filename">mk/compiler.mk</code> for more 9125 used. See <code class="filename">mk/compiler.mk</code> for more
9126 information about the latter variable.</p></td> 9126 information about the latter variable.</p></td>
9127</tr> 9127</tr>
9128<tr class="question"> 9128<tr class="question">
9129<td align="left" valign="top"> 9129<td align="left" valign="top">
9130<a name="devfaq.bl3flags"></a><a name="idm75612880"></a><p><b>24.4.</b></p> 9130<a name="devfaq.bl3flags"></a><a name="idm79100912"></a><p><b>24.4.</b></p>
9131</td> 9131</td>
9132<td align="left" valign="top"><p>What is the difference between 9132<td align="left" valign="top"><p>What is the difference between
9133 <code class="varname">BUILDLINK_LDFLAGS</code>, 9133 <code class="varname">BUILDLINK_LDFLAGS</code>,
9134 <code class="varname">BUILDLINK_LDADD</code> and 9134 <code class="varname">BUILDLINK_LDADD</code> and
9135 <code class="varname">BUILDLINK_LIBS</code>?</p></td> 9135 <code class="varname">BUILDLINK_LIBS</code>?</p></td>
9136</tr> 9136</tr>
9137<tr class="answer"> 9137<tr class="answer">
9138<td align="left" valign="top"></td> 9138<td align="left" valign="top"></td>
9139<td align="left" valign="top"><p>[FIXME]</p></td> 9139<td align="left" valign="top"><p>[FIXME]</p></td>
9140</tr> 9140</tr>
9141<tr class="question"> 9141<tr class="question">
9142<td align="left" valign="top"> 9142<td align="left" valign="top">
9143<a name="devfaq.bl3prefix"></a><a name="idm75610704"></a><p><b>24.5.</b></p> 9143<a name="devfaq.bl3prefix"></a><a name="idm79098736"></a><p><b>24.5.</b></p>
9144</td> 9144</td>
9145<td align="left" valign="top"><p>Why does <span class="command"><strong>make show-var 9145<td align="left" valign="top"><p>Why does <span class="command"><strong>make show-var
9146 VARNAME=BUILDLINK_PREFIX.<em class="replaceable"><code>foo</code></em></strong></span> 9146 VARNAME=BUILDLINK_PREFIX.<em class="replaceable"><code>foo</code></em></strong></span>
9147 say it's empty?</p></td> 9147 say it's empty?</p></td>
9148</tr> 9148</tr>
9149<tr class="answer"> 9149<tr class="answer">
9150<td align="left" valign="top"></td> 9150<td align="left" valign="top"></td>
9151<td align="left" valign="top"><p>For optimization reasons, some variables are only 9151<td align="left" valign="top"><p>For optimization reasons, some variables are only
9152 available in the <span class="quote">&#8220;<span class="quote">wrapper</span>&#8221;</span> phase and later. To 9152 available in the <span class="quote">&#8220;<span class="quote">wrapper</span>&#8221;</span> phase and later. To
9153 <span class="quote">&#8220;<span class="quote">simulate</span>&#8221;</span> the wrapper phase, append 9153 <span class="quote">&#8220;<span class="quote">simulate</span>&#8221;</span> the wrapper phase, append
9154 <span class="command"><strong>PKG_PHASE=wrapper</strong></span> to the above 9154 <span class="command"><strong>PKG_PHASE=wrapper</strong></span> to the above
9155 command.</p></td> 9155 command.</p></td>
9156</tr> 9156</tr>
9157<tr class="question"> 9157<tr class="question">
9158<td align="left" valign="top"> 9158<td align="left" valign="top">
9159<a name="devfaq.master_sites"></a><a name="idm75615824"></a><p><b>24.6.</b></p> 9159<a name="devfaq.master_sites"></a><a name="idm79095536"></a><p><b>24.6.</b></p>
9160</td> 9160</td>
9161<td align="left" valign="top"><p>What does 9161<td align="left" valign="top"><p>What does
9162 <code class="code">${MASTER_SITE_SOURCEFORGE:=package/}</code> mean? I 9162 <code class="code">${MASTER_SITE_SOURCEFORGE:=package/}</code> mean? I
9163 don't understand the <code class="code">:=</code> inside 9163 don't understand the <code class="code">:=</code> inside
9164 it.</p></td> 9164 it.</p></td>
9165</tr> 9165</tr>
9166<tr class="answer"> 9166<tr class="answer">
9167<td align="left" valign="top"></td> 9167<td align="left" valign="top"></td>
9168<td align="left" valign="top"><p>The <code class="code">:=</code> is not really an 9168<td align="left" valign="top"><p>The <code class="code">:=</code> is not really an
9169 assignment operator, although it looks like it. 9169 assignment operator, although it looks like it.
9170 Instead, it is a degenerate form of 9170 Instead, it is a degenerate form of
9171 <code class="code">${LIST:<em class="replaceable"><code>old_string</code></em>=<em class="replaceable"><code>new_string</code></em>}</code>, 9171 <code class="code">${LIST:<em class="replaceable"><code>old_string</code></em>=<em class="replaceable"><code>new_string</code></em>}</code>,
9172 which is documented in the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> man page and which is 9172 which is documented in the <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?make+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> man page and which is
9173 commonly used in the form <code class="code">${SRCS:.c=.o}</code>. In the 9173 commonly used in the form <code class="code">${SRCS:.c=.o}</code>. In the
9174 case of <code class="varname">MASTER_SITE_*</code>, 9174 case of <code class="varname">MASTER_SITE_*</code>,
9175 <em class="replaceable"><code>old_string</code></em> is the empty string and 9175 <em class="replaceable"><code>old_string</code></em> is the empty string and
9176 <em class="replaceable"><code>new_string</code></em> is 9176 <em class="replaceable"><code>new_string</code></em> is
9177 <code class="code">package/</code>. That's where the 9177 <code class="code">package/</code>. That's where the
9178 <code class="code">:</code> and the <code class="code">=</code> fall 9178 <code class="code">:</code> and the <code class="code">=</code> fall
9179 together.</p></td> 9179 together.</p></td>
9180</tr> 9180</tr>
9181<tr class="question"> 9181<tr class="question">
9182<td align="left" valign="top"> 9182<td align="left" valign="top">
9183<a name="devfaq.mailinglists"></a><a name="idm75625424"></a><p><b>24.7.</b></p> 9183<a name="devfaq.mailinglists"></a><a name="idm79088752"></a><p><b>24.7.</b></p>
9184</td> 9184</td>
9185<td align="left" valign="top"><p>Which mailing lists are there for package 9185<td align="left" valign="top"><p>Which mailing lists are there for package
9186 developers?</p></td> 9186 developers?</p></td>
9187</tr> 9187</tr>
9188<tr class="answer"> 9188<tr class="answer">
9189<td align="left" valign="top"></td> 9189<td align="left" valign="top"></td>
9190<td align="left" valign="top"><div class="variablelist"><dl class="variablelist"> 9190<td align="left" valign="top"><div class="variablelist"><dl class="variablelist">
9191<dt><span class="term"><a class="ulink" href="http://www.NetBSD.org/mailinglists/index.html#tech-pkg" target="_top">tech-pkg</a></span></dt> 9191<dt><span class="term"><a class="ulink" href="http://www.NetBSD.org/mailinglists/index.html#tech-pkg" target="_top">tech-pkg</a></span></dt>
9192<dd><p>This is a list for technical discussions related 9192<dd><p>This is a list for technical discussions related
9193 to pkgsrc development, e.g. soliciting feedback for changes to 9193 to pkgsrc development, e.g. soliciting feedback for changes to
9194 pkgsrc infrastructure, proposed new features, questions related 9194 pkgsrc infrastructure, proposed new features, questions related
9195 to porting pkgsrc to a new platform, advice for maintaining a 9195 to porting pkgsrc to a new platform, advice for maintaining a
9196 package, patches that affect many packages, help requests moved 9196 package, patches that affect many packages, help requests moved
9197 from pkgsrc-users when an infrastructure bug is found, 9197 from pkgsrc-users when an infrastructure bug is found,
9198 etc.</p></dd> 9198 etc.</p></dd>
9199<dt><span class="term"><a class="ulink" href="http://www.NetBSD.org/mailinglists/index.html#pkgsrc-bugs" target="_top">pkgsrc-bugs</a></span></dt> 9199<dt><span class="term"><a class="ulink" href="http://www.NetBSD.org/mailinglists/index.html#pkgsrc-bugs" target="_top">pkgsrc-bugs</a></span></dt>
9200<dd><p>All bug reports in category "pkg" sent with 9200<dd><p>All bug reports in category "pkg" sent with
9201 <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">send-pr</span>(1)</span></a> appear here. Please do not report your bugs here 9201 <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1.i386+NetBSD-8.1"><span class="citerefentry"><span class="refentrytitle">send-pr</span>(1)</span></a> appear here. Please do not report your bugs here
9202 directly; use one of the other mailing 9202 directly; use one of the other mailing
9203 lists.</p></dd> 9203 lists.</p></dd>
9204</dl></div></td> 9204</dl></div></td>
9205</tr> 9205</tr>
9206<tr class="question"> 9206<tr class="question">
9207<td align="left" valign="top"> 9207<td align="left" valign="top">
9208<a name="devfaq.documentation"></a><a name="idm75629904"></a><p><b>24.8.</b></p> 9208<a name="devfaq.documentation"></a><a name="idm79076720"></a><p><b>24.8.</b></p>
9209</td> 9209</td>
9210<td align="left" valign="top"><p>Where is the pkgsrc 9210<td align="left" valign="top"><p>Where is the pkgsrc
9211 documentation?</p></td> 9211 documentation?</p></td>
9212</tr> 9212</tr>
9213<tr class="answer"> 9213<tr class="answer">
9214<td align="left" valign="top"></td> 9214<td align="left" valign="top"></td>
9215<td align="left" valign="top"> 9215<td align="left" valign="top">
9216<p>There are many places where you can find 9216<p>There are many places where you can find
9217 documentation about pkgsrc:</p> 9217 documentation about pkgsrc:</p>
9218<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 9218<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
9219<li class="listitem"><p>The pkgsrc guide (this document) is a collection 9219<li class="listitem"><p>The pkgsrc guide (this document) is a collection
9220 of chapters that explain large parts of pkgsrc, but some 9220 of chapters that explain large parts of pkgsrc, but some
9221 chapters tend to be outdated. Which ones they are is hard to 9221 chapters tend to be outdated. Which ones they are is hard to
@@ -9243,27 +9243,27 @@ do? @@ -9243,27 +9243,27 @@ do?
9243 documented</span>&#8221;</span>, that is the documentation exists only in the 9243 documented</span>&#8221;</span>, that is the documentation exists only in the
9244 mind of the developer who wrote the code. To get this 9244 mind of the developer who wrote the code. To get this
9245 information, use the <span class="command"><strong>cvs annotate</strong></span> command 9245 information, use the <span class="command"><strong>cvs annotate</strong></span> command
9246 to see who has written it and ask on the 9246 to see who has written it and ask on the
9247 <code class="literal">tech-pkg</code> mailing list, so that others can 9247 <code class="literal">tech-pkg</code> mailing list, so that others can
9248 find your questions later (see above). To be sure that the 9248 find your questions later (see above). To be sure that the
9249 developer in charge reads the mail, you may CC him or 9249 developer in charge reads the mail, you may CC him or
9250 her.</p></li> 9250 her.</p></li>
9251</ul></div> 9251</ul></div>
9252</td> 9252</td>
9253</tr> 9253</tr>
9254<tr class="question"> 9254<tr class="question">
9255<td align="left" valign="top"> 9255<td align="left" valign="top">
9256<a name="devfaq.too-much-time"></a><a name="idm75631696"></a><p><b>24.9.</b></p> 9256<a name="devfaq.too-much-time"></a><a name="idm79070192"></a><p><b>24.9.</b></p>
9257</td> 9257</td>
9258<td align="left" valign="top"><p>I have a little time to kill. What shall I 9258<td align="left" valign="top"><p>I have a little time to kill. What shall I
9259do?</p></td> 9259do?</p></td>
9260</tr> 9260</tr>
9261<tr class="answer"> 9261<tr class="answer">
9262<td align="left" valign="top"></td> 9262<td align="left" valign="top"></td>
9263<td align="left" valign="top"> 9263<td align="left" valign="top">
9264<p>This is not really an FAQ yet, but here's the answer 9264<p>This is not really an FAQ yet, but here's the answer
9265anyway.</p> 9265anyway.</p>
9266<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 9266<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
9267<li class="listitem"><p>Run <span class="command"><strong>pkg_chk -N</strong></span> (from the 9267<li class="listitem"><p>Run <span class="command"><strong>pkg_chk -N</strong></span> (from the
9268 <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkg_chk/README.html" target="_top"><code class="filename">pkgtools/pkg_chk</code></a> package). It 9268 <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkg_chk/README.html" target="_top"><code class="filename">pkgtools/pkg_chk</code></a> package). It
9269 will tell you about newer versions of installed packages that are 9269 will tell you about newer versions of installed packages that are
@@ -9921,43 +9921,43 @@ CFLAGS+= -Wall @@ -9921,43 +9921,43 @@ CFLAGS+= -Wall
9921 and there are many corners where every little bit of a file is 9921 and there are many corners where every little bit of a file is
9922 well thought out, making pkgsrc likely to fail as soon as 9922 well thought out, making pkgsrc likely to fail as soon as
9923 anything is changed near those parts. To prevent most changes 9923 anything is changed near those parts. To prevent most changes
9924 from breaking anything, a suite of regression tests should go 9924 from breaking anything, a suite of regression tests should go
9925 along with every important part of the pkgsrc infrastructure. 9925 along with every important part of the pkgsrc infrastructure.
9926 This chapter describes how regression tests work in pkgsrc and 9926 This chapter describes how regression tests work in pkgsrc and
9927 how you can add new tests.</p> 9927 how you can add new tests.</p>
9928<div class="sect1"> 9928<div class="sect1">
9929<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 9929<div class="titlepage"><div><div><h2 class="title" style="clear: both">
9930<a name="regression.run"></a>27.1. Running the regression tests</h2></div></div></div> 9930<a name="regression.run"></a>27.1. Running the regression tests</h2></div></div></div>
9931<p>You first need to install the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkg_regress/README.html" target="_top"><code class="filename">pkgtools/pkg_regress</code></a> package, which 9931<p>You first need to install the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkg_regress/README.html" target="_top"><code class="filename">pkgtools/pkg_regress</code></a> package, which
9932 provides the <span class="command"><strong>pkg_regress</strong></span> command. Then you 9932 provides the <span class="command"><strong>pkg_regress</strong></span> command. Then you
9933 can simply run that command, which will run all tests in the 9933 can simply run that command, which will run all tests in the
9934 <code class="filename">regress</code> category.</p> 9934 <code class="filename">regress/</code> directory.</p>
9935</div> 9935</div>
9936<div class="sect1"> 9936<div class="sect1">
9937<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 9937<div class="titlepage"><div><div><h2 class="title" style="clear: both">
9938<a name="regression.new"></a>27.2. Adding a new regression test</h2></div></div></div> 9938<a name="regression.new"></a>27.2. Adding a new regression test</h2></div></div></div>
9939<p>Every directory in the <code class="filename">regress</code> 9939<p>Every directory in the <code class="filename">regress/</code>
9940 category that contains a file called <code class="filename">spec</code> 9940 directory that contains a file called <code class="filename">spec</code>
9941 is considered a regression test. This file is a shell program 9941 is considered a regression test. This file is a shell program
9942 that is included by the <span class="command"><strong>pkg_regress</strong></span> command. 9942 that is included by the <span class="command"><strong>pkg_regress</strong></span> command.
9943 The following functions can be overridden to suit your 9943 The following functions can be overridden to suit your
9944 needs.</p> 9944 needs.</p>
9945<div class="sect2"> 9945<div class="sect2">
9946<div class="titlepage"><div><div><h3 class="title"> 9946<div class="titlepage"><div><div><h3 class="title">
9947<a name="regression.fun.override"></a>27.2.1. Overridable functions</h3></div></div></div> 9947<a name="regression.fun.override"></a>27.2.1. Overridable functions</h3></div></div></div>
9948<p>These functions do not take any parameters. Although they 9948<p>These functions do not take any parameters. Although they
9949 are called in <span class="quote">&#8220;<span class="quote">set -e</span>&#8221;</span> mode, they don't stop at the 9949 are called in <span class="quote">&#8220;<span class="quote">set -e</span>&#8221;</span> mode, they don't stop at the
9950 first failing command. See <a class="ulink" href="http://stackoverflow.com/q/4072984" target="_top">this StackOverflow 9950 first failing command. See <a class="ulink" href="http://stackoverflow.com/q/4072984" target="_top">this Stack Overflow
9951 question</a> for details.</p> 9951 question</a> for details.</p>
9952<div class="variablelist"><dl class="variablelist"> 9952<div class="variablelist"><dl class="variablelist">
9953<dt><span class="term"><code class="varname">do_setup</code></span></dt> 9953<dt><span class="term"><code class="varname">do_setup</code></span></dt>
9954<dd><p>This function prepares the environment for the 9954<dd><p>This function prepares the environment for the
9955 test. By default it does nothing.</p></dd> 9955 test. By default it does nothing.</p></dd>
9956<dt><span class="term"><code class="varname">do_test</code></span></dt> 9956<dt><span class="term"><code class="varname">do_test</code></span></dt>
9957<dd> 9957<dd>
9958<p>This function runs the actual test. By default, 9958<p>This function runs the actual test. By default,
9959 it calls <code class="varname">TEST_MAKE</code> with the arguments 9959 it calls <code class="varname">TEST_MAKE</code> with the arguments
9960 <code class="varname">MAKEARGS_TEST</code> and writes its output including 9960 <code class="varname">MAKEARGS_TEST</code> and writes its output including
9961 error messages into the file 9961 error messages into the file
9962 <code class="varname">TEST_OUTFILE</code>.</p> 9962 <code class="varname">TEST_OUTFILE</code>.</p>
9963<p>When defining this function, make sure that all output that 9963<p>When defining this function, make sure that all output that
@@ -9971,38 +9971,41 @@ do_test() { @@ -9971,38 +9971,41 @@ do_test() {
9971</dd> 9971</dd>
9972<dt><span class="term"><code class="varname">check_result</code></span></dt> 9972<dt><span class="term"><code class="varname">check_result</code></span></dt>
9973<dd> 9973<dd>
9974<p>This function is run after the test and is 9974<p>This function is run after the test and is
9975 typically used to compare the actual output from the one that is 9975 typically used to compare the actual output from the one that is
9976 expected. It can make use of the various helper functions from 9976 expected. It can make use of the various helper functions from
9977 the next section. Example:</p> 9977 the next section. Example:</p>
9978<pre class="programlisting"> 9978<pre class="programlisting">
9979check_result() { 9979check_result() {
9980 exit_status 0 9980 exit_status 0
9981 output_require "Example" 9981 output_require "Example"
9982 output_require "^[[:alpha:]+[[:space:]][[:alpha:]]{6}$" 9982 output_require "^[[:alpha:]+[[:space:]][[:alpha:]]{6}$"
9983 output_prohibit "no such file or directory" 9983 output_prohibit "no such file or directory"
 9984 regress_fail "expected $expected but got $actual for input $input"
9984} 9985}
9985</pre> 9986</pre>
9986</dd> 9987</dd>
9987<dt><span class="term"><code class="varname">do_cleanup</code></span></dt> 9988<dt><span class="term"><code class="varname">do_cleanup</code></span></dt>
9988<dd><p>This function cleans everything up after the 9989<dd><p>This function cleans everything up after the
9989 test has been run. By default it does nothing.</p></dd> 9990 test has been run. By default it does nothing.</p></dd>
9990</dl></div> 9991</dl></div>
9991</div> 9992</div>
9992<div class="sect2"> 9993<div class="sect2">
9993<div class="titlepage"><div><div><h3 class="title"> 9994<div class="titlepage"><div><div><h3 class="title">
9994<a name="regression.fun.helper"></a>27.2.2. Helper functions</h3></div></div></div> 9995<a name="regression.fun.helper"></a>27.2.2. Helper functions</h3></div></div></div>
9995<div class="variablelist"><dl class="variablelist"> 9996<div class="variablelist"><dl class="variablelist">
 9997<dt><span class="term"><code class="varname">regress_fail <em class="replaceable"><code>message...</code></em></code></span></dt>
 9998<dd><p>This function makes the test fail with the given error message.</p></dd>
9996<dt><span class="term"><code class="varname">exit_status expected</code></span></dt> 9999<dt><span class="term"><code class="varname">exit_status expected</code></span></dt>
9997<dd><p>This function compares the exitcode of the 10000<dd><p>This function compares the exitcode of the
9998 <span class="command"><strong>do_test</strong></span> function with its first parameter. 10001 <span class="command"><strong>do_test</strong></span> function with its first parameter.
9999 If they differ, the test will fail.</p></dd> 10002 If they differ, the test will fail.</p></dd>
10000<dt><span class="term"><code class="varname">output_require regex...</code></span></dt> 10003<dt><span class="term"><code class="varname">output_require regex...</code></span></dt>
10001<dd> 10004<dd>
10002<p>This function checks for each of its parameters 10005<p>This function checks for each of its parameters
10003 if the output from <span class="command"><strong>do_test</strong></span> matches the 10006 if the output from <span class="command"><strong>do_test</strong></span> matches the
10004 extended regular expression. If it does not, the test will 10007 extended regular expression. If it does not, the test will
10005 fail. Example:</p> 10008 fail. Example:</p>
10006<pre class="programlisting"> 10009<pre class="programlisting">
10007output_require "looks fine" 10010output_require "looks fine"
10008output_require "^[[:alpha:]+[[:space:]][[:alpha:]]{6}$" 10011output_require "^[[:alpha:]+[[:space:]][[:alpha:]]{6}$"

cvs diff -r1.280 -r1.281 pkgsrc/doc/pkgsrc.txt (expand / switch to unified diff)

--- pkgsrc/doc/pkgsrc.txt 2020/01/06 21:35:51 1.280
+++ pkgsrc/doc/pkgsrc.txt 2020/01/11 12:36:55 1.281
@@ -8035,39 +8035,39 @@ Table of Contents @@ -8035,39 +8035,39 @@ Table of Contents
8035 27.2.2. Helper functions 8035 27.2.2. Helper functions
8036 8036
8037The pkgsrc infrastructure consists of a large codebase, and there are many 8037The pkgsrc infrastructure consists of a large codebase, and there are many
8038corners where every little bit of a file is well thought out, making pkgsrc 8038corners where every little bit of a file is well thought out, making pkgsrc
8039likely to fail as soon as anything is changed near those parts. To prevent most 8039likely to fail as soon as anything is changed near those parts. To prevent most
8040changes from breaking anything, a suite of regression tests should go along 8040changes from breaking anything, a suite of regression tests should go along
8041with every important part of the pkgsrc infrastructure. This chapter describes 8041with every important part of the pkgsrc infrastructure. This chapter describes
8042how regression tests work in pkgsrc and how you can add new tests. 8042how regression tests work in pkgsrc and how you can add new tests.
8043 8043
804427.1. Running the regression tests 804427.1. Running the regression tests
8045 8045
8046You first need to install the pkgtools/pkg_regress package, which provides the  8046You first need to install the pkgtools/pkg_regress package, which provides the
8047pkg_regress command. Then you can simply run that command, which will run all 8047pkg_regress command. Then you can simply run that command, which will run all
8048tests in the regress category. 8048tests in the regress/ directory.
8049 8049
805027.2. Adding a new regression test 805027.2. Adding a new regression test
8051 8051
8052Every directory in the regress category that contains a file called spec is 8052Every directory in the regress/ directory that contains a file called spec is
8053considered a regression test. This file is a shell program that is included by 8053considered a regression test. This file is a shell program that is included by
8054the pkg_regress command. The following functions can be overridden to suit your 8054the pkg_regress command. The following functions can be overridden to suit your
8055needs. 8055needs.
8056 8056
805727.2.1. Overridable functions 805727.2.1. Overridable functions
8058 8058
8059These functions do not take any parameters. Although they are called in "set -e 8059These functions do not take any parameters. Although they are called in "set -e
8060" mode, they don't stop at the first failing command. See this StackOverflow 8060" mode, they don't stop at the first failing command. See this Stack Overflow
8061question for details. 8061question for details.
8062 8062
8063do_setup 8063do_setup
8064 8064
8065 This function prepares the environment for the test. By default it does 8065 This function prepares the environment for the test. By default it does
8066 nothing. 8066 nothing.
8067 8067
8068do_test 8068do_test
8069 8069
8070 This function runs the actual test. By default, it calls TEST_MAKE with the 8070 This function runs the actual test. By default, it calls TEST_MAKE with the
8071 arguments MAKEARGS_TEST and writes its output including error messages into 8071 arguments MAKEARGS_TEST and writes its output including error messages into
8072 the file TEST_OUTFILE. 8072 the file TEST_OUTFILE.
8073 8073
@@ -8088,26 +8088,30 @@ check_result @@ -8088,26 +8088,30 @@ check_result
8088 exit_status 0 8088 exit_status 0
8089 output_require "Example" 8089 output_require "Example"
8090 output_require "^[[:alpha:]+[[:space:]][[:alpha:]]{6}$" 8090 output_require "^[[:alpha:]+[[:space:]][[:alpha:]]{6}$"
8091 output_prohibit "no such file or directory" 8091 output_prohibit "no such file or directory"
8092 } 8092 }
8093 8093
8094do_cleanup 8094do_cleanup
8095 8095
8096 This function cleans everything up after the test has been run. By default 8096 This function cleans everything up after the test has been run. By default
8097 it does nothing. 8097 it does nothing.
8098 8098
809927.2.2. Helper functions 809927.2.2. Helper functions
8100 8100
 8101regress_fail message...
 8102
 8103 This function makes the test fail with the given error message.
 8104
8101exit_status expected 8105exit_status expected
8102 8106
8103 This function compares the exitcode of the do_test function with its first 8107 This function compares the exitcode of the do_test function with its first
8104 parameter. If they differ, the test will fail. 8108 parameter. If they differ, the test will fail.
8105 8109
8106output_require regex... 8110output_require regex...
8107 8111
8108 This function checks for each of its parameters if the output from do_test 8112 This function checks for each of its parameters if the output from do_test
8109 matches the extended regular expression. If it does not, the test will 8113 matches the extended regular expression. If it does not, the test will
8110 fail. Example: 8114 fail. Example:
8111 8115
8112 output_require "looks fine" 8116 output_require "looks fine"
8113 output_require "^[[:alpha:]+[[:space:]][[:alpha:]]{6}$" 8117 output_require "^[[:alpha:]+[[:space:]][[:alpha:]]{6}$"