Annotation of www/checklist.html, Revision 1.23
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
281: (max. 60 characters). Do NOT include the package name (or version number
282: of the software) in the comment. Do NOT start with an uppercase letter
283: unless semantically significant, do NOT end with a period.
284: <li>
285: DESCR is a longer description of the port. One to a few paragraphs
286: concisely explaining what the port does is sufficient.
287: <li>
288: PLIST is kept empty at this point.
289: </ul>
290:
1.22 rohee 291: <br><li>
1.20 turan 292: Install the application with <b>make install</b>
293: <p>
294: If the port installs dynamic libraries, check their symbol tables
295: with <code>nm</code>, as some mistaken software strips dynamic libraries,
296: which may lead to weird failures later.
297:
1.22 rohee 298: <br><br><li>
1.20 turan 299: <strong>Check port for security holes again</strong>. This is
300: especially important for network and setuid programs. See
301: <a href="porting.html#security">our security recommendations</a>
302: for that. Log interesting stuff and fixes in the
303: <code>pkg/SECURITY</code> file. This file
304: should list audited potential problems, along with relevant patches,
305: so that another person can see at first glance what has been done.
306: Example:
1.14 rohee 307: <pre>
308: $OpenBSD$
1.9 espie 309:
310: ${WRKDIR}/receiver.c
311: call to mktemp (wrapper function do_mktemp) does seem to be correct.
312:
313: The server makes extensive use of strlcpy/strlcat/snprintf.
1.20 turan 314: </pre>
315:
1.22 rohee 316: <li>
1.20 turan 317: Create pkg/PLIST. After the install is complete use the developer's command,
318: <b>make plist</b> which makes the file PLIST-auto in the <i>pkg</i> directory.
319: This file is a candidate packing list.
320: <p>
321: Beware! The files are found by timestamp. This means it does NOT:
322: <ul>
323: <li>
324: list any files installed with `tar' as their timestamp
325: will not change and thus won't be found by `find'
326: <li>
327: Update the <code>info/dir</code> file if .info files are added.
328: Also, be sure that the <code>info/dir</code> is not part of the PLIST.
329: <li>
330: Try to do anything special with links or symbolic links. A
331: cursory test of tar shows it does the right thing with links
332: and symbolic links so I don't see why we need to special case
333: anything in the packing list. But still...
334: </ul>
335: <p>
336: Peruse `PLIST-auto' and verify that everything was installed and
337: that it was installed in the proper locations. Anything not installed
338: can be added to a port Makefile `post-install' rule.
339: <p>
340: Move `PLIST-auto' to `PLIST'
341:
342: <p>
343: Ports that install shared libraries will need two versions of the PLIST file.
344: <ul>
345: <li>
346: PLIST describes the files installed on those architectures that support
347: shared libraries.
348: <li>
349: PLIST.noshared describes the files installed on architectures that do not
350: support shared libs.
351: <li>
352: Typically, PLIST.noshared is a copy of PLIST less references to any
353: shared libraries.
354: </ul>
355:
1.22 rohee 356: <br><li>
1.20 turan 357: Keep repeating uninstall and reinstall until perfect.<br>
358: <em>Perfect</em> is when everything installs and uninstalls
359: in its proper location. `pkg_delete <pkg_name>' is
360: used to uninstall. `sudo make reinstall' is used to reinstall. See the
361: `pkg_create' man page for other commands that may be added
362: to PLIST to ensure all is cleaned up. After an uninstall the command
363: <p><code>find /usr/local -newer work/.install_started -print</code>
364: <p>should only list standard directory names.
365:
1.22 rohee 366: <br><br><li>
1.20 turan 367: Test the packaging:<br>
368: After the port installs correctly issue the command
369: <code>make package</code> to create a package. To test the
370: package first do a <code>pkg_delete</code> and then do a
371: <code>pkg_add</code> The results after an add should EXACTLY
372: match the results after a `make install'.
1.9 espie 373:
1.22 rohee 374: <br><br><li>
1.20 turan 375: Mail <a href="mailto:ports@openbsd.org">ports@openbsd.org</a> with a short
376: note asking for comments and testing. Attach the port to this email and
377: sent it out. If you don't get any comments, send email to
1.23 ! wvdputte 378: <a href="mailto:turan@openbsd.org">turan@openbsd.org</a> and I will pick it
! 379: for you.
1.20 turan 380: <p>
381: Try to get others to test it on a variety of platforms for you.
382: <ul><li>
383: The DEC Alpha is good because it has only static libraries and because
1.22 rohee 384: <code>sizeof(int) != sizeof(long)</code>
1.20 turan 385: <li>
386: Sun SPARC is good because it is very common and because its byte order is
387: the reverse of i386; if you developed on SPARC, of course, you'd want it
388: tested on i386).
389: </ul>
390:
1.22 rohee 391: <br><li>
1.20 turan 392: Incorporate any feedback you get. Test it again on your platform.
393: Get those who gave you feedback to test it again from your new port.
394:
1.22 rohee 395: <br><br><li>
1.20 turan 396: Finally, include it in the "ports" tree.
397: <p>
398: If you do not have CVS access, ask someone on
1.23 ! wvdputte 399: <a href="mailto:ports@openbsd.org">ports@openbsd.org</a> to commit it. Don't
! 400: forget about me, <a href="mailto:turan@openbsd.org">turan@openbsd.org</a> if
! 401: no one picks it up.
1.9 espie 402:
1.22 rohee 403: <br><br><li>
1.20 turan 404: If you are a developer with CVS access, check it in.
405: We normally use "import" for a new port,
406: rather than adding a zillion (or a dozen) files individually.
407: Import uses "vendor branch" version numbers like 1.1.1.1, but don't worry
408: about that! :-) If you make changes to a specific file (edit, then
409: cvs commit), it will be 1.2, and that will be used.
410: <p>
411: In short, import is typically used when a port is created.
412: From that point on cvs add and cvs rm are typically used to add or remove
413: files, and the normal edit->commit cycle for changes.
414: You might use something like this:
415: <pre>
1.4 ian 416: cd kaffe1
417: make clean # you really really don't want to check in all of work!
418: cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \
419: <I>YourName</I> <I>YourName_YYYY-MMM-DD</I>
1.20 turan 420: </pre>
421: <ul><li>
422: -d cvs.openbsd.org:/cvs says where cvs lives. This can be omitted if you
1.21 form 423: have a CVSROOT environment variable defined.
1.20 turan 424: <li>
425: -m 'kaffe port' is your login message. Change it to whatever you like
426: <li>
427: ports/lang/kaffe1 is the path relative to /cvs where the port lives
428: <li>
429: <i>YourName</i> (replaced with your login name) is the "vendor tag".
430: You imported it so you are the vendor.
431: <li>
432: <i>YourName_YYYY-MMM-DD</i> (e.g., ian_2000-Jan-01)
433: is the 'vendor release tag'. This is as good as any.
434: </ul>
435: As a real example, here is the output of checking in the Kaffe1 port,
436: which one of us did on September 8, 1998:
437: <pre>
1.4 ian 438: $ cd kaffe1
439: $ make clean >/dev/null
440: $ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08
441: ian@cvs.openbsd.org's password: (not shown, obviously)
442: I ports/lang/kaffe1/CVS
443: I ports/lang/kaffe1/files/CVS
444: I ports/lang/kaffe1/pkg/CVS
445: N ports/lang/kaffe1/Makefile
446: cvs server: Importing /cvs/ports/lang/kaffe1/files
447: N ports/lang/kaffe1/files/md5
448: cvs server: Importing /cvs/ports/lang/kaffe1/pkg
449: N ports/lang/kaffe1/pkg/COMMENT
450: N ports/lang/kaffe1/pkg/DESCR
451: N ports/lang/kaffe1/pkg/PLIST
452:
453: No conflicts created by this import
454: $
1.20 turan 455: </pre>
456:
1.22 rohee 457: <li>
1.20 turan 458: Last but not least, add a one-line entry for the new port
459: in its parent directory's makefile, i.e., for ports/lang/kaffe1,
460: add it to ports/lang/Makefile.
461:
1.22 rohee 462: <br><br><li>
1.20 turan 463: Maintain the port! As time goes by, problems may arise, or new versions
464: of the software may be released. You should strive to keep your port up
1.22 rohee 465: to date. In other words - iterate, test, test, iterate...
466: </ol>
1.20 turan 467:
468: Thank you for supporting the OpenBSD "ports" process!
469: <hr>
470: <a href="porting.html"><img height=24 width=24 src=back.gif
471: border=0 alt=Porting></a>
472: <a href="mailto:www@openbsd.org">www@openbsd.org</a>
1.23 ! wvdputte 473: <br><small>$OpenBSD: checklist.html,v 1.22 2000/03/11 18:49:19 rohee Exp $</small>
1.20 turan 474: </body>
1.1 marc 475: </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