1379 lines
53 KiB
Plaintext
1379 lines
53 KiB
Plaintext
<!-- $FreeBSD$ -->
|
|
<!-- The FreeBSD Documentation Project -->
|
|
|
|
<sect1><heading>Porting an existing piece of free software<label id="porting"></heading>
|
|
|
|
<p><em>Contributed by &a.jkh;, &a.gpalmer; and
|
|
&a.asami;.<newline>28 August 1996.</em>
|
|
|
|
<p>The porting of freely available software, while perhaps not as
|
|
gratifying as developing your own from scratch, is still a vital part
|
|
of FreeBSD's growth and of great usefulness to those who would not
|
|
otherwise know where to turn for it. All ported software is organized
|
|
into a carefully organized hierarchy know as ``the ports collection''.
|
|
The collection enables a new user to get a quick and complete overview
|
|
of what is available for FreeBSD in an easy-to-compile form. It also
|
|
saves considerable space by not actually containing the majority
|
|
of the sources being ported, but merely those differences required for
|
|
running under FreeBSD.
|
|
|
|
<p>What follows are some guidelines for creating a new port for
|
|
FreeBSD 2.x. The bulk of the work is done by
|
|
<tt>/usr/share/mk/bsd.port.mk</tt>, which all port Makefiles include.
|
|
Please refer to that file for more details on the inner workings of
|
|
the ports collection.
|
|
|
|
<sect2>
|
|
<heading>Before Starting the Port<label id="porting:starting"></heading>
|
|
|
|
<p>Note: Only a fraction of the overridable variables
|
|
(<tt>${..}</tt>) are mentioned in this document. Most
|
|
(if not all) are documented at the start of
|
|
<tt>bsd.port.mk</tt>. This file uses a non-standard tab
|
|
setting. <tt>Emacs</tt> should recognize the setting on
|
|
loading the file. <tt>vi</tt> or <tt>ex</tt> can be set to
|
|
using the correct value by typing `<tt>:set tabstop=4</tt>'
|
|
once the file has been loaded.
|
|
|
|
<p>You may come across code that needs modifications or
|
|
conditional compilation based upon what version of UNIX it is
|
|
running under. If you need to make such changes to the code
|
|
for conditional compilation, make sure you make the changes as
|
|
general as possible so that we can back-port code to FreeBSD
|
|
1.x systems and cross-port to other BSD systems such as 4.4BSD
|
|
from CSRG, BSD/386, 386BSD and NetBSD.
|
|
|
|
<p>The preferred way to tell 4.3BSD/Reno and newer versions of
|
|
the BSD code apart is by using the `<tt>BSD</tt>' macro
|
|
defined in <tt><sys/param.h></tt>. Hopefully that file
|
|
is already included; if not, add the code:
|
|
|
|
<tscreen><verb>
|
|
#ifdef _HAVE_PARAM_H
|
|
#include <sys/param.h>
|
|
#endif
|
|
</verb></tscreen>
|
|
|
|
to the proper place in the <tt>.c</tt> file and add
|
|
<tt>-D_HAVE_PARAM_H</tt> to the <tt>CFLAGS</tt> in the
|
|
Makefile.
|
|
|
|
Then, you may use:
|
|
|
|
<tscreen><verb>
|
|
#if (defined(BSD) && (BSD >= 199103))
|
|
</verb></tscreen>
|
|
|
|
to detect if the code is being compiled on a 4.3 Net2 code
|
|
base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD,
|
|
BSD/386 1.1 and below).
|
|
|
|
Use:
|
|
|
|
<tscreen><verb>
|
|
#if (defined(BSD) && (BSD >= 199306))
|
|
</verb></tscreen>
|
|
|
|
to detect if the code is being compiled on a 4.4 code base or
|
|
newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or
|
|
above).
|
|
|
|
<p>Use sparingly:
|
|
|
|
<itemize>
|
|
<item><tt>__FreeBSD__</tt> is defined in all versions of
|
|
FreeBSD. Use it if the change you are making ONLY affects
|
|
FreeBSD. Porting gotchas like the use of
|
|
<tt>sys_errlist[]</tt> vs <tt>strerror()</tt> are
|
|
Berkeleyisms, not FreeBSD changes.
|
|
|
|
<item>In FreeBSD 2.x, <tt>__FreeBSD__</tt> is defined to be
|
|
<tt>2</tt>. In earlier versions, it is <tt>1</tt>.
|
|
|
|
<item>If you need to tell the difference between a FreeBSD 1.x
|
|
system and a FreeBSD 2.x system, usually the right answer is
|
|
to use the <tt>BSD</tt> macros described above. If there
|
|
actually is a FreeBSD specific change (such as special
|
|
shared library options when using `<tt>ld</tt>') then it is
|
|
OK to use <tt>__FreeBSD__</tt> and `<tt>#if __FreeBSD__ >
|
|
1</tt>' to detect a FreeBSD 2.x system.
|
|
|
|
If you need more granularity in detecting FreeBSD systems since
|
|
2.0-RELEASE you can use the following:
|
|
|
|
<tscreen><verb>
|
|
#if __FreeBSD__ >= 2
|
|
#include <osreldate.h>
|
|
# if __FreeBSD_version >= 199504
|
|
/* 2.0.5+ release specific code here */
|
|
# endif
|
|
#endif
|
|
</verb></tscreen>
|
|
<tt>__FreeBSD_version</tt> values:
|
|
<tscreen><verb>
|
|
2.0-RELEASE: 199411
|
|
2.1-current's: 199501, 199503
|
|
2.0.5-RELEASE: 199504
|
|
2.2-current before 2.1: 199508
|
|
2.1.0-RELEASE: 199511
|
|
2.2-current before 2.1.5: 199512
|
|
2.1.5-RELEASE: 199607
|
|
2.2-current before 2.1.6: 199608
|
|
2.1.6-RELEASE: 199612
|
|
2.2-RELEASE: 199701
|
|
3.0-current as of Feb 1997: 199702 (will certainly be bumped)
|
|
</verb></tscreen>
|
|
The pattern is the year followed by the month.
|
|
|
|
</itemize>
|
|
|
|
<p>In the hundreds of ports that have been done, there have
|
|
only been one or two cases where <tt>__FreeBSD__</tt>
|
|
should have been used. Just because an earlier port
|
|
screwed up and used it in the wrong place does not mean
|
|
you should do so too.
|
|
|
|
<sect2>
|
|
<heading>Quick Porting</heading>
|
|
|
|
<p>This section tells you how to do a quick port. In many
|
|
cases, it is not enough, but we will see.
|
|
|
|
<p>First, get the original tarball and put it into
|
|
<tt>${DISTDIR}</tt>, which defaults to
|
|
<tt>/usr/ports/distfiles</tt>.
|
|
|
|
<p>Note: The following assumes that the software compiled
|
|
out-of-the-box, i.e., there was absolutely no change required
|
|
for the port to work on your FreeBSD box. If you needed to
|
|
change something, you will have to refer to the next section
|
|
too.
|
|
|
|
<sect3>
|
|
<heading>Writing the Makefile</heading>
|
|
|
|
<p>The minimal <tt>Makefile</tt> would look something like this:
|
|
|
|
<tscreen><verb>
|
|
# New ports collection makefile for: oneko
|
|
# Version required: 1.1b
|
|
# Date created: 5 December 1994
|
|
# Whom: asami
|
|
#
|
|
# $Id$
|
|
#
|
|
|
|
DISTNAME= oneko-1.1b
|
|
CATEGORIES= games
|
|
MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
|
|
|
|
MAINTAINER= asami@FreeBSD.ORG
|
|
|
|
USE_IMAKE= yes
|
|
|
|
.include <bsd.port.mk>
|
|
</verb></tscreen>
|
|
|
|
<p>See if you can figure it out. Do not worry about the contents
|
|
of the <tt>$Id$</tt> line, it will be filled in
|
|
automatically by CVS when the port is imported to our main
|
|
ports tree. You can find a more detailed example in the <ref
|
|
id="porting:samplem" name="sample Makefile"> section.
|
|
|
|
<sect3>
|
|
<heading>Writing the description files</heading>
|
|
|
|
<p>There are three required description files that are
|
|
required for any port, whether they actually package or not.
|
|
They are <tt>COMMENT</tt>, <tt>DESCR</tt>, and
|
|
<tt>PLIST</tt>, and reside in the <tt>pkg</tt> subdirectory.
|
|
|
|
<sect4>
|
|
<heading>COMMENT</heading>
|
|
|
|
<p>This is the one-line description of the port. <em>PLEASE
|
|
do not include the package name (or version number of the
|
|
software) in the comment.</em>
|
|
Here is an example:
|
|
<tscreen><verb>
|
|
A cat chasing a mouse all over the screen.
|
|
</verb></tscreen>
|
|
|
|
<sect4>
|
|
<heading>DESCR</heading>
|
|
|
|
<p>This is a longer description of the port. One to a few
|
|
paragraphs concisely explaining what the port does is
|
|
sufficient. Note: This is <em>not</em> a manual nor an
|
|
in-depth description on how to use or compile the port.
|
|
In particular, please do not just copy the <tt>README</tt>
|
|
file here, unless, of course, it is a concise description
|
|
of the port.
|
|
|
|
<p>It is recommended that you sign the name at the end of
|
|
this file, as in:
|
|
|
|
<tscreen><verb>
|
|
This is a port of oneko, in which a cat chases a poor mouse all over
|
|
the screen.
|
|
:
|
|
(etc.)
|
|
|
|
- Satoshi
|
|
asami@cs.berkeley.edu
|
|
</verb></tscreen>
|
|
|
|
<sect4>
|
|
<heading>PLIST</heading>
|
|
|
|
<p>This file lists all the files installed by the port. It
|
|
is also called the `packing list' because the package is
|
|
generated by packing the files listed here. The pathnames
|
|
are relative to the installation prefix (usually
|
|
<tt>/usr/local</tt> or <tt>/usr/X11R6</tt>).
|
|
|
|
<p>Here is a small example:
|
|
|
|
<tscreen><verb>
|
|
bin/oneko
|
|
man/man1/oneko.1.gz
|
|
lib/X11/app-defaults/Oneko
|
|
lib/X11/oneko/cat1.xpm
|
|
lib/X11/oneko/cat2.xpm
|
|
lib/X11/oneko/mouse.xpm
|
|
</verb></tscreen>
|
|
|
|
<p>Refer to the <tt>pkg_create(1)</tt> man page for details
|
|
on the packing list.
|
|
|
|
<sect3>
|
|
<heading>Creating the checksum file</heading>
|
|
|
|
<p>Just type `<tt>make makesum</tt>'. The ports make rules
|
|
will automatically generate the file <tt>files/md5</tt>.
|
|
|
|
<sect3>
|
|
<heading>Testing the port</heading>
|
|
|
|
<p>You should make sure that the port rules do exactly what
|
|
you want it to do, including packaging up the port. Try
|
|
doing `<tt>make install</tt>', `<tt>make package</tt>' and
|
|
then `<tt>pkg_delete -d <pkgname></tt>' and see if all
|
|
the files are correctly deleted. Then do a `<tt>pkg_add
|
|
<pkgname>.tgz</tt>' and see if everything re-appears
|
|
and works correctly.
|
|
|
|
<sect3>
|
|
<heading>Submitting the port<label id="porting:submitting"></heading>
|
|
|
|
<p>Now that you are happy with your port, the only thing
|
|
remaining is to put it in the main FreeBSD ports tree and
|
|
make everybody else happy about it too. To accomplish this,
|
|
pack the necessary files (everything described in this
|
|
section -- in particular do <em>not</em> include the
|
|
original source tarball, the `<tt>work</tt>' subdirectory or
|
|
the package) into a <tt>.tar.gz</tt> file, stick it in the
|
|
directory
|
|
<tscreen><verb>
|
|
ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/
|
|
</verb></tscreen>
|
|
and send mail to us using <tt>send-pr(1)</tt> (please
|
|
classify it as category `ports' and class `change-request').
|
|
We will take a look, get back to you if necessary, and put
|
|
it in the tree. Your name will also appear in the list of
|
|
`Additional FreeBSD contributors' on the FreeBSD Handbook
|
|
and other files. Isn't that great?!? <tt>:)</tt>
|
|
|
|
<sect2>
|
|
<heading>Slow Porting</heading>
|
|
|
|
<p>Ok, so it was not that simple, and the port required some
|
|
modifications to get it to work. In this section, we will
|
|
explain, step by step, how to modify it to get it to work with
|
|
the ports paradigm.
|
|
|
|
<sect3>
|
|
<heading>How things work</heading>
|
|
|
|
<p>First, this is the sequence of events which occurs when the
|
|
user first types `<tt>make</tt>' in your port's directory,
|
|
and you may find that having <tt>bsd.port.mk</tt> in another
|
|
window while you read this really helps to understand it.
|
|
|
|
<p>But do not worry if you do not really understand what
|
|
<tt>bsd.port.mk</tt> is doing, not many people
|
|
do... <tt>:></tt>
|
|
|
|
<enum>
|
|
<item>The fetch target is run. The fetch target is
|
|
responsible for making sure that the tarball exists
|
|
locally in <tt>${DISTDIR}</tt>. If fetch cannot
|
|
find the required files in <tt>${DISTDIR}</tt> it
|
|
will look up the URL <tt>${MASTER_SITES}</tt>,
|
|
which is set in the Makefile, as well as our main ftp
|
|
site at <htmlurl
|
|
url="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/"
|
|
name="ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/,">
|
|
where we put sanctioned distfiles as backup. It will then
|
|
attempt to
|
|
fetch the named distribution file with
|
|
<tt>${FETCH}</tt>, assuming that the requesting
|
|
site has direct access to the Internet. If that succeeds,
|
|
it will save the file in <tt>${DISTDIR}</tt> for
|
|
future use and proceed.
|
|
|
|
<item>The extract target is run. It looks for your ports'
|
|
distribution file in <tt>${DISTDIR}</tt> (typically
|
|
a gzip'd tarball) and unpacks it into a temporary
|
|
subdirectory specified by <tt>${WRKDIR}</tt>
|
|
(defaults to <tt>work</tt>).
|
|
|
|
<item>The patch target is run. First, any patches defined
|
|
in <tt>${PATCHFILES}</tt> are applied. Second, if
|
|
any patches are found in <tt>${PATCHDIR}</tt>
|
|
(defaults to the <tt>patches</tt> subdirectory), they are
|
|
applied at this time in alphabetical order.
|
|
|
|
<item>The configure target is run. This can do any one of
|
|
many different things.
|
|
|
|
<enum>
|
|
|
|
<item>If it exists, <tt>scripts/configure</tt> is run.
|
|
|
|
<item>If <tt>${HAS_CONFIGURE}</tt> or
|
|
<tt>${GNU_CONFIGURE}</tt> is set,
|
|
<tt>${WRKSRC}/configure</tt> is run.
|
|
|
|
<item>If <tt>${USE_IMAKE}</tt> is set,
|
|
<tt>${XMKMF}</tt> (default: `<tt>xmkmf
|
|
-a</tt>') is run.
|
|
|
|
</enum>
|
|
|
|
<item>The build target is run. This is responsible for
|
|
descending into the ports' private working directory
|
|
(<tt>${WRKSRC}</tt>) and building it. If
|
|
<tt>${USE_GMAKE}</tt> is set, GNU <tt>make</tt>
|
|
will be used, otherwise the system <tt>make</tt> will be
|
|
used.
|
|
|
|
</enum>
|
|
|
|
<p>The above are the default actions. In addition, you can
|
|
define targets `<tt>pre-<something></tt>' or
|
|
`<tt>post-<something></tt>', or put scripts with those
|
|
names, in the <tt>scripts</tt> subdirectory, and they will
|
|
be run before or after the default actions are done.
|
|
|
|
<p>For example, if you have a <tt>post-extract</tt> target
|
|
defined in your Makefile, and a file <tt>pre-build</tt> in
|
|
the <tt>scripts</tt> subdirectory, the
|
|
<tt>post-extract</tt> target will be called after the
|
|
regular extraction actions, and the <tt>pre-build</tt>
|
|
script will be executed before the default build rules are
|
|
done. It is recommended that you use Makefile targets if
|
|
the actions are simple enough, because it will be easier for
|
|
someone to figure out what kind of non-default action the
|
|
port requires.
|
|
|
|
<p>The default actions are done by the <tt>bsd.port.mk</tt>
|
|
targets `<tt>do-<something></tt>'. For example, the
|
|
commands to extract a port are in the target
|
|
`<tt>do-extract</tt>'. If you are not happy with the
|
|
default target, you can fix it by redefining the
|
|
`<tt>do-<something></tt>' target in your Makefile.
|
|
|
|
<p>Note that the `main' targets (e.g., <tt>extract</tt>,
|
|
<tt>configure</tt>, etc.) do nothing more than make sure all
|
|
the stages up to that one is completed and call the real
|
|
targets or scripts, and they are not intended to be
|
|
changed. If you want to fix the extraction, fix
|
|
<tt>do-extract</tt>, but never ever touch <tt>extract</tt>!
|
|
|
|
<p>Now that you understand what goes on when the user types
|
|
`<tt>make</tt>', let us go through the recommended steps to
|
|
create the perfect port.
|
|
|
|
<sect3>
|
|
<heading>Getting the original sources</heading>
|
|
|
|
<p>Get the original sources (normally) as a compressed tarball
|
|
(<tt><foo>.tar.gz</tt> or <tt><foo>.tar.Z</tt>)
|
|
and copy it into <tt>${DISTDIR}</tt>. Always use
|
|
<em>mainstream</em> sources when and where you can.
|
|
|
|
<p>If you cannot find a ftp/http site that is well-connected
|
|
to the net, or can only find sites that have irritatingly
|
|
non-standard formats, we can `house' it ourselves by putting
|
|
it on
|
|
<tscreen><verb>
|
|
ftp://freefall.FreeBSD.ORG/pub/FreeBSD/LOCAL_PORTS/
|
|
</verb></tscreen>
|
|
as the last resort. Send mail to the &a.ports
|
|
if you are not sure what to do.
|
|
|
|
<p>If your port requires some additional `patches' that are
|
|
available on the Internet, fetch them too and put them in
|
|
<tt>${DISTDIR}</tt>. Do not worry if they come from
|
|
site other than where you got the main source tarball,
|
|
we have a way to handle these situations (see the
|
|
description of <ref id="porting:patchfiles"
|
|
name="${PATCHFILES}"> below).
|
|
|
|
<sect3>
|
|
<heading>Modifying the port</heading>
|
|
|
|
<p>Unpack a copy of the tarball in a private directory and
|
|
make whatever changes are necessary to get the port to
|
|
compile properly under the current version of FreeBSD. Keep
|
|
<em>careful track</em> of everything you do, as you will be
|
|
automating the process shortly. Everything, including the
|
|
deletion, addition or modification of files should be doable
|
|
using an automated script or patch file when your port is
|
|
finished.
|
|
|
|
<p>If your port requires significant user
|
|
interaction/customization to compile or install, you should
|
|
take a look at one of Larry Wall's classic Configure scripts
|
|
and perhaps do something similar yourself. The goal of the
|
|
new ports collection is to make each port as `plug-and-play'
|
|
as possible for the end-user while using a minimum of disk
|
|
space.
|
|
|
|
<p>Note: Unless explicitly stated, patch files, scripts, and
|
|
other files you have created and contributed to the FreeBSD
|
|
ports collection are assumed to be covered by the standard
|
|
BSD copyright conditions.
|
|
|
|
<sect3>
|
|
<heading>Patching</heading>
|
|
|
|
<p>In the preparation of the port, files that have been added
|
|
or changed can be picked up with a recursive diff for later
|
|
feeding to patch. Each set of patches you wish to apply
|
|
should be collected into a file named
|
|
`<tt>patch-<xx></tt>' where <tt><xx></tt>
|
|
denotes the sequence in which the patches will be applied --
|
|
these are done in <em>alphabetical order</em>, thus
|
|
`<tt>aa</tt>' first, `<tt>ab</tt>' second and so on. These
|
|
files should be stored in <tt>${PATCHDIR}</tt>, from
|
|
where they will be automatically applied. All patches
|
|
should be relative to <tt>${WRKSRC}</tt> (generally
|
|
the directory your port's tarball unpacks itself into, that
|
|
being where the make is done). To make fixes and upgrades
|
|
easier you should avoid having more than one patch fix the
|
|
same file (e.g., patch-aa and patch-ab both changing
|
|
<tt>${WRKSRC}</tt>/foobar.c).
|
|
|
|
<sect3>
|
|
<heading>Configuring</heading>
|
|
|
|
<p>Include any additional customization commands to your
|
|
<tt>configure</tt> script and save it in the
|
|
`<tt>scripts</tt>' subdirectory. As mentioned above, you
|
|
can also do this as Makefile targets and/or scripts with the
|
|
name <tt>pre-configure</tt> or <tt>post-configure</tt>.
|
|
|
|
<sect3>
|
|
<heading>Handling user input</heading>
|
|
|
|
<p>If your port requires user input to build, configure or
|
|
install, then set <tt>IS_INTERACTIVE</tt> in your Makefile.
|
|
This will allow `overnight builds' to skip your port if the
|
|
user sets the variable <tt>BATCH</tt> in his environment
|
|
(and if the user sets the variable <tt>INTERACTIVE</tt>,
|
|
then <em>only</em> those ports requiring interaction are
|
|
built).
|
|
|
|
<sect2>
|
|
<heading>Configuring the Makefile</heading>
|
|
|
|
<p>Configuring the Makefile is pretty simple, and again we
|
|
suggest that you look at existing examples before starting.
|
|
Also, there is a <ref id="porting:samplem" name="sample
|
|
Makefile"> in this handbook, so take a look and please follow
|
|
the ordering of variables and sections in that template to
|
|
make your port easier for others to read.
|
|
|
|
<p>Now, consider the following problems in sequence as you
|
|
design your new Makefile:
|
|
|
|
<sect3>
|
|
<heading>The original source</heading>
|
|
|
|
<p>Does it live in <tt>${DISTDIR}</tt> as a standard
|
|
gzip'd tarball? If so, you can go on to the next step. If
|
|
not, you should look at overriding any of the
|
|
<tt>${EXTRACT_CMD}</tt>,
|
|
<tt>${EXTRACT_BEFORE_ARGS}</tt>,
|
|
<tt>${EXTRACT_AFTER_ARGS}</tt>,
|
|
<tt>${EXTRACT_SUFX}</tt>, or
|
|
<tt>${DISTFILES}</tt> variables, depending on how
|
|
alien a format your port's distribution file is. (The most
|
|
common case is `<tt>EXTRACT_SUFX=.tar.Z</tt>', when the
|
|
tarball is condensed by regular compress, not gzip.)
|
|
|
|
<p>In the worst case, you can simply create your own
|
|
`<tt>do-extract</tt>' target to override the default, though
|
|
this should be rarely, if ever, necessary.
|
|
|
|
<sect3>
|
|
<heading>DISTNAME</heading>
|
|
|
|
<p>You should set <tt>${DISTNAME}</tt> to be the base
|
|
name of your port. The default rules expect the
|
|
distribution file list (<tt>${DISTFILES}</tt>) to be
|
|
named
|
|
<tt>${DISTNAME}${EXTRACT_SUFX}</tt>
|
|
by default which, if it is a normal tarball, is going to be
|
|
something like:
|
|
<tscreen><verb>
|
|
foozolix-1.0.tar.gz
|
|
</verb></tscreen>
|
|
for a setting of `<tt>DISTNAME=foozolix-1.0</tt>'.
|
|
|
|
The default rules also expect the tarball(s) to extract into
|
|
a subdirectory called <tt>work/${DISTNAME}</tt>, e.g.
|
|
<tscreen><verb>
|
|
work/foozolix-1.0/
|
|
</verb></tscreen>
|
|
|
|
All this behavior can be overridden, of course, it simply
|
|
represents the most common time-saving defaults. For a port
|
|
requiring multiple distribution files, simply set
|
|
<tt>${DISTFILES}</tt> explicitly. If only a subset
|
|
of <tt>${DISTFILES}</tt> are actual extractable
|
|
archives, then set them up in
|
|
<tt>${EXTRACT_ONLY}</tt>, which will override the
|
|
<tt>${DISTFILES}</tt> list when it comes to
|
|
extraction, and the rest will be just left in
|
|
<tt>${DISTDIR}</tt> for later use.
|
|
|
|
<sect3>
|
|
<heading>CATEGORIES</heading>
|
|
|
|
<p>When a package is created, it is put under
|
|
<tt>/usr/ports/packages/All</tt> and links are made from one
|
|
or more subdirectories of <tt>/usr/ports/packages</tt>. The
|
|
names of these subdirectories are specified by the variable
|
|
<tt>${CATEGORIES}</tt>. It is intended to make life
|
|
easier for the user when he is wading through the pile of
|
|
packages on the ftp site or the CD-ROM. Please take a look
|
|
at the existing categories (you can find them in <htmlurl
|
|
url="http://www.freebsd.org/ports/" name="the ports
|
|
page">) and pick the ones that are suitable for your port.
|
|
If your port truly belongs to something that is different
|
|
from all the existing ones, you can even create a new
|
|
category name.
|
|
|
|
<sect3>
|
|
<heading>MASTER_SITES</heading>
|
|
|
|
<p>Record the directory part of the ftp/http-URL pointing at
|
|
the original tarball in <tt>${MASTER_SITES}</tt>.
|
|
Do not forget the trailing slash (<tt>/</tt>)!
|
|
|
|
<p>The make macros will try to use this specification for
|
|
grabbing the distribution file with <tt>${FETCH}</tt>
|
|
if they cannot find it already on the system.
|
|
|
|
<p>It is recommended that you put multiple sites on this list,
|
|
preferably from different continents. This will safeguard
|
|
against wide-area network problems, and we are even planning
|
|
to add support for automatically determining the closest
|
|
master site and fetching from there!
|
|
|
|
<p>If the original tarball is part of one of the following
|
|
popular archives: X-contrib, GNU, Perl CPAN, TeX CTAN, or
|
|
Linux Sunsite, you refer to those sites in an easy compact
|
|
form using MASTER_SITE_XCONTRIB, MASTER_SITE_GNU,
|
|
MASTER_SITE_PERL_CPAN, MASTER_SITE_TEX_CTAN, and
|
|
MASTER_SITE_SUNSITE. Simply set MASTER_SITE_SUBDIR to the path
|
|
with in the archive. Here is an example:
|
|
<tscreen><verb>
|
|
MASTER_SITES= ${MASTER_SITE_XCONTRIB}
|
|
MASTER_SITE_SUBDIR= applications
|
|
</verb></tscreen>
|
|
<p>The user can also set the MASTER_SITE_* variables in
|
|
<tt>/etc/make.conf</tt> to override our choices, and use their
|
|
favorate mirrors of these popular archives instead.
|
|
|
|
<sect3>
|
|
<heading>PATCHFILES<label id="porting:patchfiles"></heading>
|
|
|
|
<p>If your port requires some additional patches that are
|
|
available by ftp or http, set <tt>${PATCHFILES}</tt>
|
|
to the names of the files and <tt>${PATCH_SITES}</tt>
|
|
to the URL of the directory that contains them (the format
|
|
is the same as <tt>${MASTER_SITES}</tt>).
|
|
|
|
<p>If the patch is not relative to the top of the source tree
|
|
(i.e., <tt>${WKRSRC}</tt>) because it contains some
|
|
extra pathnames, set <tt>${PATCH_DIST_STRIP}</tt>
|
|
accordingly. For instance, if all the pathnames in the
|
|
patch has an extra `<tt>foozolix-1.0/</tt>' in front of the
|
|
filenames, then set `<tt>PATCH_DIST_STRIP=-p1</tt>'.
|
|
|
|
<p>Do not worry if the patches are compressed, they will be
|
|
decompressed automatically if the filenames end with
|
|
`<tt>.gz</tt>' or `<tt>.Z</tt>'.
|
|
|
|
<p>If the patch is distributed with some other files, such as
|
|
documentation, in a gzip'd tarball, you can't just use
|
|
<tt>${PATCHFILES}</tt>. If that is the case, add the
|
|
name and the location of the patch tarball to
|
|
<tt>${DISTFILES}</tt> and
|
|
<tt>${MASTER_SITES}</tt>. Then, from the
|
|
<tt>pre-patch</tt> target, apply the patch either by running
|
|
the patch command from there, or copying the patch file into
|
|
the <tt>${PATCHDIR}</tt> directory and calling it
|
|
<tt>patch-<xx></tt>. (Note the tarball will have been
|
|
extracted alongside the regular source by then, so there is
|
|
no need to explicitly extract it if it is a regular gzip'd
|
|
or compress'd tarball.) If you do the latter, take extra
|
|
care not to overwrite something that already exists in that
|
|
directory. Also do not forget to add a command to remove
|
|
the copied patch in the <tt>pre-clean</tt> target.
|
|
|
|
<sect3>
|
|
<heading>MAINTAINER</heading>
|
|
|
|
<p>Set your mail-address here. Please. <tt>:)</tt>
|
|
|
|
<p>For detailed description of the responsibility of maintainers,
|
|
refer to <ref id="policies:maintainer"
|
|
name="MAINTAINER on Makefiles"> section.
|
|
|
|
<sect3>
|
|
<heading>Dependencies</heading>
|
|
|
|
<p>Many ports depend on other ports. There are five
|
|
variables that you can use to ensure that all the required
|
|
bits will be on the user's machine.
|
|
|
|
<sect4>
|
|
<heading>LIB_DEPENDS</heading>
|
|
|
|
<p>This variable specifies the shared libraries this port
|
|
depends on. It is a list of `<tt>lib:dir</tt>' pairs
|
|
where <tt>lib</tt> is the name of the shared library, and
|
|
<tt>dir</tt> is the directory in which to find it in case
|
|
it is not available. For example,
|
|
<tscreen><verb>
|
|
LIB_DEPENDS= jpeg\\.6\\.:${PORTSDIR}/graphics/jpeg
|
|
</verb></tscreen>
|
|
will check for a shared jpeg library with major version 6,
|
|
and descend into the <tt>graphics/jpeg</tt> subdirectory
|
|
of your ports tree to build and install it if it is not
|
|
found.
|
|
|
|
Note that the <tt>lib</tt> part is just an argument given
|
|
to `<tt>ldconfig -r | grep</tt>', so periods should be
|
|
escaped by two backslashes like in the example above.
|
|
|
|
The dependency is checked from within the <tt>extract</tt>
|
|
target. Also, the name of the dependency is put in to the
|
|
package so that <tt>pkg_add</tt> will automatically
|
|
install it if it is not on the user's system.
|
|
|
|
<sect4>
|
|
<heading>RUN_DEPENDS</heading>
|
|
|
|
<p>This variable specifies executables or files this port
|
|
depends on during run-time. It is a list of
|
|
`<tt>path:dir</tt>' pairs where <tt>path</tt> is the name
|
|
of the executable or file, and <tt>dir</tt> is the
|
|
directory in which to find it in case it is not
|
|
available. If <tt>path</tt> starts with a slash
|
|
(<tt>/</tt>), it is treated as a file and its existence is
|
|
tested with `<tt>test -e</tt>'; otherwise, it is assumed
|
|
to be an executable, and `<tt>which -s</tt>' is used to
|
|
determine if the program exists in the user's search path.
|
|
|
|
<p>For example,
|
|
<tscreen><verb>
|
|
RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \
|
|
wish:${PORTSDIR}/x11/tk
|
|
</verb></tscreen>
|
|
will check if the file `<tt>/usr/local/etc/innd</tt>'
|
|
exists, and build and install it from the
|
|
<tt>news/inn</tt> subdirectory of the ports tree if it is
|
|
not found. It will also see if an executable called
|
|
`<tt>wish</tt>' is in your search path, and descend into
|
|
the <tt>x11/tk</tt> subdirectory of your ports tree to
|
|
build and install it if it is not found. (Note that in
|
|
this case, `<tt>innd</tt>' is actually an executable; if
|
|
an executable is in a place that is not expected to be in
|
|
a normal user's search path, you should use the full
|
|
pathname.)
|
|
|
|
The dependency is checked from within the <tt>install</tt>
|
|
target. Also, the name of the dependency is put in to the
|
|
package so that <tt>pkg_add</tt> will automatically
|
|
install it if it is not on the user's system.
|
|
|
|
<sect4>
|
|
<heading>BUILD_DEPENDS</heading>
|
|
|
|
<p>This variable specifies executables or files this port
|
|
requires to build. Like <tt>RUN_DEPENDS</tt>, it is a
|
|
list of `<tt>path:dir</tt>' pairs. For example,
|
|
<tscreen><verb>
|
|
BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip
|
|
</verb></tscreen>
|
|
will check for an executable called `<tt>unzip</tt>', and
|
|
descend into the <tt>archivers/unzip</tt> subdirectory of
|
|
your ports tree to build and install it if it is not found.
|
|
|
|
Note that `build' here means everything from extracting to
|
|
compilation. The dependency is checked from within the
|
|
<tt>extract</tt> target.
|
|
|
|
<sect4>
|
|
<heading>FETCH_DEPENDS</heading>
|
|
|
|
<p>This variable specifies executables or files this port
|
|
requires to fetch. Like the previous two, it is a list of
|
|
`<tt>path:dir</tt>' pairs. For example,
|
|
<tscreen><verb>
|
|
FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2
|
|
</verb></tscreen>
|
|
will check for an executable called `<tt>ncftp2</tt>', and
|
|
descend into the <tt>net/ncftp2</tt> subdirectory of
|
|
your ports tree to build and install it if it is not found.
|
|
|
|
The dependency is checked from within the <tt>fetch</tt>
|
|
target.
|
|
|
|
<sect4>
|
|
<heading>DEPENDS</heading>
|
|
|
|
<p>If there is a dependency that does not fall into either of
|
|
the above four categories, or your port requires to have
|
|
the source of the other port extracted (i.e., having them
|
|
installed is not enough), then use this variable. This is
|
|
just a list of directories, as there is nothing to check,
|
|
unlike the previous four.
|
|
|
|
<sect3>
|
|
<heading>Building mechanisms</heading>
|
|
|
|
<p>If your package uses GNU <tt>make</tt>, set
|
|
`<tt>USE_GMAKE=yes</tt>'. If your package uses GNU
|
|
<tt>configure</tt>, set `<tt>GNU_CONFIGURE=yes</tt>'. If
|
|
you want to give some extra arguments to GNU
|
|
<tt>configure</tt> (other than the default
|
|
`<tt>--prefix=${PREFIX}</tt>'),
|
|
set those extra arguments in
|
|
<tt>${CONFIGURE_ARGS}</tt>.
|
|
|
|
<p>If your package is an X application that creates Makefiles
|
|
from Imakefiles using <tt>imake</tt>, then set
|
|
`<tt>USE_IMAKE=yes</tt>'. This will cause the configure
|
|
stage to automatically do an <tt>xmkmf -a</tt>. If the
|
|
`<tt>-a</tt>' flag is a problem for your port, set
|
|
`<tt>XMKMF=xmkmf</tt>'.
|
|
|
|
<p>If your port's source Makefile has something else than
|
|
`<tt>all</tt>' as the main build target, set
|
|
<tt>${ALL_TARGET}</tt> accordingly. Same goes for
|
|
`<tt>install</tt>' and <tt>${INSTALL_TARGET}</tt>.
|
|
|
|
<sect3>
|
|
<heading>NO_INSTALL_MANPAGES</heading>
|
|
|
|
<p>If the port uses imake but does not understand the
|
|
`<tt>install.man</tt>' target,
|
|
`<tt>NO_INSTALL_MANPAGES=yes</tt>' should be set. In
|
|
addition, the author of the original port should be
|
|
shot. <tt>:></tt>
|
|
|
|
<sect2>
|
|
<heading>Ports that require Motif</heading>
|
|
|
|
<p>There are many programs that require a Motif library
|
|
(available from several commercial vendors, while there is (at
|
|
least) one effort to create a free clone) to compile. Since
|
|
it is a popular toolkit and their licenses usually permit
|
|
redistribution of statically linked binaries, we have made
|
|
special provisions for handling ports that require Motif in a
|
|
way that we can easily compile binaries linked either
|
|
dynamically or statically.
|
|
|
|
<sect3>
|
|
<heading>REQUIRES_MOTIF</heading>
|
|
|
|
<p>If your port requires Motif, define this variable in the
|
|
Makefile. This will prevent people who don't own a copy of
|
|
Motif from even attempting to build it.
|
|
|
|
<sect3>
|
|
<heading>${MOTIFLIB}</heading>
|
|
|
|
<p>This variable will be set by <tt>bsd.port.mk</tt> to be the
|
|
appropriate reference to the Motif library. Please patch
|
|
the source to use this wherever the Motif library is
|
|
referenced in the Makefile or Imakefile.
|
|
|
|
<p>There are two common cases:
|
|
<enum>
|
|
<item>If the port refers to the Motif library as
|
|
`<tt>-lXm</tt>' in its Makefile or Imakefile, simply
|
|
substitute `<tt>${MOTIFLIB}</tt>' for it.
|
|
|
|
<item>If the port uses `<tt>XmClientLibs</tt>' in its
|
|
Imakefile, change it to `<tt>${MOTIFLIB}
|
|
${XTOOLLIB} ${XLIB}</tt>'.
|
|
</enum>
|
|
|
|
<p>Note that <tt>${MOTIFLIB}</tt> (usually) expands to
|
|
`<tt>-L/usr/X11R6/lib -lXm</tt>' or
|
|
`<tt>/usr/X11R6/lib/libXm.a</tt>', so there is no need to
|
|
add `<tt>-L</tt>' or `<tt>-l</tt>' in front.
|
|
|
|
<sect2>
|
|
<heading>Licensing Problems</heading>
|
|
|
|
<p>Some software packages have restrictive licenses or are in
|
|
violation to the law (PKP's patent on public key crypto,
|
|
ITAR (export of crypto software) to name just two of them).
|
|
What we can do with them vary a lot, depending on the exact
|
|
wordings of the respective licenses.
|
|
|
|
<p>Note that it is your responsibility as a porter to read the
|
|
licensing terms of the software and make sure that the FreeBSD
|
|
project will not be held accountable of violating them by
|
|
redistributing the source or compiled binaries either via ftp
|
|
or CD-ROM. If in doubt, please contact the &a.ports;.
|
|
|
|
<p>There are two variables you can set in the Makefile to handle
|
|
the situations that arise frequently:
|
|
|
|
<enum>
|
|
<item>If the port has a `do not sell for profit' type of
|
|
license, set the variable <tt>NO_CDROM</tt>. We will make
|
|
sure such ports won't go into the CD-ROM come release time.
|
|
The distfile and package will still be available via ftp.
|
|
|
|
<item>If the resulting package needs to be built uniquely for
|
|
each site, or the resulting binary package can't be distributed
|
|
due to licensing; set the variable <tt>NO_PACKAGE</tt>.
|
|
We will make sure such packages won't go on the ftp site, nor
|
|
into the CD-ROM come release time. The distfile will still be
|
|
included on both however.
|
|
|
|
<item>If the port has legal restrictions on who can use it
|
|
(e.g., crypto stuff) or has a `no commercial use' license,
|
|
set the variable <tt>RESTRICTED</tt> to be the string
|
|
describing the reason why. For such ports, the
|
|
distfiles/packages will not be available even from our ftp
|
|
sites.
|
|
</enum>
|
|
|
|
<p>Note: The GNU General Public License (GPL), both version 1
|
|
and 2, should not be a problem for ports.
|
|
|
|
<p>Note: If you are a committer, make sure you update the
|
|
<tt>ports/LEGAL</tt> file too.
|
|
|
|
<sect2>
|
|
<heading>Upgrading</heading>
|
|
|
|
<p>When you notice that a port is out of date compared to the
|
|
latest version from the original authors, first make sure you
|
|
have the latest port. You can find them in the
|
|
<tt>ports-current</tt> directory of the ftp mirror sites.
|
|
|
|
<p>The next step is to send a mail to the maintainer, if one is
|
|
listed in the port's Makefile. That person may already be
|
|
working on an upgrade, or have a reason to not upgrade the
|
|
port right now (because of, for example, stability problems
|
|
of the new version).
|
|
|
|
<p>If the maintainer asks you to do the upgrade or there isn't
|
|
any such person to begin with, please make the upgrade and
|
|
send the recursive diff of the new and old ports directories
|
|
to us (i.e., if your modified ports directory is called
|
|
`<tt>superedit</tt>' and the original as in our tree is
|
|
`<tt>superedit.bak</tt>', then send us the result of `<tt>diff
|
|
-ru superedit.bak superedit</tt>'.) If the port has changed
|
|
so much that the diff is larger than the new port itself, you
|
|
can <ref id="porting:submitting" name="upload"> the port
|
|
following the procedure described above. Either way, don't
|
|
forget to send us a message using <tt>send-pr(1)</tt>!
|
|
|
|
<sect2>
|
|
<heading>Do's and Dont's</heading>
|
|
|
|
<p>Here is a list of common do's and dont's that you encounter
|
|
during the porting process.
|
|
|
|
<sect3>
|
|
<heading>WRKDIR</heading>
|
|
|
|
<p>Do not leave anything valuable lying around in the
|
|
<tt>work</tt> subdirectory, `<tt>make clean</tt>' will
|
|
<em>nuke</em> it completely! If you need auxiliary files
|
|
that are not scripts or patches, put them in the subdirectory
|
|
<tt>files</tt> and use the <tt>post-extract</tt> target to
|
|
copy them to the <tt>work</tt> subdirectory.
|
|
|
|
<sect3>
|
|
<heading>Package information</heading>
|
|
|
|
<p>Do install package information, i.e., the three files in
|
|
<tt>pkg</tt>. Note that these files are not used only for
|
|
packaging anymore, and are <em>mandatory</em> now, even if
|
|
<tt>${NO_PACKAGE}</tt> is set.
|
|
|
|
<sect3>
|
|
<heading>Compress manpages, strip binaries</heading>
|
|
|
|
<p>Do compress manpages and strip binaries. If the original
|
|
source already strips the binary, fine; otherwise, you can add a
|
|
<tt>post-install</tt> rule to do it yourself. Here is an example:
|
|
<tscreen><verb>
|
|
post-install:
|
|
strip ${PREFIX}/bin/xdl
|
|
</verb></tscreen>
|
|
<p>Use the <tt>file</tt> command on the installed executable
|
|
to check whether the binary is stripped or not. If it
|
|
does not say `not stripped', it is stripped.
|
|
|
|
<p>To automagically compress the manpages, use the MAN[1-9LN]
|
|
variables. They will check the variable
|
|
<tt>NOMANCOMPRESS</tt> that the user can set in
|
|
<tt>/etc/make.conf</tt> to disable man page compression.
|
|
Place them last in the section below the
|
|
<tt>MAINTAINER</tt> variable. Here is an example:
|
|
<tscreen><verb>
|
|
MAN1= foo.1 bar.1
|
|
MAN5= foo.conf.5
|
|
MAN8= baz.8
|
|
</verb></tscreen>
|
|
<p>Note that this is not usually necessary with ports that are X
|
|
applications and use Imake to build.
|
|
|
|
<p>If your port anchors its man tree somewhere other than
|
|
<tt>PREFIX</tt>, you can use the <tt>MANPREFIX</tt> to set it.
|
|
Also, if only manpages in certain section go in a
|
|
non-standard place, such as many Perl modules ports, you
|
|
can set individual man paths using
|
|
<tt>MAN<em>sect</em>PREFIX</tt> (where <em>sect</em> is one
|
|
of 1-9, L or N).
|
|
|
|
<sect3>
|
|
<heading>INSTALL_* macros</heading>
|
|
<p>Do use the macros provided in <tt>bsd.port.mk</tt> to
|
|
ensure correct modes and ownership of files in your own
|
|
*-install targets. They are:
|
|
|
|
<itemize>
|
|
<item><tt>${INSTALL_PROGRAM}</tt> is a command to install
|
|
binary executables.
|
|
<item><tt>${INSTALL_SCRIPT}</tt> is a command to install
|
|
executable scripts.
|
|
<item><tt>${INSTALL_DATA}</tt> is a command to install
|
|
sharable data.
|
|
<item><tt>${INSTALL_MAN}</tt> is a command to install
|
|
manpages (it doesn't do compression).
|
|
</itemize>
|
|
|
|
<p>These are basically the <tt>install</tt> command with all
|
|
the appropriate flags. See below for an example on how to
|
|
use them.
|
|
|
|
<sect3>
|
|
<heading>INSTALL package script</heading>
|
|
<p>If your port needs execute commands when the binary package
|
|
is installed with pkg_add you can do with via the pkg/INSTALL
|
|
script. This script will automatically be added to the
|
|
package, and will be run twice by pkg_add. The first time
|
|
will as `<tt>INSTALL ${PKGNAME} PRE-INSTALL</tt>'
|
|
and the second time as `<tt>INSTALL ${PKGNAME} POST-INSTALL</tt>'.
|
|
`<tt>$2</tt>' can be tested to determine which mode
|
|
the script is being run in.
|
|
The `<tt>PKG_PREFIX</tt>' environmental variable will be set to
|
|
the package installation directory. See man <tt>pkg_add(1)</tt>
|
|
for additional information.
|
|
Note, that this script is not run automatically if you install
|
|
the port with `<tt>make install</tt>'. If you are depending
|
|
on it being run, you will have to explicitly call it on your
|
|
port's Makefile.
|
|
|
|
<sect3>
|
|
<heading>REQ package script</heading>
|
|
<p>If your needs to determine if it should install or not, you
|
|
can create a pkg/REQ ``requirements'' script. It will be invoked
|
|
automatically at installation/deinstallation time to determine
|
|
whether or not installation/deinstallation should proceed.
|
|
See man <tt>pkg_create(1)</tt> and man <tt>pkg_add(1)</tt> for
|
|
more information.
|
|
|
|
<sect3>
|
|
<heading>Install additional documentation</heading>
|
|
|
|
<p>If your software has some documentation other than the
|
|
standard man and info pages that you think is useful for the
|
|
user, install it under <tt>${PREFIX}/share/doc</tt>.
|
|
This can be done, like the previous item, in the
|
|
<tt>post-install</tt> target.
|
|
|
|
<p>Create a new directory for your port. The directory name
|
|
should reflect what the port is. This usually means
|
|
<tt>${PKGNAME}</tt> minus the version part. However,
|
|
if you think the user might want different versions of the
|
|
port to be installed at the same time, you
|
|
can use the whole <tt>${PKGNAME}</tt>.
|
|
|
|
<p>Make the installation dependent to the variable
|
|
<tt>NOPORTDOCS</tt> so that users can disable it in
|
|
<tt>/etc/make.conf</tt>, like this:
|
|
<tscreen><verb>
|
|
post-install:
|
|
.if !defined(NOPORTDOCS)
|
|
${MKDIR} ${PREFIX}/share/doc/xv
|
|
${INSTALL_DATA} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv
|
|
.endif
|
|
</verb></tscreen>
|
|
|
|
<p>Do not forget to add them to <tt>pkg/PLIST</tt> too! (Do not
|
|
worry about <tt>NOPORTDOCS</tt> here; there is currently no
|
|
way for the packages to read variables from
|
|
<tt>/etc/make.conf</tt>.)
|
|
|
|
<p>If you need to display a message to the installer, you may
|
|
place the message in <tt>pkg/MESSAGE</tt>. This capibility
|
|
is often useful to display additional installation steps to
|
|
be taken after a pkg_add, or to display licensing information.
|
|
(note: the MESSAGE file does not need to be added to pkg/PLIST).
|
|
|
|
|
|
<sect3>
|
|
<heading>DIST_SUBDIR</heading>
|
|
|
|
<p>Do not let your port clutter <tt>/usr/ports/distfiles</tt>. If
|
|
your port requires a lot of files to be
|
|
fetched, or contains a file that has a name that might conflict
|
|
with other ports (e.g., `Makefile'), set
|
|
<tt>${DIST_SUBDIR}</tt> to the name of the port
|
|
(<tt>${PKGNAME}</tt> without the version part should work
|
|
fine). This will change <tt>${DISTDIR}</tt> from the
|
|
default <tt>/usr/ports/distfiles</tt> to
|
|
<tt>/usr/ports/distfiles/${DIST_SUBDIR}</tt>, and in
|
|
effect puts everything that is required for your port into that
|
|
subdirectory.
|
|
|
|
<p>It will also look at the subdirectory with the same name on the
|
|
backup master site at <tt>ftp.freebsd.org</tt>. (Setting
|
|
<tt>${DISTDIR}</tt> explicitly in your Makefile will not
|
|
accomplish this, so please use <tt>${DIST_SUBDIR}</tt>.)
|
|
|
|
<p>Note this does not affect the <tt>${MASTER_SITES}</tt>
|
|
you define in your Makefile.
|
|
|
|
<sect3>
|
|
<heading>Feedback</heading>
|
|
|
|
<p>Do send applicable changes/patches to the original
|
|
author/maintainer for inclusion in next release of the code.
|
|
This will only make your job that much easier for the next
|
|
release.
|
|
|
|
<sect3>
|
|
<heading>RCS strings</heading>
|
|
|
|
<p>Do not put RCS strings in patches. CVS will mangle them
|
|
when we put the files into the ports tree, and when we check
|
|
them out again, they will come out different and the patch
|
|
will fail. RCS strings are surrounded by dollar
|
|
(`<tt>$</tt>') signs, and typically start with
|
|
`<tt>$Id</tt>' or `<tt>$RCS</tt>'.
|
|
|
|
<sect3>
|
|
<heading>Recursive diff</heading>
|
|
|
|
<p>Using the recurse (`<tt>-r</tt>') option to <tt>diff</tt>
|
|
to generate patches is fine, but please take a look at the
|
|
resulting patches to make sure you don't have any
|
|
unnecessary junk in there. In particular, diffs between two
|
|
backup files, Makefiles when the port uses imake or GNU
|
|
configure, etc., are unnecessary and should be deleted.
|
|
Also, if you had to delete a file, then you can do it in the
|
|
<tt>post-extract</tt> target rather than as part of the
|
|
patch.
|
|
|
|
<sect3>
|
|
<heading>PREFIX</heading>
|
|
|
|
<p>Do try to make your port install relative to
|
|
<tt>${PREFIX}</tt>. (The value of this variable will be
|
|
set to <tt>${LOCALBASE}</tt> (default
|
|
<tt>/usr/local</tt>), unless <tt>${USE_IMAKE}</tt> or
|
|
<tt>${USE_X11}</tt> is set, in which case it will be
|
|
<tt>${X11BASE}</tt> (default <tt>/usr/X11R6</tt>).)
|
|
|
|
<p>Not hard-coding `<tt>/usr/local</tt>' or `<tt>/usr/X11R6</tt>'
|
|
anywhere in the source will make the port much more flexible and
|
|
able to cater to the needs of other sites. For X ports that use
|
|
imake, this is automatic; otherwise, this can often be done by
|
|
simply replacing the occurrences of `<tt>/usr/local</tt>' (or
|
|
`<tt>/usr/X11R6</tt>' for X ports that do not use imake) in the
|
|
various scripts/Makefiles in the port to read
|
|
`<tt>${PREFIX}</tt>', as this variable is automatically
|
|
passed down to every stage of the build and install processes.
|
|
|
|
<p>The variable <tt>${PREFIX}</tt> can be reassigned in your
|
|
Makefile or in the user's environment. However, it is strongly
|
|
discouraged for individual ports to set this variable explicitly
|
|
in the Makefiles. (If your port is an X port but does not use
|
|
imake, set <tt>USE_X11=yes</tt>; this is quite different from
|
|
setting <tt>PREFIX=/usr/X11R6</tt>.)
|
|
|
|
<p>Also, refer to programs/files from other ports with the
|
|
variables mentioned above, not explicit pathnames. For instance,
|
|
if your port requires a macro <tt>PAGER</tt> to be the full
|
|
pathname of <tt>less</tt>, use the compiler flag:
|
|
<verb>-DPAGER=\"${PREFIX}/bin/less\"</verb> or
|
|
<verb>-DPAGER=\"${LOCALBASE}/bin/less\"</verb> if this is an
|
|
X port, instead of <verb>-DPAGER=\"/usr/local/bin/less\"</verb>.
|
|
This way it will have a better chance of working if the system
|
|
administrator has moved the whole `/usr/local' tree somewhere
|
|
else.
|
|
|
|
<sect3>
|
|
<heading>Subdirectories</heading>
|
|
|
|
<p>Try to let the port put things in the right subdirectories
|
|
of <tt>${PREFIX}</tt>. Some ports lump everything
|
|
and put it in the subdirectory with the port's name, which is
|
|
incorrect. Also, many ports put everything except binaries,
|
|
header files and manual pages in the a subdirectory of
|
|
`<tt>lib</tt>', which does not bode well with the BSD
|
|
paradigm. Many of the files should me moved to one of the
|
|
following: `<tt>etc</tt>' (setup/configuration files),
|
|
`<tt>libexec</tt>' (executables started internally),
|
|
`<tt>sbin</tt>' (executables for superusers/managers),
|
|
`<tt>info</tt>' (documentation for info browser) or
|
|
`<tt>share</tt>' (architecture independent files). See man
|
|
<tt>hier(7)</tt> for details, the rule governing
|
|
<tt>/usr</tt> pretty much applies to <tt>/usr/local</tt>
|
|
too.
|
|
|
|
<sect3>
|
|
<heading>ldconfig</heading>
|
|
|
|
<p>If your port installs a shared library, add a
|
|
<tt>post-install</tt> target to your Makefile that runs
|
|
`<tt>/sbin/ldconfig -m</tt>' on the directory where the new
|
|
library is installed (usually <tt>${PREFIX}/lib</tt>)
|
|
to register it into the shared library cache.
|
|
|
|
<p>Also, add an <tt>@exec</tt> line to your <tt>pkg/PLIST</tt>
|
|
file so that a user who installed the package can start
|
|
using the shared library immediately. This line should
|
|
immediately follow the line for the shared library itself,
|
|
as in:
|
|
<tscreen><verb>
|
|
lib/libtcl.so.7.3
|
|
@exec /sbin/ldconfig -m %D/lib
|
|
</verb></tscreen>
|
|
|
|
<p>Never, ever, <em>ever</em> add a line that says
|
|
`<tt>ldconfig</tt>' without any arguments to your Makefile
|
|
or pkg/PLIST. This will reset the shared library cache to
|
|
the contents of <tt>/usr/lib</tt> only, and will royally
|
|
screw up the user's machine ("Help, xinit does not run
|
|
anymore after I install this port!"). Anybody who does this
|
|
will be shot and cut into 65,536 pieces by a rusty knife and
|
|
have his liver chopped out by a bunch of crows and will
|
|
eternally rot to death in the deepest bowels of hell (not
|
|
necessarily in that order)....
|
|
|
|
<sect3>
|
|
<heading>If you are stuck....</heading>
|
|
|
|
<p>Do look at existing examples and the <tt>bsd.port.mk</tt>
|
|
file before asking us questions! <tt>;)</tt>
|
|
|
|
<p>Do ask us questions if you have any trouble! Do not just
|
|
beat your head against a wall! <tt>:)</tt>
|
|
|
|
<sect2>
|
|
<heading>A Sample Makefile<label id="porting:samplem"></heading>
|
|
|
|
<p>Here is a sample Makefile that you can use to create a new
|
|
port. Make sure you remove all the extra comments (ones
|
|
between brackets)!
|
|
|
|
<p>It is recommended that you follow this format (ordering of
|
|
variables, empty lines between sections, etc.). Not all of
|
|
the existing Makefiles are in this format (mostly old ones),
|
|
but we are trying to uniformize how they look. This format is
|
|
designed so that the most important information is easy to
|
|
locate.
|
|
|
|
<tscreen><verb>
|
|
[the header...just to make it easier for us to identify the ports]
|
|
# New ports collection makefile for: xdvi
|
|
# Version required: pl18 [things like "1.5alpha" are fine here too]
|
|
# Date created: 26 May 1995
|
|
[this is the person who did the original port to FreeBSD, in particular, the
|
|
person who wrote this Makefile]
|
|
# Whom: Satoshi Asami <asami@FreeBSD.ORG>
|
|
#
|
|
# $Id$
|
|
[ ^^^^ This will be automatically replaced with RCS ID string by CVS
|
|
when it is committed to our repository.]
|
|
#
|
|
|
|
[section to describe the port itself and the master site - DISTNAME
|
|
is always first, followed by PKGNAME (if necessary), CATEGORIES,
|
|
and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
|
|
After those, one of EXTRACT_SUFX or DISTFILES can be specified too.]
|
|
DISTNAME= xdvi
|
|
PKGNAME= xdvi-pl18
|
|
CATEGORIES= print
|
|
[do not forget the trailing slash ("/")!]
|
|
MASTER_SITES= ${MASTER_SITE_XCONTRIB}
|
|
MASTER_SITE_SUBDIR= applications
|
|
[set this if the source is not in the standard ".tar.gz" form]
|
|
EXTRACT_SUFX= .tar.Z
|
|
|
|
[section for distributed patches -- can be empty]
|
|
PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/
|
|
PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz
|
|
|
|
[maintainer; *mandatory*! This is the person (preferably with commit
|
|
privileges) who a user can contact for questions and bug reports - this
|
|
person should be the porter or someone who can forward questions to the
|
|
original porter reasonably promptly. If you really do not want to have your
|
|
address here, set it to "ports@FreeBSD.ORG".]
|
|
MAINTAINER= asami@FreeBSD.ORG
|
|
|
|
[dependencies -- can be empty]
|
|
RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
|
|
LIB_DEPENDS= Xpm\\.4\\.:${PORTSDIR}/graphics/xpm
|
|
|
|
[this section is for other standard bsd.port.mk variables that do not belong
|
|
to any of the above]
|
|
[If it asks questions during configure, build, install...]
|
|
IS_INTERACTIVE= yes
|
|
[If it extracts to a directory other than ${DISTNAME}...]
|
|
WRKSRC= ${WRKDIR}/xdvi-new
|
|
[If the distributed patches were not made relative to ${WRKSRC}, you may need
|
|
to tweak this]
|
|
PATCH_DIST_STRIP= -p1
|
|
[If it requires a "configure" script generated by GNU autoconf to be run...]
|
|
GNU_CONFIGURE= yes
|
|
[If it requires GNU make, not /usr/bin/make, to build...]
|
|
USE_GMAKE= yes
|
|
[If it is an X application and requires "xmkmf -a" to be run...]
|
|
USE_IMAKE= yes
|
|
[et cetera.]
|
|
|
|
[non-standard variables to be used in the rules below]
|
|
MY_FAVORITE_RESPONSE= "yeah, right"
|
|
|
|
[then the special rules, in the order they are called]
|
|
pre-fetch:
|
|
i go fetch something, yeah
|
|
|
|
post-patch:
|
|
i need to do something after patch, great
|
|
|
|
pre-install:
|
|
and then some more stuff before installing, wow
|
|
|
|
[and then the epilogue]
|
|
.include <bsd.port.mk>
|
|
</verb></tscreen>
|
|
|
|
<sect2>
|
|
<heading>Package Names</heading>
|
|
|
|
<p>The following are the conventions you should follow in
|
|
naming your packages. This is to have our package directory
|
|
easy to scan, as there are already lots and lots of packages
|
|
and users are going to turn away if they hurt their eyes!
|
|
|
|
<p>The package name should look like
|
|
|
|
<tscreen><verb>
|
|
[<language>-]<name>[[-]<compiled.specifics>]-<version.string.numbers>;
|
|
</verb></tscreen>
|
|
|
|
If your <tt>${DISTNAME}</tt> doesn't look like that,
|
|
set <tt>${PKGNAME}</tt> to something in that format.
|
|
|
|
<enum>
|
|
<item>FreeBSD strives to support the native language of its
|
|
users. The `<language>' part should be a two letter
|
|
abbreviation of the natural language if the port is specific
|
|
to a certain language. Examples are `jp' for Japanese and
|
|
`ru' for Russian.
|
|
|
|
<item>The `<tt><name></tt>' part should be all
|
|
lowercases, except for a really large package (with lots of
|
|
programs in it). Things like XFree86 (yes there really is a
|
|
package of it, check it out) and ImageMagick fall into this
|
|
category. Otherwise, convert the name (or at least the
|
|
first letter) to lowercase. If the software in question
|
|
really is called that way, you can have numbers, hyphens and
|
|
underscores in the name too (like `kinput2').
|
|
|
|
<item>If the port can be built with different hardcoded
|
|
defaults (usually specified as environment variables or on
|
|
the <tt>make</tt> command line), the
|
|
`<compiled.specifics>' part should state the
|
|
compiled-in defaults (the hyphen is optional). Examples are
|
|
papersize and font units.
|
|
|
|
<item>The version string should be a period-separated list of
|
|
integers and single lowercase alphabets. The only exception
|
|
is the string `pl' (meaning `patchlevel'), which can be used
|
|
<em>only</em> when there are no major and minor version
|
|
numbers in the software.
|
|
</enum>
|
|
|
|
<p>Here are some (real) examples on how to convert a
|
|
<tt>${DISTNAME}</tt> into a suitable
|
|
<tt>${PKGNAME}</tt>:
|
|
|
|
<tscreen><verb>
|
|
DISTNAME PKGNAME Reason
|
|
mule-2.2.2 mule-2.2.2 no prob at all
|
|
XFree86-3.1.2 XFree86-3.1.2 ditto
|
|
EmiClock-1.0.2 emiclock-1.0.2 no uppercase names for single programs
|
|
gmod1.4 gmod-1.4 need hyphen after `<name>'
|
|
xmris.4.02 xmris-4.02 ditto
|
|
rdist-1.3alpha rdist-1.3a no strings like `alpha' allowed
|
|
es-0.9-beta1 es-0.9b1 ditto
|
|
v3.3beta021.src tiff-3.3 what the heck was that anyway? ;)
|
|
tvtwm tvtwm-pl11 version string always required
|
|
piewm piewm-1.0 ditto
|
|
xvgr-2.10pl1 xvgr-2.10.1 `pl' allowed only when no maj/minor numbers
|
|
gawk-2.15.6 jp-gawk-2.15.6 Japanese language version
|
|
psutils-1.13 psutils-letter-1.13 papersize hardcoded at package build time
|
|
pkfonts pkfonts300-1.0 package for 300dpi fonts
|
|
</verb></tscreen>
|
|
|
|
<p>If there is absolutely no trace of version information in the
|
|
original source and it is unlikely that the original author
|
|
will ever release another version, just set the version string
|
|
to `1.0' (like the piewm example above). Otherwise, ask the
|
|
original author or use the date string (`yy.mm.dd') as the
|
|
version.
|
|
|
|
<sect2>
|
|
<heading>That is It, Folks!</heading>
|
|
|
|
<p>Boy, this sure was a long tutorial, wasn't it? Thanks for
|
|
following us to here, really.
|
|
|
|
<p>Well, now that you know how to do a port, let us go at it and
|
|
convert everything in the world into ports! That is the
|
|
easiest way to start contributing to the FreeBSD Project!
|
|
<tt>:)</tt>
|