Annotation of www/porttest.html, Revision 1.20
1.1 couderc 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2:
3: <html>
4: <head>
1.15 couderc 5: <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
6: <meta name="resource-type" content="document">
7: <meta name="description" content="The OpenBSD Port Testing Guide">
8: <meta name="keywords" content="openbsd,ports, test">
9: <meta name="distribution" content="global">
1.18 jose 10: <meta name="copyright" content="copyright 2002-2004 by OpenBSD.">
1.6 couderc 11: <title>OpenBSD Port Testing Guide</title>
1.1 couderc 12: </head>
13:
14: <body text="#000000" bgcolor="#FFFFFF" link="#23238E">
15: <a href="index.html"><img alt="[OpenBSD]" height="30" width="141" src=
16: "images/smalltitle.gif" border="0"></a>
17:
1.6 couderc 18: <h2><font color="#e00000">Port Testing Guide</font></h2>
1.1 couderc 19: <hr>
20:
21: <h2><font color="#0000e0">Index</font></h2>
22:
23: <ul>
24: <li><a href="#Introduction">Introduction</a></li>
25:
26: <li><a href="#How">How</a></li>
27:
28: <li><a href="#First">First step</a></li>
29:
30: <li><a href="#Testing">Testing</a></li>
31:
32: <li><a href="#Commenting">Commenting</a></li>
33:
34: <li><a href="#More">More testing</a></li>
35: </ul>
36: <hr>
37:
38: <h2><a name="Introduction"><font color=
39: "#0000e0">Introduction</font></a></h2>
40:
1.20 ! steven 41: <p>The <a href="faq/faq15.html#Ports">ports tree</a> is a huge piece
! 42: of work that
1.8 avsm 43: permits OpenBSD users to use third-party programs without wasting time
44: patching, configuring and installing each one individually. This work
1.9 avsm 45: is done by a group of volunteers who spend their time porting and testing
46: applications across the range of OpenBSD platforms. Many people think
47: that they cannot help this process because they do not have enough
48: knowledge; this is false because they can help porters work better and
49: faster.</p>
1.1 couderc 50:
51: <h2><a name="How"><font color="#0000e0">How</font></a></h2>
52:
1.8 avsm 53: <p>Testing submitted updates or new ports which are posted on the
1.6 couderc 54: <a href="mail.html">ports mailing list</a>. By doing this
1.3 couderc 55: you reduce the latency of commits and also increase the number of ports to
56: be committed (many ports are not committed because of lack of testing!).</p>
1.1 couderc 57:
58: <h2><a name="First"><font color="#0000e0">First step</font></a></h2>
59:
1.8 avsm 60: <p>The ports tree is developed against
61: <a href="plus.html">OpenBSD-current</a>; there is no guarantee that
1.20 ! steven 62: new ports or updates will work correctly on the other branches.
! 63: This means
1.8 avsm 64: you should upgrade your system and ports tree to -current
65: (instructions on how to do this can be found at the
1.19 nick 66: <a href="anoncvs.html">anoncvs</a> and
67: <a href="faq/current.html">Following Current</a>) pages.
1.8 avsm 68: It is also recommended that you subscribe to the ports and ports-changes
1.12 jufi 69: <a href="mail.html">mailing-lists</a>. This way you will be notified
1.8 avsm 70: about new or updated ports and about changes in the ports tree.</p>
1.7 couderc 71:
1.1 couderc 72: <h2><a name="Testing"><font color="#0000e0">Testing</font></a></h2>
73:
1.8 avsm 74: <p>There are two types of submissions on the mailing-lists; new ports
75: and updates. New ports are generally posted as tarball attachments
1.20 ! steven 76: or URLs. A good idea is to extract them into the
1.8 avsm 77: <tt>/usr/ports/mystuff/</tt> directory and test from there.
78: Updates are generally a diff against the -current ports tree, so it is best
79: to copy the port to <tt>mystuff/</tt> and apply the diff to prevent tree
1.7 couderc 80: breakage.</p>
1.1 couderc 81:
1.7 couderc 82: <p>Step-by-step building is needed to verify that every target, see
1.6 couderc 83: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=ports&sektion=7&">
1.7 couderc 84: ports(7)</a>, is achieved correctly :</p>
1.1 couderc 85:
86: <ul>
1.8 avsm 87: <li><i>fetch</i>
88: <ul>
1.14 couderc 89: <li>Needed to verify that distfile(s) are correctly downloaded. Try
90: to test all of the <tt>MASTER_SITES</tt> specified to make sure they
91: are all valid sources.</li>
1.10 couderc 92: </ul>
93:
94: <li><i>checksum</i>
95: <ul>
1.14 couderc 96: <li>Verify that downloaded distfiles match the checksums recorded
97: in the <tt>distinfo</tt> file.</li>
1.10 couderc 98: </ul>
1.8 avsm 99:
100: <li><i>extract</i>
1.14 couderc 101: <ul><li>Each of the distfiles should install any dependent programs
102: (such as bzip2) beforehand.</li></ul>
1.8 avsm 103:
104: <li><i>patch</i>
105: <ul>
106: <li>Patches should apply cleanly without any warnings.
107: <li>There shouldn't be any <tt>.orig</tt> files left behind in the
108: <tt>patches/</tt> directory.
1.14 couderc 109: <li>Another common mistake is to include RCS tags in a patch; this
110: will break when the port is checked into the repository and the RCS
111: tag expanded.
1.8 avsm 112: </ul>
113:
114: <li><i>configure</i>
115: <ul>
116: <li>Check that configure scripts correctly detect features
117: on your platform.
118: <li>GNU libtool is notorious for undesired 'features' on OpenBSD,
119: so check that the port is using a recent version which creates
120: correct libraries on your architecture.
121: <li>The configure script should not detect stray applications already
122: installed on your system without explicit dependencies being
123: set in the port.
124: </ul>
125:
126: <li><i>build</i>
127: <ul>
128: <li>Check for build errors and suspicious warnings.
129: <li>Warnings about <a href=
1.6 couderc 130: "http://www.openbsd.org/cgi-bin/man.cgi?query=tmpnam&sektion=3&">
1.8 avsm 131: tmpnam(3)</a> issues should be resolved by using
1.14 couderc 132: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=mkstemp&sektion=3&">
133: mkstemp(3)</a>.</li>
134: <li>Try to set the <tt>SEPARATE_BUILD</tt> variable to 'concurrent'
135: and test if the build still works.
1.8 avsm 136: <li>Make sure dependencies on GNU make are really necessary.
1.20 ! steven 137: <li>Check whether the port is using libtool. If it is, try
! 138: setting <tt>USE_LIBTOOL=Yes</tt>. This way, the ports
! 139: infrastructure will use the libtool version in the tree, instead
! 140: of libtool versions that come bundled with the software's source.
1.8 avsm 141: </ul>
142:
1.14 couderc 143: <li><i>regress</i>
144: <ul>
145: <li>Check for errors (empty tests means okay).
146: </ul>
147:
148:
1.8 avsm 149: <li><i>fake</i>
150: <ul>
151: <li>This target installs the application into a fake working
152: directory, to ensure that all files can be easily packaged up
153: without affecting the base system.
154: <li>The port should <b>never</b> install files outside of the
155: fake directory (such as into <tt>/usr/local</tt>).
1.20 ! steven 156: This kind of mistake can be easily caught by using
! 157: <tt>USE_SYSTRACE=Yes</tt>.
1.8 avsm 158: <li>GNU libtool occasionally has trouble relinking libraries
159: during the fake process on some architectures.
1.20 ! steven 160: <li>Check whether all files get installed with correct ownerships
! 161: and permissions.
1.8 avsm 162: </ul>
163:
164: <li><i>package</i>
165: <ul>
166: <li>Package creation can break if pkg/PLIST* and/or
167: pkg/PFRAG* are wrong.</li>
168: </ul>
169:
1.20 ! steven 170: <li><i>lib-depends-check</i>
! 171: <ul>
! 172: <li>This will check whether all libraries on which the port depends
! 173: can be reached through either <tt>LIB_DEPENDS</tt> or <tt>WANTLIB</tt>.
! 174: The result should be empty. The above variables should be inspected
! 175: when you see lines starting "Extra" or "Missing".
! 176: </ul>
! 177:
1.8 avsm 178: <li><i>install</i>
179: <ul>
180: <li>Packages should install all of the files from their packaging
181: lists successfully and with the correct permissions. Be especially
182: careful of files with the setuid bits set.
183: <li>Make sure that the package <tt>INSTALL</tt> script works
184: correctly, and does not overwrite any files in <tt>/etc</tt>.
185: </ul>
186:
187: <li><i>deinstall</i>
188: <ul>
189: <li>This should remove all files installed by the package, except
190: those in <tt>/etc</tt>.
191: <li>Make sure that the <tt>DEINSTALL</tt> script works as expected.
192: </ul>
1.1 couderc 193: </ul>
194:
1.11 avsm 195: <p>Remaining <tt>pkg/</tt> files like DESCR and MESSAGE should be checked
196: for grammar and typos. Paragraphs should be formatted using
197: <a href="http://www.openbsd.org/cgi-bin/man.cgi?query=fmt&sektion=1&format=html">fmt(1)</a> and wrapped at 70 characters.</p>
1.1 couderc 198:
199: <h2><a name="Commenting"><font color="#0000e0">Commenting</font></a></h2>
200:
201: <p>At the end of the test comes the really important thing : comments.
1.7 couderc 202: Even if the port is working fine comments must be done. If we have ten
1.3 couderc 203: posts where people say that the port runs fine under different architectures
1.7 couderc 204: then the commit is done faster. If it does not work then some information
205: must be given.
206: There are tools that can help in this task, like <a href=
1.1 couderc 207: "http://www.openbsd.org/cgi-bin/cvsweb/ports/infrastructure/build/portslogger">
1.14 couderc 208: portslogger</a> which is like an "intelligent tee" that redirects output
209: into a log file.</p>
1.1 couderc 210:
211: <p>Example :<br>
212: </p>
213:
214: <div style="margin-left: 2em">
1.11 avsm 215: <table border="0" cellpadding="3" width="90%">
1.1 couderc 216: <tr>
217: <td nowrap bgcolor="#EEEEEE">
218: <pre>
1.16 sturm 219: # make install 2>&1 | /usr/ports/infrastructure/build/portslogger .
1.1 couderc 220: </pre>
221: </td>
222: </tr>
223: </table>
224: </div>
225: <br>
226: <br>
227:
228:
1.3 couderc 229: <p>This will redirect the output into a log file located in the current
1.1 couderc 230: directory.</p>
231:
1.20 ! steven 232: <p>Finally, once the port is found to be okay, other ports depending on
! 233: it should also be tested, to check whether they are still working
! 234: correctly. The <i>show-required-by</i> make target will help to find
! 235: other ports which depend on the current one.
! 236:
1.1 couderc 237: <h2><a name="More"><font color="#0000e0">More testing</font></a></h2>
238:
1.20 ! steven 239: <p>Check the port's Makefile for correct dependencies, typos, incorrect
! 240: links, useless or missing variables, correct licensing and categories.
! 241: Those who are more skilled can help by examining patches, as well as
! 242: providing diffs to correct bugs, add flavors, or other enhancements.</p>
1.11 avsm 243: <p>These diffs should be done with the <tt>-uNr --exclude=CVS</tt> options.
244: <tt>cvs diff -uN</tt> can also be used to generate patches against
245: the CVS repository.</p>
1.17 jufi 246: <hr>
247: <a href="index.html"><img src="back.gif" height="24" width="24" alt="OpenBSD" border="0"></a>
248: <a href="mailto:www@openbsd.org">www@openbsd.org</a><br>
249: <small>
1.20 ! steven 250: $OpenBSD: porttest.html,v 1.19 2005/02/09 20:37:25 nick Exp $
1.17 jufi 251: </small>
252: </body>
1.1 couderc 253: </html>