Annotation of www/checklist.html, Revision 1.21
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">
9: <meta name="copyright" content="This document copyright 1998 by OpenBSD.">
10:
11: <title>OpenBSD Porting Checklist</title>
1.1 marc 12: </head>
1.20 turan 13:
14: <body text="#000000" bgcolor="#FFFFFF" link="#23238E">
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:
27: <p><li>
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:
39: <p><li>
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:
45: <p><li>
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:
55: <p><li>
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
64: is kept. E.g. ftp://ftp.openbsd.org/pub/OpenBSD/distfiles/ <b>Don't forget
65: the trailing slash.</b> Try to have at least three distinct sites as well.
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
79: (not openbsd) patches to the port. Common uses are things like security
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.20 turan 110: <p><li>
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.20 turan 128: <p><li>
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.20 turan 133: <p><li>
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.
136: <p><li>
137: Now is also a good time to figure out what kind of licensing restrictions
138: apply to your port. Many are freely redistribution but then again, quite
139: a few are not. We need four questions answered to distribute ports
140: properly. These are the PERMIT_* values in the Makefile.
141: <ul><li>
142: PERMIT_PACKAGE_CDROM tells us if we can put the package on the cdrom.
143: <li>
144: PERMIT_PACKAGE_FTP tells us if we can put the package on the ftp sites.
145: <li>
146: PERMIT_DISTFILES_CDROM tells us if we can mirror the distfiles on the cdrom.
147: <li>
148: PERMIT_DISTFILES_FTP tells us if we can mirror the distfiles on the ftp sites.
149: </ul><p>
150: Set these values to Yes if it is permitted or to a comment string stating why
151: it is not. Pay attention to any special conditions you may need to fulfill
152: later on. E.g. some ports require to install a copy of the license. We
153: recommend you place the license in <code>/usr/local/share/DISTNAME/</code>.
154:
155: <p><li>
156: Add configuration options to Makefile and/or create the configuration script.
157: <ul><li>
158: You can add a port configuration script named `configure' to a directory
159: named <code>scripts/</code>. This will be run before any configuration
160: specified by GNU_CONFIGURE or HAS_CONFIGURE is run.
161: <li>
162: If GNU_CONFIGURE is used you may want to run ./configure --help
163: to see what options are available.
164: <li>
165: Anything that you may want to override can be changed by adding the
166: --option flags to the CONFIGURE_ARGS parameter in the Makefile.
167: <li>
168: Use CONFIGURE_ARGS+= to append to the variable. CONFIGURE_ARGS= will
169: overwrite it.
170: </ul>
171:
172: <p><li>
173: Try building the port with <b>make build</b>.
174: <ul><li>
175: If you're lucky, the port will go all the way through without errors.
176: <li>
177: If it exits with an error, you will need to generate patches for your port.
178: Figure out what needs to be changed and make patch for it.
179: <li>
180: Patches must be relative to ${WRKDIST}.
181: <li> The easiest way to reset the port and test your patches is
182: <b>make clean patch</b>. This will delete the work directory, re-extract,
183: and patch your port.
184: </ul>
185:
186: <p><li>
187: Begin and cycle of <b>make build</b>, generate a patch, and
188: <b>make clean patch</b>.
189: <ul><li>
190: Patches go in the directory <i>patches/</i> and should be named patch-* with
191: * being something meaningful. We recommend you name your patches
192: patch-FILENAME where FILENAME is the name of the file it is patching.
193: <li>
194: Applying PATCHFILES is the first half of the make patch stage. It can be
195: invoked separately as make distpatch, which is a convenient target for
196: porters. Ignore this if you haven't set it.
197: <li>
198: Only patch one source file per patchfile, please,
199: <li>
200: Use <b>diff -p -u</b> to generate patches,
201: <li>
202: All patches MUST be relative to ${WRKDIST},
203: <li>
204: Check that patches <strong>DON'T</strong> contain tags that cvs
205: will replace. If they do, your patches won't apply after you check
206: them in. You can check in your changes with -kk to avoid this.
207: <li>
208: Add a small explanation of the patch role in the patchfile before
209: the patch itself, and an OpenBSD CVS tag <code>$OpenBSD$</code>.
210: <li>
211: <b>Please</b> feed your patches back to the author of that piece of software.
212: </ul>
213:
214: <p><li>
215: Try setting <code>SEPARATE_BUILD</code><br>
216: <ul><li>
217: If the port can build with object files outside its source tree,
218: this is cleaner (many programs using <code>GNU_CONFIGURE</code> can),
219: and may help people who mount their ports tree on several arches.
220: <li>
221: This can also spare you some effort, as you will possibly be able to
222: restart the cycle at <code>configure</code> most of the time.
223: </ul>
224:
225: <p><li>
226: Peruse the output (if any) and tweak any options in the Makefile.
227: To repeat issue the command `<b>make clean configure</b>'.
228: <p>
229: Note: make sure host dependent files go in <i>/etc</i> or
230: <i>/etc/<name></i>, but <b>NEVER REPLACE OR MODIFY</b> existing files
231: in <i>/etc</i>. Best to have install place
232: in <i>/usr/local/share/<name></i> and then copy to
233: <i>/etc</i> or <i>/etc/<name></i> only if the files do not exist.
234: If the files exist, display a message that says such-and-such files need
235: to be modified. This also guarantees that the files will be included in
236: the package since everything under <i>/usr/local</i> is included in the PLIST
237:
238: <p>
239: The OpenBSD file locations are:
240: <pre>
1.1 marc 241: user executables: /usr/local/bin
242: system admin executables: /usr/local/sbin
243: program executables: /usr/local/libexec
244: libraries /usr/local/lib
1.14 rohee 245: architecture dependent data /usr/local/lib/<name>
1.1 marc 246: installed include files: /usr/local/include or
1.14 rohee 247: /usr/local/include/<name>
248: single-machine data: /etc or /etc/<name>
1.1 marc 249: local state: /var/run
250: GNU info files: /usr/local/info
251: man pages: /usr/local/man/...
1.14 rohee 252: read-only architecture-independent: /usr/local/share/<name>
253: misc documentation: /usr/local/share/doc/<name>
1.20 turan 254: </pre>
1.9 espie 255:
1.20 turan 256: <p><li>
257: Begin a cycle of makes until the port is ready. Patch (see above)
258: clean, and make until the port is generated. Get rid of all warnings
259: if possible, especially security related warnings.
260: <p><li>
261: Control SEPARATE_BUILD semantics.
262: You have to do this only if the port builds with
263: SEPARATE_BUILD defined.
264: Ideally, the port should no longer modify any file in
265: ${WRKSRC} after <b>make patch</b>.
266: You can check this by making sure you don't have any write access
267: to ${WRKSRC}. Then you can set
268: SEPARATE_BUILD=concurrent: someone can use the same
269: source tree to build on distinct arches simultaneously.
270: Otherwise, set <code>SEPARATE_BUILD=simple</code>: building on
271: distinct arches simultaneously may meet with problems, as some
272: source files may be regenerated at awkward moments.
1.9 espie 273:
1.20 turan 274: <p><li>
275: Edit <i>pkg/DESCR</i>, <i>pkg/COMMENT</i>, <i>pkg/PLIST</i>.
276: <ul>
277: <li>
278: COMMENT is a <strong>SHORT</strong> one-line description of the port
279: (max. 60 characters). Do NOT include the package name (or version number
280: of the software) in the comment. Do NOT start with an uppercase letter
281: unless semantically significant, do NOT end with a period.
282: <li>
283: DESCR is a longer description of the port. One to a few paragraphs
284: concisely explaining what the port does is sufficient.
285: <li>
286: PLIST is kept empty at this point.
287: </ul>
288:
289: <p><li>
290: Install the application with <b>make install</b>
291: <p>
292: If the port installs dynamic libraries, check their symbol tables
293: with <code>nm</code>, as some mistaken software strips dynamic libraries,
294: which may lead to weird failures later.
295:
296: <p><li>
297: <strong>Check port for security holes again</strong>. This is
298: especially important for network and setuid programs. See
299: <a href="porting.html#security">our security recommendations</a>
300: for that. Log interesting stuff and fixes in the
301: <code>pkg/SECURITY</code> file. This file
302: should list audited potential problems, along with relevant patches,
303: so that another person can see at first glance what has been done.
304: Example:
1.14 rohee 305: <pre>
306: $OpenBSD$
1.9 espie 307:
308: ${WRKDIR}/receiver.c
309: call to mktemp (wrapper function do_mktemp) does seem to be correct.
310:
311: The server makes extensive use of strlcpy/strlcat/snprintf.
1.20 turan 312: </pre>
313:
314: <p><li>
315: Create pkg/PLIST. After the install is complete use the developer's command,
316: <b>make plist</b> which makes the file PLIST-auto in the <i>pkg</i> directory.
317: This file is a candidate packing list.
318: <p>
319: Beware! The files are found by timestamp. This means it does NOT:
320: <ul>
321: <li>
322: list any files installed with `tar' as their timestamp
323: will not change and thus won't be found by `find'
324: <li>
325: Update the <code>info/dir</code> file if .info files are added.
326: Also, be sure that the <code>info/dir</code> is not part of the PLIST.
327: <li>
328: Try to do anything special with links or symbolic links. A
329: cursory test of tar shows it does the right thing with links
330: and symbolic links so I don't see why we need to special case
331: anything in the packing list. But still...
332: </ul>
333: <p>
334: Peruse `PLIST-auto' and verify that everything was installed and
335: that it was installed in the proper locations. Anything not installed
336: can be added to a port Makefile `post-install' rule.
337: <p>
338: Move `PLIST-auto' to `PLIST'
339:
340: <p>
341: Ports that install shared libraries will need two versions of the PLIST file.
342: <ul>
343: <li>
344: PLIST describes the files installed on those architectures that support
345: shared libraries.
346: <li>
347: PLIST.noshared describes the files installed on architectures that do not
348: support shared libs.
349: <li>
350: Typically, PLIST.noshared is a copy of PLIST less references to any
351: shared libraries.
352: </ul>
353:
354: <p><li>
355: Keep repeating uninstall and reinstall until perfect.<br>
356: <em>Perfect</em> is when everything installs and uninstalls
357: in its proper location. `pkg_delete <pkg_name>' is
358: used to uninstall. `sudo make reinstall' is used to reinstall. See the
359: `pkg_create' man page for other commands that may be added
360: to PLIST to ensure all is cleaned up. After an uninstall the command
361: <p><code>find /usr/local -newer work/.install_started -print</code>
362: <p>should only list standard directory names.
363:
364: <p><li>
365: Test the packaging:<br>
366: After the port installs correctly issue the command
367: <code>make package</code> to create a package. To test the
368: package first do a <code>pkg_delete</code> and then do a
369: <code>pkg_add</code> The results after an add should EXACTLY
370: match the results after a `make install'.
1.9 espie 371:
1.20 turan 372: <p><li>
373: Mail <a href="mailto:ports@openbsd.org">ports@openbsd.org</a> with a short
374: note asking for comments and testing. Attach the port to this email and
375: sent it out. If you don't get any comments, send email to
376: <a href="turan@openbsd.org">turan@openbsd.org</a> and I will pick it for you.
377: <p>
378: Try to get others to test it on a variety of platforms for you.
379: <ul><li>
380: The DEC Alpha is good because it has only static libraries and because
381: sizeof(int) != sizeof(long)
382: <li>
383: Sun SPARC is good because it is very common and because its byte order is
384: the reverse of i386; if you developed on SPARC, of course, you'd want it
385: tested on i386).
386: <p>
387: </ul>
388:
389: <p><li>
390: Incorporate any feedback you get. Test it again on your platform.
391: Get those who gave you feedback to test it again from your new port.
392:
393: <p><li>
394: Finally, include it in the "ports" tree.
395: <p>
396: If you do not have CVS access, ask someone on
397: <a href="ports@openbsd.org">ports@openbsd.org</a> to commit it. Don't forget
398: about me, <a href="turan@openbsd.org">turan@openbsd.org</a> if no one
399: picks it up.
1.9 espie 400:
1.20 turan 401: <p><li>
402: If you are a developer with CVS access, check it in.
403: We normally use "import" for a new port,
404: rather than adding a zillion (or a dozen) files individually.
405: Import uses "vendor branch" version numbers like 1.1.1.1, but don't worry
406: about that! :-) If you make changes to a specific file (edit, then
407: cvs commit), it will be 1.2, and that will be used.
408: <p>
409: In short, import is typically used when a port is created.
410: From that point on cvs add and cvs rm are typically used to add or remove
411: files, and the normal edit->commit cycle for changes.
412: You might use something like this:
413: <pre>
1.4 ian 414: cd kaffe1
415: make clean # you really really don't want to check in all of work!
416: cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \
417: <I>YourName</I> <I>YourName_YYYY-MMM-DD</I>
1.20 turan 418: </pre>
419: <ul><li>
420: -d cvs.openbsd.org:/cvs says where cvs lives. This can be omitted if you
1.21 ! form 421: have a CVSROOT environment variable defined.
1.20 turan 422: <li>
423: -m 'kaffe port' is your login message. Change it to whatever you like
424: <li>
425: ports/lang/kaffe1 is the path relative to /cvs where the port lives
426: <li>
427: <i>YourName</i> (replaced with your login name) is the "vendor tag".
428: You imported it so you are the vendor.
429: <li>
430: <i>YourName_YYYY-MMM-DD</i> (e.g., ian_2000-Jan-01)
431: is the 'vendor release tag'. This is as good as any.
432: </ul>
433: As a real example, here is the output of checking in the Kaffe1 port,
434: which one of us did on September 8, 1998:
435: <pre>
1.4 ian 436: $ cd kaffe1
437: $ make clean >/dev/null
438: $ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08
439: ian@cvs.openbsd.org's password: (not shown, obviously)
440: I ports/lang/kaffe1/CVS
441: I ports/lang/kaffe1/files/CVS
442: I ports/lang/kaffe1/pkg/CVS
443: N ports/lang/kaffe1/Makefile
444: cvs server: Importing /cvs/ports/lang/kaffe1/files
445: N ports/lang/kaffe1/files/md5
446: cvs server: Importing /cvs/ports/lang/kaffe1/pkg
447: N ports/lang/kaffe1/pkg/COMMENT
448: N ports/lang/kaffe1/pkg/DESCR
449: N ports/lang/kaffe1/pkg/PLIST
450:
451: No conflicts created by this import
452: $
1.20 turan 453: </pre>
454:
455: <p><li>
456: Last but not least, add a one-line entry for the new port
457: in its parent directory's makefile, i.e., for ports/lang/kaffe1,
458: add it to ports/lang/Makefile.
459:
460: <p><li>
461: Maintain the port! As time goes by, problems may arise, or new versions
462: of the software may be released. You should strive to keep your port up
463: to date. In other words - iterate, test, test, iterate, ...
464: </ul>
465:
466: Thank you for supporting the OpenBSD "ports" process!
467: <hr>
468: <a href="porting.html"><img height=24 width=24 src=back.gif
469: border=0 alt=Porting></a>
470: <a href="mailto:www@openbsd.org">www@openbsd.org</a>
1.21 ! form 471: <br><small>$OpenBSD: checklist.html,v 1.20 2000/03/10 17:13:13 turan Exp $</small>
1.20 turan 472: </body>
1.1 marc 473: </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