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