Annotation of www/checklist.html, Revision 1.20
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
! 421: have a CVS_ROOT environment variable defined.
! 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>
! 471: <br><small>$OpenBSD: checklist.html,v 1.19 2000/02/14 01:35:31 espie Exp $</small>
! 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