Annotation of www/checklist.html, Revision 1.8
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.1 marc 33: <li>Create Makefile -- start with this skeleton
34: <a href="#makefile">makefile</a>.
35: <p>
36: <li><code>make fetch</code><br>
37: This verifies that the master site, distname, and extract suffix are
38: correct.
39: <p>
40: <li><code>make makesum</code><br>
41: This creates the files directory and the md5 checksum for the
42: fetched files.
43: <p>
44: <li><code>make extract</code><br>
45: Ensures that the file can be extracted into the work directory.
46: This also verifies that the checksum created in step 3 is good.
47: <p>
48: <li>Create initial patches<br>
49: When the extract is complete cd to the work directory and read
50: any install docs. You may need to modify the WRKSRC variable
51: in the makefile as well as generate initial patches to configure
52: for openbsd.
53: <p>Note: Patches go in the directory `patches' and are names patch-xx
54: where xx should be aa, ab, ..., az, ba, bb ... zz.
55: <ul>
56: <li>only patch one source file per patchfile, please
57: <li>use diff -u to generate patches
58: <li>all patches MUST be relative to ${WRKSRC}
59: </ul>
60: <p>
61: <li><code>make patch</code><br>
62: this will apply patches to the extracted sources. If you want
63: to see the output use the command:
64: <p><code>make PATCH_DEBUG=YES patch</code>
1.7 espie 65: <p>The easiest way to re-run patches is to `make clean && make patch'.
1.1 marc 66: This will delete the work directory and re-extract and patch.
67: <p>
68: <li>add configuration options to Makefile and/or create configuration
69: script.<br>
70: You can add a port configuration script named `configure' to a
71: directory named scripts. This will be run before any
72: configuration specified by GNU_CONFIGURE or HAS_CONFIGURE is run.
73: <p>If GNU_CONFIGURE is used you may want to run ./configure --help
74: to see what options are available. Anything thay you may want to
75: override can be changed by adding the --option flags to the
76: CONFIGURE_ARGS parameter in the Makefile
77: <p>
78: <li><code>make configure</code><br>
79: Peruse the output (if any) and tweak any options in the Makefile.
1.7 espie 80: To repeat issue the command `make clean && make configure'.
1.1 marc 81: <p>Note: make sure host dependent files go in /etc or /etc/<name>, but
82: NEVER replace existing files in /etc. Best to have install place
83: in /usr/local/lib/<name> and then copy to /etc or /etc/<name> only
84: the files do not exist.
85: <p>The OpenBSD file locations are:
86: <pre>
87: user executables: /usr/local/bin
88: system admin executables: /usr/local/sbin
89: program executables: /usr/local/libexec
90: libraries /usr/local/lib
91: architecture dependent data /usr/local/lib/<name>
92: installed include files: /usr/local/include or
93: /usr/local/include/<name>
94: single-machine data: /etc or /etc/<name>
95: local state: /var/run
96: GNU info files: /usr/local/info
97: man pages: /usr/local/man/...
98: read-only architecture-independent: /usr/local/share/<name>
99: misc documentation: /usr/local/share/doc/<name>
100: </pre>
101: <p>
102: <li><code>make</code><br>
103: Begin a cycle of makes until the port is ready. Patch (see above)
104: clean, and make until the port is generated. Get rid of all warnings
105: if possible, especially security related warnings.
106: <p>
107: <li><code>mkdir pkg; touch pkg/{DESCR,COMMENT,PLIST}</code><br>
108: Create dummy versions of the package files. Edit DESCR and COMMENT.
1.7 espie 109: <p>COMMENT is a <strong>SHORT</strong> one-line description of the port
110: (max. 60 characters). Do NOT include the
1.1 marc 111: package name (or version number of the software) in the comment.
112: <p>DESCR is a longer description of the port. One to a few paragraphs
113: concisely explaining what the port does is sufficient.
114: <p>PLIST is kept empty at this point.
115: <p>
116: <li><code>sudo make install</code><br>
117: install the application.
118: <p>
119: <li>Create pkg/PLIST<br>
120: After the install is complete use the developers command:
121: <p><code>make plist</code>
122: <p>which makes a the file PLIST-auto in the pkg directory. This file
123: is a candidate packing list. Beware: the files are found by
124: timestamp. This means it does NOT:
125: <ul>
126: <li>list any files installed with `tar' as their timestamp
127: will not change and thus won't be found by `find'
128: <li>update the <code>info/dir</code> file if .info files are
129: added. You'll have to add that by hand. Also, be sure that
130: the <code>info/dir</code> is not part of the PLIST.
131: <li>try to do anything special with links or symbolic links. A
132: cursory test of tar shows it does the right thing with links
133: and symbolic links so I don't see why we need to special case
134: anything in the packing list. But still...
135: </ul>
136: <p>Peruse `PLIST-auto' and verify that everything was installed and
137: that it was installed in the proper locations. Anything not installed
138: can be added to a port Makefile `post-install' rule.
139: <p>Copy `PLIST-auto' to `PLIST'
140: <p>
141: <li>uninstall and reinstall; repeat until perfect.<br>
142: <em>Perfect</em> is when everything installs and uninstalls
143: in its proper location. `pkg_delete <pkg_name>' is used to
144: uninstall. `sudo make reinstall' is used to reinstall. See the
145: `pkg_create' man page for other commands that may be added to PLIST
146: to ensure all is cleaned up. After an uninstall the command
147: <p><code>find /usr/local -newer work/.install_started -print</code>
148: <p>should only list standard directory names.
149: <p>
150: <li>Create package:<br>
151: After the port installs correctly issue the command
152: <code>make package</code> to create a package. To test the
153: package first do a <code>pkg_delete</code> and then do a
154: <code>pkg_add</code> The results after an add should EXACTLY
155: match the results after a `make install'.
1.4 ian 156: <p>
157: <LI>Distribute it!</BR>
158: Since the whole point of this process
159: is to make your ported version of the software available to
160: other OpenBSD users, you now need to disseminate it.
161: <UL>
162: <LI>First, get others to test it on a variety of
163: platforms (the DEC Alpha is good because it has only static libraries
164: and because sizeof int != sizeof long; Sun SPARC is good because it is
165: very common and because its byte order is the reverse of i386; if you
166: developed on SPARC, of course, you'd want it tested on i386).
167: <P>The ports@openbsd mailing list is a good place to find porting-savy
168: people with different platforms!
169: <LI>Incorporate any feedback you get. Test it again on your platform.
170: Get those who gave you feedback to test it again from your new port.
171: <LI>Finally, include it in the "ports" tree.
172: If you are a developer with CVS access, check it in.
173: We normally use "import" for a new port,
174: rather than adding a zillion (or a dozen) files individually.
175: Import uses "vendor branch" version numbers like 1.1.1.1, but don't worry
176: about that! :-) If you make changes to a specific file (edit, then
177: cvs commit), it will be 1.2, and that will be used.
178: <P>
179: In short, import is typically used when a port is created.
180: From that point on cvs add and cvs rm are typically used to add or remove
181: files, and the normal edit->commit cycle for changes.
182: <P>
183: You might use something like this:
184: <PRE>
185: cd kaffe1
186: make clean # you really really don't want to check in all of work!
187: cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \
188: <I>YourName</I> <I>YourName_YYYY-MMM-DD</I>
189: </PRE>
190: <P>-d cvs.openbsd.org:/cvs says where cvs lives. This can be omitted if you
191: have a CVS_ROOT environment variable defined.
192: <P>-m 'kaffe port' is your login message. Change it to whatever you like
193: <P>ports/lang/kaffe1 is the path relative to /cvs where the port lives
194: <P><I>YourName</I> (replaced with your login name) is the "vendor tag".
195: You imported it so you are the vendor.
196: <P><I>YourName_YYYY-MMM-DD</I> (e.g., ian_2000-Jan-01)
197: is the 'vendor release tag'. This is as good as any.
198: <P>As a real example, here is the output of checking in the Kaffe1 port,
199: which one of us did on September 8, 1998:
200: <PRE>
201: $ cd kaffe1
202: $ make clean >/dev/null
203: $ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08
204: ian@cvs.openbsd.org's password: (not shown, obviously)
205: I ports/lang/kaffe1/CVS
206: I ports/lang/kaffe1/files/CVS
207: I ports/lang/kaffe1/pkg/CVS
208: N ports/lang/kaffe1/Makefile
209: cvs server: Importing /cvs/ports/lang/kaffe1/files
210: N ports/lang/kaffe1/files/md5
211: cvs server: Importing /cvs/ports/lang/kaffe1/pkg
212: N ports/lang/kaffe1/pkg/COMMENT
213: N ports/lang/kaffe1/pkg/DESCR
214: N ports/lang/kaffe1/pkg/PLIST
215:
216: No conflicts created by this import
217: $
218: </PRE>
1.5 ian 219: <P>Last but not least, add a one-line entry for the new port
220: in its parent directory's makefile, i.e., for ports/lang/kaffe1,
221: add it to ports/lang/Makefile.
1.4 ian 222: <P>If you do not have CVS commit access, send mail to the ports
223: maintainers at ports@openbsd.org,
224: stating that you have a port ready to go into the tree. List the
225: name and version of the program, the platforms it's been tested on,
226: and any limitations.
227: </UL>
228: <P>
229: <LI>Maintain the port!<BR>
230: As time goes by, problems may arise, or new versions of the software
231: may be released. You should strive to keep your port up to date.
232: In other words - iterate, test, test, iterate, ...
1.1 marc 233: </ol>
1.4 ian 234: Thank you for supporting the OpenBSD "ports" process!
1.1 marc 235: <hr>
236: <a name=makefile>
237: <h2><font color=#e00000>Skeleton ports makefile</font></h2>
238: </a>
239:
240: <code>;;;</code> indicates values that must be supplied by the
1.8 ! marc 241: porter. <strong>Remove extraneous comments when done.</strong>
1.1 marc 242: <pre>
1.8 ! marc 243: # $OpenBSD: checklist.html,v 1.7 1998/11/19 04:14:56 espie Exp $
1.1 marc 244: #
245:
246: # What port/package will be created
247: #
248: DISTNAME= ;;;
249: #DIST_SUBDIR= ;;;
250: #PKGNAME= ;;;
251: CATEGORIES= ;;;
252:
253: # Reasons why the port/package shouldn't be built
254: #
255: #COMES_WITH= 2.3
256: #ONLY_FOR_ARCHS= list architectures here
257: #BROKEN= "reason"
1.8 ! marc 258: #NO_CDROM= "reason"
1.3 marc 259: #RESTRICTED= "reason"
1.8 ! marc 260: #MIRROR_DISTFILE= no
1.1 marc 261:
262: # where to send bitches about this port
263: #
264: MAINTAINER= ports@openbsd.org
265:
266: # where the source files and patches can be fetched
267: #
268: MASTER_SITES= ;;;
269: #MASTER_SITE_SUBDIR= ;;;
270: #DISTFILES= ;;;
271: #PATCH_SITES= ;;;
272: #PATCHFILES= ;;;
1.3 marc 273: #PATCH_DIST_STRIP= -p0
1.1 marc 274: #EXTRACT_SUFX= .tar.Z
275: #EXTRACT_CMD= ;;;
276: #EXTRACT_BEFORE_ARGS= ;;;
277: #EXTRACT_AFTER_ARGS= ;;;
278:
279: # Dependencies
280: #
281: #FETCH_DEPENDS= ;;;
282: #BUILD_DEPENDS= ;;;
283: #RUN_DEPENDS= ;;;
284: #LIB_DEPENDS= ;;;
285:
286: # Is the build automagic or is it interactive
287: #
288: #IS_INTERACTIVE= yes
289:
290: # build/configuration variables
291: #
292: #USE_GMAKE= yes
293: #USE_IMAKE= yes
294: #USE_X11= yes (assumed if USE_IMAKE is yes)
1.8 ! marc 295: #USE_AUTOCONF= yes
! 296: #GNU_CONFIGURE= yes (assumed if USE_AUTOCONF is yes)
1.1 marc 297: #HAS_CONFIGURE= yes (assumed if GNU_CONFIGURE is yes)
298: #CONFIGURE_SCRIPT= ;;; (if other than configure)
299: #.if (${MACHINE_ARCH} != "alpha")
300: #CONFIGURE_ARGS+= --enable-shared
301: #.endif
302: #CONFIGURE_ARGS+= --enable-static
1.8 ! marc 303: #CONFIGURE_ENV= ;;;
1.1 marc 304:
305: # Things that we don't want to do for this port/package
306: #
307: #NO_DEPENDS= yes
308: #NO_WRKDIR= yes
309: #NO_WRKSUBDIR= yes
310: #NO_CHECKSUM= yes
311: #NO_EXTRACT= yes
312: #NO_PATCH= yes
313: #NO_CONFIGURE= yes
314: #NO_BUILD= yes
315: #NO_INSTALL= yes
316: #NO_MTREE= yes
1.8 ! marc 317: #NO_PACKAGE= yes
! 318: #NO_PKG_REGISTER= yes
1.1 marc 319:
320: # This section is only needed if man pages are distributed in compressed
321: # form. Define MANCOMPRESSED and the man pages by section. The pages
322: # will be uncompressed after being installed.
323: #
324: #MANCOMPRESSED= yes
325: #MAN1= ;;;
326: #MAN3= ;;;
327: #MAN4= ;;;
328: #MAN5= ;;;
329: #MAN8= ;;;
330:
331: # Overrides for default values
332: #
333: #MAKEFILE= ;;;
334: #MAKE_FLAGS= ;;;
335: #MAKE_ENV= ;;;
336: #SCRIPTS_ENV= ;;;
337: #LDFLAGS= ;;;
338: #WRKDIR= ;;; if other than work
339: #WRKSRC= ;;; if other than ${WRKDIR}/$DISTNAME
340:
341: #ALL_TARGET= ;;;
342: #INSTALL_TARGET= ;;;
343:
344: # This target may be necessary if a shared library may have been created
345: #
346: #post-install:
347: # ${LDCONFIG} -m ${PREFIX}/lib
348:
349: .include <bsd.port.mk>
350: </pre>
351: <hr>
352: <a href="porting.html"><img height=24 width=24 src=back.gif
353: border=0 alt=Porting></a>
354: <a href=mailto:www@openbsd.org>www@openbsd.org</a>
1.8 ! marc 355: <br><small>$OpenBSD: checklist.html,v 1.7 1998/11/19 04:14:56 espie Exp $</small>
1.1 marc 356: </body>
357: </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