File: [local] / www / Attic / checklist.html (download) (as text)
Revision 1.5, Sun Sep 13 23:05:26 1998 UTC (25 years, 8 months ago) by ian
Branch: MAIN
Changes since 1.4: +5 -2 lines
Remind 'em to add to ../Makefile for completeness.
|
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="resource-type"
content="document">
<meta name="description"
CONTENT="How to make an OpenBSD port; porting checklist">
<meta name="keywords"
content="openbsd,ports">
<meta name="distribution"
content="global">
<meta name="copyright"
content="This document copyright 1998 by the OpenBSD project">
<title>OpenBSD Porting Checklist</title>
<link rev="made" HREF="mailto:www@openbsd.org">
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#23238E">
<img height=30 width=141 src=images/smalltitle.gif alt="[OpenBSD]" >
<h2><font color=#e00000>OpenBSD Porting Checklist</font></h2>
I use this checklist as a reminder of things to do when creating
new ports and when validating old ports. I don't claim this list
is totally accurate, much less perfect, but only hope that some
find it useful. Direct any questions and/or comments to me at
<a href=mailto:marc@snafu.org>marc@snafu.org</a>.
<p>
<ol>
<li>To avoid duplication, subscribe to the ports@openbsd.org
mailing list - somebody may be already working on the same port as you.
<p>
<li>Create Makefile -- start with this skeleton
<a href="#makefile">makefile</a>.
<p>
<li><code>make fetch</code><br>
This verifies that the master site, distname, and extract suffix are
correct.
<p>
<li><code>make makesum</code><br>
This creates the files directory and the md5 checksum for the
fetched files.
<p>
<li><code>make extract</code><br>
Ensures that the file can be extracted into the work directory.
This also verifies that the checksum created in step 3 is good.
<p>
<li>Create initial patches<br>
When the extract is complete cd to the work directory and read
any install docs. You may need to modify the WRKSRC variable
in the makefile as well as generate initial patches to configure
for openbsd.
<p>Note: Patches go in the directory `patches' and are names patch-xx
where xx should be aa, ab, ..., az, ba, bb ... zz.
<ul>
<li>only patch one source file per patchfile, please
<li>use diff -u to generate patches
<li>all patches MUST be relative to ${WRKSRC}
</ul>
<p>
<li><code>make patch</code><br>
this will apply patches to the extracted sources. If you want
to see the output use the command:
<p><code>make PATCH_DEBUG=YES patch</code>
<p>The easiest way to re-run patches is to `make clean && make patch'.
This will delete the work directory and re-extract and patch.
<p>
<li>add configuration options to Makefile and/or create configuration
script.<br>
You can add a port configuration script named `configure' to a
directory named scripts. This will be run before any
configuration specified by GNU_CONFIGURE or HAS_CONFIGURE is run.
<p>If GNU_CONFIGURE is used you may want to run ./configure --help
to see what options are available. Anything thay you may want to
override can be changed by adding the --option flags to the
CONFIGURE_ARGS parameter in the Makefile
<p>
<li><code>make configure</code><br>
Peruse the output (if any) and tweak any options in the Makefile.
To repeat issue the command `make clean && make configure'.
<p>Note: make sure host dependent files go in /etc or /etc/<name>, but
NEVER replace existing files in /etc. Best to have install place
in /usr/local/lib/<name> and then copy to /etc or /etc/<name> only
the files do not exist.
<p>The OpenBSD file locations are:
<pre>
user executables: /usr/local/bin
system admin executables: /usr/local/sbin
program executables: /usr/local/libexec
libraries /usr/local/lib
architecture dependent data /usr/local/lib/<name>
installed include files: /usr/local/include or
/usr/local/include/<name>
single-machine data: /etc or /etc/<name>
local state: /var/run
GNU info files: /usr/local/info
man pages: /usr/local/man/...
read-only architecture-independent: /usr/local/share/<name>
misc documentation: /usr/local/share/doc/<name>
</pre>
<p>
<li><code>make</code><br>
Begin a cycle of makes until the port is ready. Patch (see above)
clean, and make until the port is generated. Get rid of all warnings
if possible, especially security related warnings.
<p>
<li><code>mkdir pkg; touch pkg/{DESCR,COMMENT,PLIST}</code><br>
Create dummy versions of the package files. Edit DESCR and COMMENT.
<p>COMMENT is the one-line description of the port. Do NOT include the
package name (or version number of the software) in the comment.
<p>DESCR is a longer description of the port. One to a few paragraphs
concisely explaining what the port does is sufficient.
<p>PLIST is kept empty at this point.
<p>
<li><code>sudo make install</code><br>
install the application.
<p>
<li>Create pkg/PLIST<br>
After the install is complete use the developers command:
<p><code>make plist</code>
<p>which makes a the file PLIST-auto in the pkg directory. This file
is a candidate packing list. Beware: the files are found by
timestamp. This means it does NOT:
<ul>
<li>list any files installed with `tar' as their timestamp
will not change and thus won't be found by `find'
<li>update the <code>info/dir</code> file if .info files are
added. You'll have to add that by hand. Also, be sure that
the <code>info/dir</code> is not part of the PLIST.
<li>try to do anything special with links or symbolic links. A
cursory test of tar shows it does the right thing with links
and symbolic links so I don't see why we need to special case
anything in the packing list. But still...
</ul>
<p>Peruse `PLIST-auto' and verify that everything was installed and
that it was installed in the proper locations. Anything not installed
can be added to a port Makefile `post-install' rule.
<p>Copy `PLIST-auto' to `PLIST'
<p>
<li>uninstall and reinstall; repeat until perfect.<br>
<em>Perfect</em> is when everything installs and uninstalls
in its proper location. `pkg_delete <pkg_name>' is used to
uninstall. `sudo make reinstall' is used to reinstall. See the
`pkg_create' man page for other commands that may be added to PLIST
to ensure all is cleaned up. After an uninstall the command
<p><code>find /usr/local -newer work/.install_started -print</code>
<p>should only list standard directory names.
<p>
<li>Create package:<br>
After the port installs correctly issue the command
<code>make package</code> to create a package. To test the
package first do a <code>pkg_delete</code> and then do a
<code>pkg_add</code> The results after an add should EXACTLY
match the results after a `make install'.
<p>
<LI>Distribute it!</BR>
Since the whole point of this process
is to make your ported version of the software available to
other OpenBSD users, you now need to disseminate it.
<UL>
<LI>First, get others to test it on a variety of
platforms (the DEC Alpha is good because it has only static libraries
and because sizeof int != sizeof long; Sun SPARC is good because it is
very common and because its byte order is the reverse of i386; if you
developed on SPARC, of course, you'd want it tested on i386).
<P>The ports@openbsd mailing list is a good place to find porting-savy
people with different platforms!
<LI>Incorporate any feedback you get. Test it again on your platform.
Get those who gave you feedback to test it again from your new port.
<LI>Finally, include it in the "ports" tree.
If you are a developer with CVS access, check it in.
We normally use "import" for a new port,
rather than adding a zillion (or a dozen) files individually.
Import uses "vendor branch" version numbers like 1.1.1.1, but don't worry
about that! :-) If you make changes to a specific file (edit, then
cvs commit), it will be 1.2, and that will be used.
<P>
In short, import is typically used when a port is created.
From that point on cvs add and cvs rm are typically used to add or remove
files, and the normal edit->commit cycle for changes.
<P>
You might use something like this:
<PRE>
cd kaffe1
make clean # you really really don't want to check in all of work!
cvs -d cvs.openbsd.org:/cvs import -m 'kaffe port' ports/lang/kaffe1 \
<I>YourName</I> <I>YourName_YYYY-MMM-DD</I>
</PRE>
<P>-d cvs.openbsd.org:/cvs says where cvs lives. This can be omitted if you
have a CVS_ROOT environment variable defined.
<P>-m 'kaffe port' is your login message. Change it to whatever you like
<P>ports/lang/kaffe1 is the path relative to /cvs where the port lives
<P><I>YourName</I> (replaced with your login name) is the "vendor tag".
You imported it so you are the vendor.
<P><I>YourName_YYYY-MMM-DD</I> (e.g., ian_2000-Jan-01)
is the 'vendor release tag'. This is as good as any.
<P>As a real example, here is the output of checking in the Kaffe1 port,
which one of us did on September 8, 1998:
<PRE>
$ cd kaffe1
$ make clean >/dev/null
$ cvs import -m 'kaffe1.0(==JDK1.1) port' ports/lang/kaffe1 ian ian_1998-Sep-08
ian@cvs.openbsd.org's password: (not shown, obviously)
I ports/lang/kaffe1/CVS
I ports/lang/kaffe1/files/CVS
I ports/lang/kaffe1/pkg/CVS
N ports/lang/kaffe1/Makefile
cvs server: Importing /cvs/ports/lang/kaffe1/files
N ports/lang/kaffe1/files/md5
cvs server: Importing /cvs/ports/lang/kaffe1/pkg
N ports/lang/kaffe1/pkg/COMMENT
N ports/lang/kaffe1/pkg/DESCR
N ports/lang/kaffe1/pkg/PLIST
No conflicts created by this import
$
</PRE>
<P>Last but not least, add a one-line entry for the new port
in its parent directory's makefile, i.e., for ports/lang/kaffe1,
add it to ports/lang/Makefile.
<P>If you do not have CVS commit access, send mail to the ports
maintainers at ports@openbsd.org,
stating that you have a port ready to go into the tree. List the
name and version of the program, the platforms it's been tested on,
and any limitations.
</UL>
<P>
<LI>Maintain the port!<BR>
As time goes by, problems may arise, or new versions of the software
may be released. You should strive to keep your port up to date.
In other words - iterate, test, test, iterate, ...
</ol>
Thank you for supporting the OpenBSD "ports" process!
<hr>
<a name=makefile>
<h2><font color=#e00000>Skeleton ports makefile</font></h2>
</a>
<code>;;;</code> indicates values that must be supplied by the
porter. Remove extraneous comments when done.
<pre>
# OpenBSD makefile for: ;;;
# Version required: ;;;
# Date created: ;;;
# Whom: you@your.domain
#
# $OpenBSD: checklist.html,v 1.5 1998/09/13 23:05:26 ian Exp $
#
# What port/package will be created
#
DISTNAME= ;;;
#DIST_SUBDIR= ;;;
#PKGNAME= ;;;
CATEGORIES= ;;;
# Reasons why the port/package shouldn't be built
#
#COMES_WITH= 2.3
#ONLY_FOR_ARCHS= list architectures here
#BROKEN= "reason"
#RESTRICTED= "reason"
#NO_CDROM= "reason"
#NO_PACKAGE= "reason"
# where to send bitches about this port
#
MAINTAINER= ports@openbsd.org
# where the source files and patches can be fetched
#
MASTER_SITES= ;;;
#MASTER_SITE_SUBDIR= ;;;
#DISTFILES= ;;;
#PATCH_SITES= ;;;
#PATCHFILES= ;;;
#PATCH_DIST_STRIP= -p0
# How to extract the sources
#
#EXTRACT_SUFX= .tar.Z
#EXTRACT_CMD= ;;;
#EXTRACT_BEFORE_ARGS= ;;;
#EXTRACT_AFTER_ARGS= ;;;
# Dependencies
#
#FETCH_DEPENDS= ;;;
#BUILD_DEPENDS= ;;;
#RUN_DEPENDS= ;;;
#LIB_DEPENDS= ;;;
# Is the build automagic or is it interactive
#
#IS_INTERACTIVE= yes
# build/configuration variables
#
#USE_GMAKE= yes
#USE_IMAKE= yes
#USE_X11= yes (assumed if USE_IMAKE is yes)
#GNU_CONFIGURE= yes
#HAS_CONFIGURE= yes (assumed if GNU_CONFIGURE is yes)
#CONFIGURE_SCRIPT= ;;; (if other than configure)
#.if (${MACHINE_ARCH} != "alpha")
#CONFIGURE_ARGS+= --enable-shared
#.endif
#CONFIGURE_ARGS+= --enable-static
#CONFIGURE_ENV= ${SETENV}
# Things that we don't want to do for this port/package
#
#NO_DEPENDS= yes
#NO_WRKDIR= yes
#NO_WRKSUBDIR= yes
#NO_CHECKSUM= yes
#NO_EXTRACT= yes
#NO_PATCH= yes
#NO_CONFIGURE= yes
#NO_BUILD= yes
#NO_INSTALL= yes
#NO_MTREE= yes
# This section is only needed if man pages are distributed in compressed
# form. Define MANCOMPRESSED and the man pages by section. The pages
# will be uncompressed after being installed.
#
#MANCOMPRESSED= yes
#MAN1= ;;;
#MAN3= ;;;
#MAN4= ;;;
#MAN5= ;;;
#MAN8= ;;;
# Overrides for default values
#
#MAKEFILE= ;;;
#MAKE_FLAGS= ;;;
#MAKE_ENV= ;;;
#SCRIPTS_ENV= ;;;
#LDFLAGS= ;;;
#WRKDIR= ;;; if other than work
#WRKSRC= ;;; if other than ${WRKDIR}/$DISTNAME
#ALL_TARGET= ;;;
#INSTALL_TARGET= ;;;
# This target may be necessary if a shared library may have been created
#
#post-install:
# ${LDCONFIG} -m ${PREFIX}/lib
.include <bsd.port.mk>
</pre>
<hr>
<a href="porting.html"><img height=24 width=24 src=back.gif
border=0 alt=Porting></a>
<a href=mailto:www@openbsd.org>www@openbsd.org</a>
<br><small>$OpenBSD: checklist.html,v 1.5 1998/09/13 23:05:26 ian Exp $</small>
</body>
</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