Annotation of www/checklist.html, Revision 1.19
1.14 rohee 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1.1 marc 2: <html>
3: <head>
4: <meta http-equiv="Content-Type"
5: content="text/html; charset=iso-8859-1">
6: <meta name="resource-type"
7: content="document">
8: <meta name="description"
1.3 marc 9: CONTENT="How to make an OpenBSD port; porting checklist">
1.1 marc 10: <meta name="keywords"
11: content="openbsd,ports">
12: <meta name="distribution"
13: content="global">
14: <meta name="copyright"
15: content="This document copyright 1998 by the OpenBSD project">
1.3 marc 16: <title>OpenBSD Porting Checklist</title>
1.1 marc 17: <link rev="made" HREF="mailto:www@openbsd.org">
18: </head>
19: <body text="#000000" bgcolor="#FFFFFF" link="#23238E">
20: <img height=30 width=141 src=images/smalltitle.gif alt="[OpenBSD]" >
21:
1.14 rohee 22: <h2><font color="#e00000">OpenBSD Porting Checklist</font></h2>
1.1 marc 23:
24: I use this checklist as a reminder of things to do when creating
25: new ports and when validating old ports. I don't claim this list
26: is totally accurate, much less perfect, but only hope that some
1.3 marc 27: find it useful. Direct any questions and/or comments to me at
1.14 rohee 28: <a href="mailto:marc@snafu.org">marc@snafu.org</a>.
1.1 marc 29: <p>
30: <ol>
1.4 ian 31: <li>To avoid duplication, subscribe to the ports@openbsd.org
32: mailing list - somebody may be already working on the same port as you.
33: <p>
1.11 marc 34: <li>Create Makefile -- start with the provided Makefile template
1.15 espie 35: <code>/usr/ports/infrastructure/templates/Makefile.template</code>.
36: This file can be retrieved from any of the anoncvs servers or via the
1.14 rohee 37: OpenBSD cvs/web source browser system
1.11 marc 38: <a href="http://www.openbsd.org/cgi-bin/cvsweb/">http://www.openbsd.org/cgi-bin/cvsweb/</a>.
1.1 marc 39: <p>
1.15 espie 40: <li><code>make fetch-all</code><br>
1.1 marc 41: This verifies that the master site, distname, and extract suffix are
1.15 espie 42: correct. This should fetch <strong>all</strong> files needed for
43: that port, not only those corresponding to current option or the
44: current architecture.
1.1 marc 45: <p>
46: <li><code>make makesum</code><br>
47: This creates the files directory and the md5 checksum for the
48: fetched files.
49: <p>
50: <li><code>make extract</code><br>
51: Ensures that the file can be extracted into the work directory.
1.14 rohee 52: This also verifies that the checksum created in step 4 is good.
1.1 marc 53: <p>
54: <li>Create initial patches<br>
55: When the extract is complete cd to the work directory and read
1.19 ! espie 56: any install docs. You may need to modify the WRKDIST variable
1.1 marc 57: in the makefile as well as generate initial patches to configure
1.14 rohee 58: for OpenBSD.
1.17 marc 59: <p>Note: Patches go in the directory `patches' and are named patch-xx
1.1 marc 60: where xx should be aa, ab, ..., az, ba, bb ... zz.
61: <ul>
1.18 espie 62: <li>only patch one source file per patchfile, please,
63: <li>use diff -p -u to generate patches,
1.19 ! espie 64: <li>all patches MUST be relative to ${WRDIST},
1.18 espie 65: <li>check that patches <strong>DON'T</strong> contain tags that cvs
66: will replace,
1.17 marc 67: <li>add a small explanation of the patch role in the patchfile before
1.14 rohee 68: the patch itself, and an OpenBSD CVS tag
1.18 espie 69: <code>$OpenBSD$</code>.
1.1 marc 70: </ul>
71: <p>
72: <li><code>make patch</code><br>
73: this will apply patches to the extracted sources. If you want
74: to see the output use the command:
75: <p><code>make PATCH_DEBUG=YES patch</code>
1.7 espie 76: <p>The easiest way to re-run patches is to `make clean && make patch'.
1.1 marc 77: This will delete the work directory and re-extract and patch.
78: <p>
79: <li>add configuration options to Makefile and/or create configuration
80: script.<br>
81: You can add a port configuration script named `configure' to a
82: directory named scripts. This will be run before any
83: configuration specified by GNU_CONFIGURE or HAS_CONFIGURE is run.
84: <p>If GNU_CONFIGURE is used you may want to run ./configure --help
1.14 rohee 85: to see what options are available. Anything that you may want to
1.1 marc 86: override can be changed by adding the --option flags to the
87: CONFIGURE_ARGS parameter in the Makefile
88: <p>
1.12 espie 89: <li>try setting <code>SEPARATE_BUILD</code><br>
90: If the port can build with object files outside its source tree,
91: this is cleaner (many programs using <code>GNU_CONFIGURE</code> can),
92: and may help people who mount their ports tree on several arches.
93: This can also spare you some effort, as you will possibly be able to
94: restart the cycle at <code>configure</code> most of the time.
95: <p>
1.1 marc 96: <li><code>make configure</code><br>
97: Peruse the output (if any) and tweak any options in the Makefile.
1.14 rohee 98: To repeat issue the command
99: `<code>make clean && make configure</code>'.
100: <p>Note: make sure host dependent files go in <code>/etc</code> or
101: <code>/etc/<name></code>, but NEVER replace existing files
102: in <code>/etc</code>. Best to have install place
103: in <code>/usr/local/lib/<name></code> and then copy to
104: <code>/etc</code> or
105: <code>/etc/<name></code> only if the files do not exist.
1.1 marc 106: <p>The OpenBSD file locations are:
1.9 espie 107:
1.1 marc 108: <pre>
109: user executables: /usr/local/bin
110: system admin executables: /usr/local/sbin
111: program executables: /usr/local/libexec
112: libraries /usr/local/lib
1.14 rohee 113: architecture dependent data /usr/local/lib/<name>
1.1 marc 114: installed include files: /usr/local/include or
1.14 rohee 115: /usr/local/include/<name>
116: single-machine data: /etc or /etc/<name>
1.1 marc 117: local state: /var/run
118: GNU info files: /usr/local/info
119: man pages: /usr/local/man/...
1.14 rohee 120: read-only architecture-independent: /usr/local/share/<name>
121: misc documentation: /usr/local/share/doc/<name>
1.1 marc 122: </pre>
1.9 espie 123:
1.1 marc 124: <p>
125: <li><code>make</code><br>
126: Begin a cycle of makes until the port is ready. Patch (see above)
127: clean, and make until the port is generated. Get rid of all warnings
128: if possible, especially security related warnings.
129: <p>
1.12 espie 130: <li>Control <code>SEPARATE_BUILD</code> semantics<br>
131: You have to do this only if the port builds with
132: <code>SEPARATE_BUILD</code> defined.
133: Ideally, the port should no longer modify any file in
134: <code>${WRKSRC}</code> after <code>make patch</code>.
135: You can check this by making sure you don't have any write access
136: to <code>${WRKSRC}</code>. Then you can set
137: <code>SEPARATE_BUILD=concurrent</code>: someone can use the same
138: source tree to build on distinct arches simultaneously.
139: Otherwise, set <code>SEPARATE_BUILD=simple</code>: building on
140: distinct arches simultaneously may meet with problems, as some
141: source files may be regenerated at awkward moments.
142: <p>
1.1 marc 143: <li><code>mkdir pkg; touch pkg/{DESCR,COMMENT,PLIST}</code><br>
144: Create dummy versions of the package files. Edit DESCR and COMMENT.
1.7 espie 145: <p>COMMENT is a <strong>SHORT</strong> one-line description of the port
1.14 rohee 146: (max. 60 characters). Do NOT include the package name (or version number
1.17 marc 147: of the software) in the comment. Do NOT start with an uppercase letter
148: unless semantically significant, do NOT end with a period.
1.1 marc 149: <p>DESCR is a longer description of the port. One to a few paragraphs
150: concisely explaining what the port does is sufficient.
151: <p>PLIST is kept empty at this point.
152: <p>
153: <li><code>sudo make install</code><br>
154: install the application.
155: <p>
1.16 espie 156: <li>If the port installs dynamic libraries, check their symbol tables
157: with <code>nm</code>, as some mistaken software strips dynamic libraries,
158: which may lead to weird failures later.
159: <p>
1.9 espie 160: <li><strong>Check port for security holes again</strong>. This is
161: especially important for network and setuid programs. See
162: <a href="porting.html#security">our security recommendations</a>
163: for that. Log interesting stuff and fixes in the
164: <code>pkg/SECURITY</code> file. This file
165: should list audited potential problems, along with relevant patches,
166: so that another person can see at first glance what has been done.
167: Example:
168:
1.14 rohee 169: <pre>
170: $OpenBSD$
1.9 espie 171:
172: ${WRKDIR}/receiver.c
173: call to mktemp (wrapper function do_mktemp) does seem to be correct.
174:
175: The server makes extensive use of strlcpy/strlcat/snprintf.
176:
177: </pre>
178:
1.1 marc 179: <li>Create pkg/PLIST<br>
1.17 marc 180: After the install is complete use the developer's command:
1.1 marc 181: <p><code>make plist</code>
1.17 marc 182: <p>which makes the file PLIST-auto in the pkg directory. This file
1.1 marc 183: is a candidate packing list. Beware: the files are found by
184: timestamp. This means it does NOT:
185: <ul>
186: <li>list any files installed with `tar' as their timestamp
187: will not change and thus won't be found by `find'
188: <li>update the <code>info/dir</code> file if .info files are
189: added. You'll have to add that by hand. Also, be sure that
190: the <code>info/dir</code> is not part of the PLIST.
191: <li>try to do anything special with links or symbolic links. A
192: cursory test of tar shows it does the right thing with links
193: and symbolic links so I don't see why we need to special case
194: anything in the packing list. But still...
195: </ul>
196: <p>Peruse `PLIST-auto' and verify that everything was installed and
197: that it was installed in the proper locations. Anything not installed
198: can be added to a port Makefile `post-install' rule.
199: <p>Copy `PLIST-auto' to `PLIST'
1.10 marc 200: <p>Ports that install shared libraries will need two versions of
201: the PLIST file. <code>PLIST</code> describes the files installed on
202: those architectures that support shared libraries, and
1.13 wvdputte 203: <code>PLIST.noshared</code> describes the files installed on
1.10 marc 204: architectures that do not support shared libs. Typically,
205: <code>PLIST.noshared</code> is a copy of <code>PLIST</code>
206: less references to any shared libraries.
1.1 marc 207: <p>
208: <li>uninstall and reinstall; repeat until perfect.<br>
209: <em>Perfect</em> is when everything installs and uninstalls
1.17 marc 210: in its proper location. `<code>pkg_delete <pkg_name></code>' is
1.14 rohee 211: used to uninstall. `sudo make reinstall' is used to reinstall. See the
212: `<code>pkg_create</code>' man page for other commands that may be added
213: to PLIST to ensure all is cleaned up. After an uninstall the command
1.1 marc 214: <p><code>find /usr/local -newer work/.install_started -print</code>
215: <p>should only list standard directory names.
216: <p>
217: <li>Create package:<br>
218: After the port installs correctly issue the command
219: <code>make package</code> to create a package. To test the
220: package first do a <code>pkg_delete</code> and then do a
221: <code>pkg_add</code> The results after an add should EXACTLY
222: match the results after a `make install'.
1.4 ian 223: <p>
1.14 rohee 224: <li>Distribute it!<br>
1.4 ian 225: Since the whole point of this process
226: is to make your ported version of the software available to
227: other OpenBSD users, you now need to disseminate it.
1.14 rohee 228: <ul>
229: <li>First, get others to test it on a variety of
230: platforms (the DEC Alpha is good because it has only static libraries
1.4 ian 231: and because sizeof int != sizeof long; Sun SPARC is good because it is
232: very common and because its byte order is the reverse of i386; if you
1.17 marc 233: developed on SPARC, of course, you'd want it tested on i386).
1.4 ian 234: <P>The ports@openbsd mailing list is a good place to find porting-savy
235: people with different platforms!
1.14 rohee 236: <li>Incorporate any feedback you get. Test it again on your platform.
1.4 ian 237: Get those who gave you feedback to test it again from your new port.
1.14 rohee 238: <li>Finally, include it in the "ports" tree.
1.4 ian 239: If you are a developer with CVS access, check it in.
240: We normally use "import" for a new port,
241: rather than adding a zillion (or a dozen) files individually.
242: Import uses "vendor branch" version numbers like 1.1.1.1, but don't worry
243: about that! :-) If you make changes to a specific file (edit, then
244: cvs commit), it will be 1.2, and that will be used.
245: <P>
246: In short, import is typically used when a port is created.
247: From that point on cvs add and cvs rm are typically used to add or remove
248: files, and the normal edit->commit cycle for changes.
249: <P>
250: You might use something like this:
1.14 rohee 251: <pre>
1.4 ian 252: cd kaffe1
253: make clean # you really really don't want to check in all of work!
254: cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \
255: <I>YourName</I> <I>YourName_YYYY-MMM-DD</I>
1.14 rohee 256: </pre>
1.4 ian 257: <P>-d cvs.openbsd.org:/cvs says where cvs lives. This can be omitted if you
258: have a CVS_ROOT environment variable defined.
259: <P>-m 'kaffe port' is your login message. Change it to whatever you like
260: <P>ports/lang/kaffe1 is the path relative to /cvs where the port lives
261: <P><I>YourName</I> (replaced with your login name) is the "vendor tag".
262: You imported it so you are the vendor.
263: <P><I>YourName_YYYY-MMM-DD</I> (e.g., ian_2000-Jan-01)
264: is the 'vendor release tag'. This is as good as any.
265: <P>As a real example, here is the output of checking in the Kaffe1 port,
266: which one of us did on September 8, 1998:
1.14 rohee 267: <pre>
1.4 ian 268: $ cd kaffe1
269: $ make clean >/dev/null
270: $ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08
271: ian@cvs.openbsd.org's password: (not shown, obviously)
272: I ports/lang/kaffe1/CVS
273: I ports/lang/kaffe1/files/CVS
274: I ports/lang/kaffe1/pkg/CVS
275: N ports/lang/kaffe1/Makefile
276: cvs server: Importing /cvs/ports/lang/kaffe1/files
277: N ports/lang/kaffe1/files/md5
278: cvs server: Importing /cvs/ports/lang/kaffe1/pkg
279: N ports/lang/kaffe1/pkg/COMMENT
280: N ports/lang/kaffe1/pkg/DESCR
281: N ports/lang/kaffe1/pkg/PLIST
282:
283: No conflicts created by this import
284: $
1.14 rohee 285: </pre>
1.5 ian 286: <P>Last but not least, add a one-line entry for the new port
287: in its parent directory's makefile, i.e., for ports/lang/kaffe1,
288: add it to ports/lang/Makefile.
1.4 ian 289: <P>If you do not have CVS commit access, send mail to the ports
290: maintainers at ports@openbsd.org,
291: stating that you have a port ready to go into the tree. List the
292: name and version of the program, the platforms it's been tested on,
293: and any limitations.
294: </UL>
295: <P>
296: <LI>Maintain the port!<BR>
297: As time goes by, problems may arise, or new versions of the software
298: may be released. You should strive to keep your port up to date.
299: In other words - iterate, test, test, iterate, ...
1.1 marc 300: </ol>
1.4 ian 301: Thank you for supporting the OpenBSD "ports" process!
1.1 marc 302: <hr>
303: <a href="porting.html"><img height=24 width=24 src=back.gif
304: border=0 alt=Porting></a>
1.14 rohee 305: <a href="mailto:www@openbsd.org">www@openbsd.org</a>
1.19 ! espie 306: <br><small>$OpenBSD: checklist.html,v 1.18 1999/11/02 15:45:33 espie Exp $</small>
1.1 marc 307: </body>
308: </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