Annotation of www/checklist.html, Revision 1.27
1.14 rohee 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1.1 marc 2: <html>
1.20 turan 3: <head>
4: <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
5: <meta name="resource-type" content="document">
6: <meta name="description" CONTENT="How to make/update an OpenBSD port.">
7: <meta name="keywords" content="openbsd,ports">
8: <meta name="distribution" content="global">
1.22 rohee 9: <meta name="copyright" content="This document copyright 1998-2000 by OpenBSD.">
1.20 turan 10:
11: <title>OpenBSD Porting Checklist</title>
1.1 marc 12: </head>
1.20 turan 13:
1.22 rohee 14: <body text=Black bgcolor=White link="#23238E">
1.20 turan 15: <img height=30 width=141 src=images/smalltitle.gif alt="[OpenBSD]" >
16:
17: <h2><font color="#e00000">OpenBSD Porting Checklist</font></h2>
18:
19: This document describes how to make or upgrade a port. It is a useful
20: reminder of things to do. This is not totally accurate nor perfect.
21: Direct comments and questions to <a href="mailto:turan@openbsd.org">
22: turan@openbsd.org </a>.
23:
24: <hr>
25: <ol>
26:
1.22 rohee 27: <li>
1.20 turan 28: If you want to be a maintainer, subscribe to
29: <a href="mailto:ports@openbsd.org"> ports@openbsd.org.</a>
30: <ul><li>
31: This is where all ports discussions take place.
32: <li>
33: Reading this list is important since many announcements go over this list.
34: <li>
35: You will find a lot of porting-savvy people here. They can often give you
36: good advice or test ports for you.
37: </ul>
38:
1.22 rohee 39: <br><li>
1.20 turan 40: Check out a copy of the ports tree from cvs.
41: You can find instructions to do this at
42: <a href="http://www.openbsd.org/anoncvs.html">
43: http://www.openbsd.org/anoncvs.html</a>.
44:
1.22 rohee 45: <br><br><li>
1.20 turan 46: Pick a place to put your port and create the basic
47: infrastructure there. Use the template Makefile at
48: <code>/usr/ports/infrastructure/templates/Makefile.template</code>.
1.25 reinhard 49:
50: <br>
51: NEED_VERSION relates to the version in the $OpenBSD tag of
52: <tt>$(PORTSDIR)/infrastructure/mk/bsd.port.mk</tt>: e.g.
53: <tt>$OpenBSD: bsd.port.mk,v 1.287 ...</tt> would get
54: <tt>NEED_VERSION=1.287</tt> in your Makefile.
55: The fullproof and right way is to choose the most recent version you can
56: find. As you are a port developer, you are supposed to update
57: your ports, including bsd.port.mk.
58: <br>
59:
1.20 turan 60: <ul><li>
61: Create the directories <code>files, patches, pkg</code>.
62: <li>
63: Create these empty files <code>pkg/COMMENT, pkg/DESCR, pkg/PLIST</code>
64: </ul>
65:
1.22 rohee 66: <br><li>
1.20 turan 67: Add the fetch portions of the Makefile.
68: <ul><li>
1.27 ! naddy 69: Fill in EXTRACT_SUFX if its anything besides .tar.gz. Other examples are
1.20 turan 70: .tar.Z, or .tgz.
71: <li>
72: Fill in DISTNAME which is the name of the file minus the extract suffix. E.g. if you have foo-1.0.tar.gz, DISTNAME is foo-1.0.
73: <li>
74: Fill in MASTER_SITES which is a URL to the directory where the distfile
1.22 rohee 75: is kept. E.g. ftp://ftp.openbsd.org/pub/OpenBSD/distfiles/ . <strong>Don't forget
76: the trailing slash.</strong> Try to have at least three distinct sites as well.
1.20 turan 77: Place the most easily accessible first as they are traversed in order.
78: <li>
79: Keep in mind that fetch references the file as
1.27 ! naddy 80: ${MASTER_SITE}${DISTNAME}${EXTRACT_SUFX}. All three are used. Don't
1.20 turan 81: set DISTNAME to point to the file directly.
82: <li>
83: You can check to see if you have filled this values in correctly by typing
84: <b>make fetch-all</b>
85: </ul>
86: <p>
87: For more complex ports, you have more options and tools available to you:
88: <ul><li>
89: You also have the variable PATCHFILES available. This is a list of vendor
1.22 rohee 90: (not OpenBSD) patches to the port. Common uses are things like security
1.20 turan 91: or reliability fixes.
92: <li>
93: If your ports are available over large public mirrors such as GNU, SunSite, or
94: CPAN, we have already provided a list of sites for your use in
95: /usr/ports/infrastructure/template/network.conf.template.
96: Set MASTER_SITES to ${MASTER_SITE_GNU}, or ${MASTER_SITE_SUNSITE}, etc.
97: To simplify this process, the construct %SUBDIR% is replaced by the variable
98: MASTER_SITE_SUBDIR in your Makefile.
99: <li>
100: Ports normally correspond to given versions of software. Once they are retrieved, files are checksummed and compared to the recorded
101: checksum in files/md5. So, to avoid confusion, DISTFILES and PATCHFILES should have clearly visible version numbers:
102: don't retrieve foo-latest.tar.gz if it is a link to foo-1.0.5.tar.gz. If necessary, gently ask the original program author
103: to make such distinctions clear.
104: <li>
105: If a given port needs more than about 5 DISTFILES + PATCHFILES to work, use DIST_SUBDIR to avoid cluttering
106: /usr/ports/distfiles too much.
107: <li>
108: DIST_SUBDIR must not include version numbers. When the port is updated to a later version, some distfiles may not change, but will be
109: refetched if DIST_SUBDIR is changed. Even if all distfiles change, it is easier for the user to track cruft.
110: <li>
111: All DISTFILES and PATCHFILES don't necessarily come from the same set of MASTER_SITES. Supplementary sites can be
112: defined using the variables MASTER_SITES0 to MASTER_SITES9. Just write DISTFILES=foo-1.0.5.tar.gz:5 to
113: retrieve foo-1.0.5.tar.gz from MASTER_SITES5.
114: <li>
115: Some ports don't always need to retrieve all files in all circumstances. For instance, some ports may have some compilation options, and
116: associated files which are only required in such a case. Or they may need some files for some architectures only. In such a case, those
117: supplementary optional files must be mentioned in the SUPDISTFILES variable. Targets such as makesum or
118: mirror-distfiles will fetch those supplementary files that the casual user doesn't need.
119: </ul>
1.1 marc 120:
1.22 rohee 121: <br><li>
1.20 turan 122: Create a checksum in <i>files/md5</i> by typing <b>make makesum</b>.
123: Then verify the checksum is correct by typing <b>make checksum</b>
124: <ul><li>
125: In some rare cases, files checksums can't be verified reliably. By all means, porters should try to find sites that are reliable. Communicating
126: with the software author and the archive site maintainer at this stage is highly desirable. In the worst case, non-checksummable files can be
127: mentioned in the IGNOREFILES variable.
128: <li>
129: All files in DISTFILES are usually processed during make extract. EXTRACT_ONLY may be used to limit extraction to a
130: subset of files (possibly empty). The customary use of this variable is to customize extraction: for instance, if some DISTFILES need
131: some special treatment, they will be removed from EXTRACT_ONLY and handled manually at post-extract stage.
132: For historic reasons, make extract does set up the working directory first along with extracting files. Thus, providing a
133: pre-extract or a do-extract target is highly unusual (and fairly suspicious behavior, indicative of a high degree of obfuscation
134: in the port).
135: <li>
136: Patches that need specific treatment should be mentioned in DISTFILES, and removed from EXTRACT_ONLY, for historic reasons.
137: </ul>
1.1 marc 138:
1.22 rohee 139: <br><li>
1.20 turan 140: Extract the port with <b>make extract</b>. Pay attention to where the base
141: of the sources are. Usually, its <i>work/DISTNAME</i> You may need to modify
142: the Makefile's WRKDIST variable if it is different.
1.9 espie 143:
1.22 rohee 144: <br><br><li>
1.20 turan 145: Read the installation documentation and note what you have to do to build
146: the port and any special options that might be needed.
1.22 rohee 147:
148: <br><br><li>
1.20 turan 149: Now is also a good time to figure out what kind of licensing restrictions
150: apply to your port. Many are freely redistribution but then again, quite
151: a few are not. We need four questions answered to distribute ports
152: properly. These are the PERMIT_* values in the Makefile.
153: <ul><li>
154: PERMIT_PACKAGE_CDROM tells us if we can put the package on the cdrom.
155: <li>
156: PERMIT_PACKAGE_FTP tells us if we can put the package on the ftp sites.
157: <li>
158: PERMIT_DISTFILES_CDROM tells us if we can mirror the distfiles on the cdrom.
159: <li>
160: PERMIT_DISTFILES_FTP tells us if we can mirror the distfiles on the ftp sites.
161: </ul><p>
162: Set these values to Yes if it is permitted or to a comment string stating why
163: it is not. Pay attention to any special conditions you may need to fulfill
164: later on. E.g. some ports require to install a copy of the license. We
165: recommend you place the license in <code>/usr/local/share/DISTNAME/</code>.
166:
1.22 rohee 167: <br><br><li>
1.20 turan 168: Add configuration options to Makefile and/or create the configuration script.
169: <ul><li>
170: You can add a port configuration script named `configure' to a directory
171: named <code>scripts/</code>. This will be run before any configuration
172: specified by GNU_CONFIGURE or HAS_CONFIGURE is run.
173: <li>
174: If GNU_CONFIGURE is used you may want to run ./configure --help
175: to see what options are available.
176: <li>
177: Anything that you may want to override can be changed by adding the
178: --option flags to the CONFIGURE_ARGS parameter in the Makefile.
179: <li>
180: Use CONFIGURE_ARGS+= to append to the variable. CONFIGURE_ARGS= will
181: overwrite it.
182: </ul>
183:
1.22 rohee 184: <br><li>
1.20 turan 185: Try building the port with <b>make build</b>.
186: <ul><li>
187: If you're lucky, the port will go all the way through without errors.
188: <li>
189: If it exits with an error, you will need to generate patches for your port.
190: Figure out what needs to be changed and make patch for it.
191: <li>
192: Patches must be relative to ${WRKDIST}.
193: <li> The easiest way to reset the port and test your patches is
194: <b>make clean patch</b>. This will delete the work directory, re-extract,
195: and patch your port.
196: </ul>
197:
1.22 rohee 198: <br><li>
1.26 reinhard 199: Begin and cycle of <b>make build</b>, generate a patch (or use <b>make
200: update-patches</b>), and
1.20 turan 201: <b>make clean patch</b>.
202: <ul><li>
203: Patches go in the directory <i>patches/</i> and should be named patch-* with
204: * being something meaningful. We recommend you name your patches
1.26 reinhard 205: patch-FILENAME where FILENAME is the name of the file it is patching.
206: (<tt>make update-patches</tt> does this automatically for you.)
1.20 turan 207: <li>
208: Applying PATCHFILES is the first half of the make patch stage. It can be
209: invoked separately as make distpatch, which is a convenient target for
210: porters. Ignore this if you haven't set it.
211: <li>
212: Only patch one source file per patchfile, please,
213: <li>
214: Use <b>diff -p -u</b> to generate patches,
215: <li>
216: All patches MUST be relative to ${WRKDIST},
217: <li>
218: Check that patches <strong>DON'T</strong> contain tags that cvs
219: will replace. If they do, your patches won't apply after you check
220: them in. You can check in your changes with -kk to avoid this.
221: <li>
222: Add a small explanation of the patch role in the patchfile before
223: the patch itself, and an OpenBSD CVS tag <code>$OpenBSD$</code>.
224: <li>
225: <b>Please</b> feed your patches back to the author of that piece of software.
226: </ul>
227:
1.22 rohee 228: <br><li>
1.20 turan 229: Try setting <code>SEPARATE_BUILD</code><br>
230: <ul><li>
231: If the port can build with object files outside its source tree,
232: this is cleaner (many programs using <code>GNU_CONFIGURE</code> can),
233: and may help people who mount their ports tree on several arches.
234: <li>
235: This can also spare you some effort, as you will possibly be able to
236: restart the cycle at <code>configure</code> most of the time.
237: </ul>
238:
1.22 rohee 239: <br><li>
1.20 turan 240: Peruse the output (if any) and tweak any options in the Makefile.
241: To repeat issue the command `<b>make clean configure</b>'.
242: <p>
243: Note: make sure host dependent files go in <i>/etc</i> or
1.22 rohee 244: <i>/etc/<name></i>, but <strong>NEVER REPLACE OR MODIFY</strong> existing files
1.20 turan 245: in <i>/etc</i>. Best to have install place
246: in <i>/usr/local/share/<name></i> and then copy to
247: <i>/etc</i> or <i>/etc/<name></i> only if the files do not exist.
248: If the files exist, display a message that says such-and-such files need
249: to be modified. This also guarantees that the files will be included in
250: the package since everything under <i>/usr/local</i> is included in the PLIST
251:
252: <p>
253: The OpenBSD file locations are:
254: <pre>
1.1 marc 255: user executables: /usr/local/bin
256: system admin executables: /usr/local/sbin
257: program executables: /usr/local/libexec
258: libraries /usr/local/lib
1.14 rohee 259: architecture dependent data /usr/local/lib/<name>
1.1 marc 260: installed include files: /usr/local/include or
1.14 rohee 261: /usr/local/include/<name>
262: single-machine data: /etc or /etc/<name>
1.1 marc 263: local state: /var/run
264: GNU info files: /usr/local/info
265: man pages: /usr/local/man/...
1.14 rohee 266: read-only architecture-independent: /usr/local/share/<name>
267: misc documentation: /usr/local/share/doc/<name>
1.20 turan 268: </pre>
1.9 espie 269:
1.22 rohee 270: <li>
1.20 turan 271: Begin a cycle of makes until the port is ready. Patch (see above)
272: clean, and make until the port is generated. Get rid of all warnings
273: if possible, especially security related warnings.
1.22 rohee 274:
275: <br><br><li>
1.20 turan 276: Control SEPARATE_BUILD semantics.
277: You have to do this only if the port builds with
278: SEPARATE_BUILD defined.
279: Ideally, the port should no longer modify any file in
280: ${WRKSRC} after <b>make patch</b>.
281: You can check this by making sure you don't have any write access
282: to ${WRKSRC}. Then you can set
283: SEPARATE_BUILD=concurrent: someone can use the same
284: source tree to build on distinct arches simultaneously.
285: Otherwise, set <code>SEPARATE_BUILD=simple</code>: building on
286: distinct arches simultaneously may meet with problems, as some
287: source files may be regenerated at awkward moments.
1.9 espie 288:
1.22 rohee 289: <br><br><li>
1.20 turan 290: Edit <i>pkg/DESCR</i>, <i>pkg/COMMENT</i>, <i>pkg/PLIST</i>.
291: <ul>
292: <li>
293: COMMENT is a <strong>SHORT</strong> one-line description of the port
1.24 espie 294: (max. 60 characters). Do <strong>NOT</strong> include the package
295: name (or version number of the software) in the comment.
296: Do <strong>NOT</strong> start with an uppercase letter
297: unless semantically significant,
298: do <strong>NOT</strong> end with a period.
299: <strong>DON'T EVER START WITH AN UNDETERMINATE ARTICLE SUCH AS `a' or `as',
300: remove the article altogether.</strong>
1.20 turan 301: <li>
302: DESCR is a longer description of the port. One to a few paragraphs
303: concisely explaining what the port does is sufficient.
304: <li>
305: PLIST is kept empty at this point.
306: </ul>
307:
1.22 rohee 308: <br><li>
1.20 turan 309: Install the application with <b>make install</b>
310: <p>
311: If the port installs dynamic libraries, check their symbol tables
312: with <code>nm</code>, as some mistaken software strips dynamic libraries,
313: which may lead to weird failures later.
314:
1.22 rohee 315: <br><br><li>
1.20 turan 316: <strong>Check port for security holes again</strong>. This is
317: especially important for network and setuid programs. See
318: <a href="porting.html#security">our security recommendations</a>
319: for that. Log interesting stuff and fixes in the
320: <code>pkg/SECURITY</code> file. This file
321: should list audited potential problems, along with relevant patches,
322: so that another person can see at first glance what has been done.
323: Example:
1.14 rohee 324: <pre>
325: $OpenBSD$
1.9 espie 326:
327: ${WRKDIR}/receiver.c
328: call to mktemp (wrapper function do_mktemp) does seem to be correct.
329:
330: The server makes extensive use of strlcpy/strlcat/snprintf.
1.20 turan 331: </pre>
332:
1.22 rohee 333: <li>
1.20 turan 334: Create pkg/PLIST. After the install is complete use the developer's command,
335: <b>make plist</b> which makes the file PLIST-auto in the <i>pkg</i> directory.
336: This file is a candidate packing list.
337: <p>
338: Beware! The files are found by timestamp. This means it does NOT:
339: <ul>
340: <li>
341: list any files installed with `tar' as their timestamp
342: will not change and thus won't be found by `find'
343: <li>
344: Update the <code>info/dir</code> file if .info files are added.
345: Also, be sure that the <code>info/dir</code> is not part of the PLIST.
346: <li>
347: Try to do anything special with links or symbolic links. A
348: cursory test of tar shows it does the right thing with links
349: and symbolic links so I don't see why we need to special case
350: anything in the packing list. But still...
351: </ul>
352: <p>
353: Peruse `PLIST-auto' and verify that everything was installed and
354: that it was installed in the proper locations. Anything not installed
355: can be added to a port Makefile `post-install' rule.
356: <p>
357: Move `PLIST-auto' to `PLIST'
358:
359: <p>
360: Ports that install shared libraries will need two versions of the PLIST file.
361: <ul>
362: <li>
363: PLIST describes the files installed on those architectures that support
364: shared libraries.
365: <li>
366: PLIST.noshared describes the files installed on architectures that do not
367: support shared libs.
368: <li>
369: Typically, PLIST.noshared is a copy of PLIST less references to any
370: shared libraries.
371: </ul>
372:
1.22 rohee 373: <br><li>
1.20 turan 374: Keep repeating uninstall and reinstall until perfect.<br>
375: <em>Perfect</em> is when everything installs and uninstalls
376: in its proper location. `pkg_delete <pkg_name>' is
377: used to uninstall. `sudo make reinstall' is used to reinstall. See the
378: `pkg_create' man page for other commands that may be added
379: to PLIST to ensure all is cleaned up. After an uninstall the command
380: <p><code>find /usr/local -newer work/.install_started -print</code>
381: <p>should only list standard directory names.
382:
1.22 rohee 383: <br><br><li>
1.20 turan 384: Test the packaging:<br>
385: After the port installs correctly issue the command
386: <code>make package</code> to create a package. To test the
387: package first do a <code>pkg_delete</code> and then do a
388: <code>pkg_add</code> The results after an add should EXACTLY
389: match the results after a `make install'.
1.9 espie 390:
1.22 rohee 391: <br><br><li>
1.20 turan 392: Mail <a href="mailto:ports@openbsd.org">ports@openbsd.org</a> with a short
393: note asking for comments and testing. Attach the port to this email and
394: sent it out. If you don't get any comments, send email to
1.23 wvdputte 395: <a href="mailto:turan@openbsd.org">turan@openbsd.org</a> and I will pick it
396: for you.
1.20 turan 397: <p>
398: Try to get others to test it on a variety of platforms for you.
399: <ul><li>
400: The DEC Alpha is good because it has only static libraries and because
1.22 rohee 401: <code>sizeof(int) != sizeof(long)</code>
1.20 turan 402: <li>
403: Sun SPARC is good because it is very common and because its byte order is
404: the reverse of i386; if you developed on SPARC, of course, you'd want it
405: tested on i386).
406: </ul>
407:
1.22 rohee 408: <br><li>
1.20 turan 409: Incorporate any feedback you get. Test it again on your platform.
410: Get those who gave you feedback to test it again from your new port.
411:
1.22 rohee 412: <br><br><li>
1.20 turan 413: Finally, include it in the "ports" tree.
414: <p>
415: If you do not have CVS access, ask someone on
1.23 wvdputte 416: <a href="mailto:ports@openbsd.org">ports@openbsd.org</a> to commit it. Don't
417: forget about me, <a href="mailto:turan@openbsd.org">turan@openbsd.org</a> if
418: no one picks it up.
1.9 espie 419:
1.22 rohee 420: <br><br><li>
1.20 turan 421: If you are a developer with CVS access, check it in.
422: We normally use "import" for a new port,
423: rather than adding a zillion (or a dozen) files individually.
424: Import uses "vendor branch" version numbers like 1.1.1.1, but don't worry
425: about that! :-) If you make changes to a specific file (edit, then
426: cvs commit), it will be 1.2, and that will be used.
427: <p>
428: In short, import is typically used when a port is created.
429: From that point on cvs add and cvs rm are typically used to add or remove
430: files, and the normal edit->commit cycle for changes.
431: You might use something like this:
432: <pre>
1.4 ian 433: cd kaffe1
434: make clean # you really really don't want to check in all of work!
435: cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \
436: <I>YourName</I> <I>YourName_YYYY-MMM-DD</I>
1.20 turan 437: </pre>
438: <ul><li>
439: -d cvs.openbsd.org:/cvs says where cvs lives. This can be omitted if you
1.21 form 440: have a CVSROOT environment variable defined.
1.20 turan 441: <li>
442: -m 'kaffe port' is your login message. Change it to whatever you like
443: <li>
444: ports/lang/kaffe1 is the path relative to /cvs where the port lives
445: <li>
446: <i>YourName</i> (replaced with your login name) is the "vendor tag".
447: You imported it so you are the vendor.
448: <li>
449: <i>YourName_YYYY-MMM-DD</i> (e.g., ian_2000-Jan-01)
450: is the 'vendor release tag'. This is as good as any.
451: </ul>
452: As a real example, here is the output of checking in the Kaffe1 port,
453: which one of us did on September 8, 1998:
454: <pre>
1.4 ian 455: $ cd kaffe1
456: $ make clean >/dev/null
457: $ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08
458: ian@cvs.openbsd.org's password: (not shown, obviously)
459: I ports/lang/kaffe1/CVS
460: I ports/lang/kaffe1/files/CVS
461: I ports/lang/kaffe1/pkg/CVS
462: N ports/lang/kaffe1/Makefile
463: cvs server: Importing /cvs/ports/lang/kaffe1/files
464: N ports/lang/kaffe1/files/md5
465: cvs server: Importing /cvs/ports/lang/kaffe1/pkg
466: N ports/lang/kaffe1/pkg/COMMENT
467: N ports/lang/kaffe1/pkg/DESCR
468: N ports/lang/kaffe1/pkg/PLIST
469:
470: No conflicts created by this import
471: $
1.20 turan 472: </pre>
473:
1.22 rohee 474: <li>
1.20 turan 475: Last but not least, add a one-line entry for the new port
476: in its parent directory's makefile, i.e., for ports/lang/kaffe1,
477: add it to ports/lang/Makefile.
478:
1.22 rohee 479: <br><br><li>
1.20 turan 480: Maintain the port! As time goes by, problems may arise, or new versions
481: of the software may be released. You should strive to keep your port up
1.22 rohee 482: to date. In other words - iterate, test, test, iterate...
483: </ol>
1.20 turan 484:
485: Thank you for supporting the OpenBSD "ports" process!
486: <hr>
487: <a href="porting.html"><img height=24 width=24 src=back.gif
488: border=0 alt=Porting></a>
489: <a href="mailto:www@openbsd.org">www@openbsd.org</a>
1.27 ! naddy 490: <br><small>$OpenBSD: checklist.html,v 1.26 2000/12/11 13:08:52 reinhard Exp $</small>
1.20 turan 491: </body>
1.1 marc 492: </html>
![[BACK]](/icons/back.gif){kind=icon}
Return to checklist.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / www