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