diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index 843883e43d..f1d5e58c83 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -1,9578 +1,9578 @@
%books.ent;
]>
FreeBSD Porter's HandbookThe FreeBSD Documentation ProjectApril 2000200020012002200320042005The FreeBSD Documentation
Project
&bookinfo.trademarks;
&bookinfo.legalnotice;
IntroductionThe FreeBSD ports collection is the way almost everyone
installs applications ("ports") on FreeBSD. Like everything
else about FreeBSD, it is primarily a volunteer effort.
It is important to keep this in mind when reading this
document.In FreeBSD, anyone may submit a new port, or volunteer
to maintain an existing port if it is unmaintained—you
do not need any special commit privileges to do so.Making a port yourselfSo, you are interested in making your own port or
upgrading an existing one? Great!What follows are some guidelines for creating a new port for
FreeBSD. If you want to upgrade an existing port, you should
read this and then read .When this document is not sufficiently detailed, you should
refer to /usr/ports/Mk/bsd.port.mk, which
all port Makefiles include. Even if you do not hack Makefiles
daily, it is well commented, and you will still gain much
knowledge from it. Additionally, you may send specific questions
to the &a.ports;.Only a fraction of the variables
(VAR) that can be
overridden are mentioned in this document. Most (if not all)
are documented at the start of /usr/ports/Mk/bsd.port.mk;
the others probably ought to be.
Note that this file uses a non-standard tab setting:
Emacs and
Vim should recognize the setting on
loading the file. Both &man.vi.1; and
&man.ex.1; can be set to use the correct value by
typing :set tabstop=4 once the file has been
loaded.Quick PortingThis section tells you how to do a quick port. In many cases, it
is not sufficient, so you will have to read further on into
the document.First, get the original tarball and put it into
DISTDIR, which defaults to
/usr/ports/distfiles.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.Writing the MakefileThe minimal Makefile would look something
like this:# New ports collection makefile for: oneko
# Date created: 5 December 1994
# Whom: asami
#
# $FreeBSD$
#
PORTNAME= oneko
PORTVERSION= 1.1b
CATEGORIES= games
MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
MAINTAINER= asami@FreeBSD.org
COMMENT= A cat chasing a mouse all over the screen
MAN1= oneko.1
MANCOMPRESSED= yes
USE_IMAKE= yes
.include <bsd.port.mk>See if you can figure it out. Do not worry about the contents
of the $FreeBSD$ 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 sample Makefile section.Writing the description filesThere are two description files that are required for
any port, whether they actually package or not. They are
pkg-descr and
pkg-plist. Their
pkg- prefix distinguishes them from
other files.pkg-descrThis is a longer description of the port. One to a few
paragraphs concisely explaining what the port does is
sufficient.This is not a manual or an in-depth
description on how to use or compile the port! Please
be careful if you are copying from the
README or manpage; too often
they are not a concise description of the port or are in an
awkward format (e.g., manpages have justified spacing). If the
ported software has an official WWW homepage, you should list it
here. Prefix one of the websites with
WWW: so that automated tools will work
correctly.It is recommended that you sign your name at the end of this
file, as in:This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
:
(etc.)
WWW: http://www.oneko.org/
- Satoshi
asami@cs.berkeley.edupkg-plistThis 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
/usr/local or
/usr/X11R6). If you are using the
MANn variables (as
you should be), do not list any manpages here.Here is a small example:bin/oneko
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpm
@dirrm lib/X11/onekoRefer to the &man.pkg.create.1; manual page for details on the
packing list.You should list all the files, but not the name directories,
in the list. Also, if the port creates directories for itself
during installation, make sure to add @dirrm
lines as necessary to remove them when the port is
deleted.It is recommended that you keep all the filenames in this
file sorted alphabetically. It will make verifying the changes
when you upgrade the port much easier.Creating a packing list manually can be a very tedious
task. If the port installs a large numbers of files, creating the packing list
automatically might save time.There is only one case when pkg-plist
can be omitted from a port. If the port installs just a handful
of files, and perhaps directories, the files and directories may
be listed in the variables PLIST_FILES and
PLIST_DIRS, respectively, within the port's
Makefile. For instance, we could get along
without pkg-plist in the above
oneko port by adding the
following lines to the Makefile:PLIST_FILES= bin/oneko \
lib/X11/app-defaults/Oneko \
lib/X11/oneko/cat1.xpm \
lib/X11/oneko/cat2.xpm \
lib/X11/oneko/mouse.xpm
PLIST_DIRS= lib/X11/onekoOf course, PLIST_DIRS should be left
unset if a port installs no directories of its own.The price for this way of listing port's files and
directories is that you cannot use command sequences
described in &man.pkg.create.1;. Therefore, it is suitable
only for simple ports and makes them even simpler. At the
same time, it has the advantage of reducing the number of files
in the ports collection. Please consider using this technique
before you resort to pkg-plist.Later we will see how pkg-plist
and PLIST_FILES can be used to fulfil
more sophisticated
tasks.Creating the checksum fileJust type make makesum. The ports make rules
will automatically generate the file
distinfo.If a file fetched has its checksum changed regularly and you are
certain the source is trusted (i.e. it comes from manufacturer CDs
or documentation generated daily), you should specify these files in
the IGNOREFILES variable.
Then the checksum is not calculated for that file when you run
make makesum, but set to
IGNORE.Testing the portYou should make sure that the port rules do exactly what you
want them to do, including packaging up the port. These are the
important points you need to verify.pkg-plist does not contain anything not
installed by your portpkg-plist contains everything that is
installed by your portYour port can be installed multiple times using the
reinstall targetYour port cleans up
after itself upon deinstallRecommended test orderingmake installmake packagemake deinstallpkg_add package-namemake deinstallmake reinstallmake packageMake sure that there are not any warnings issued in any of the
package and
deinstall stages. After step 3, check to
see if all the new directories are correctly deleted. Also, try
using the software after step 4, to ensure that it works correctly
when installed from a package.Checking your port with portlintPlease use portlint to see if your port
conforms to our guidelines. The portlint program
is part of the ports collection. In particular, you may want to
check if the Makefile is in
the right shape and the package is named
appropriately.Submitting the portFirst, make sure you have read the DOs and DON'Ts section.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. We do not need your work
directory or the pkgname.tgz package, so delete
them now. Next, simply include the output of shar `find
port_dir` in a bug report and send it with the
&man.send-pr.1; program (see Bug
Reports and General Commentary for more information about
&man.send-pr.1;). If the uncompressed port is larger than 20KB,
you should compress it into a tarfile and use &man.uuencode.1;
before including it in the bug report (uuencoded tarfiles are
acceptable even if the bug report is smaller than 20KB but are not
preferred). Be sure to classify the bug report as category
ports and class
change-request (Do not mark the report
confidential!).
Also add a short description of the program you ported
to the Description field of the PR and
the shar or uuencoded tarfile to the
Fix field.You can make our work a lot easier, if you use a good
description in the synopsis of the problem report.
We prefer something like
New port: <category>/<portname>
<short description of the port> for new ports and
Update port: <category>/<portname>
<short description of the update> for port updates.
If you stick to this scheme, the chance that someone will take a
look at your PR soon is much better.One more time, do not include the original source
distfile, the work directory, or the package
you built with make package.After you have submitted your port, please be patient.
Sometimes it can take a few months before a port is included
in FreeBSD, although it might only take a few days. You can
view the list of ports
waiting to be committed to FreeBSD.Once we have looked at your port, we will get back to you if necessary, and put
it in the tree. Your name will also appear in the list of
Additional FreeBSD Contributors
and other files. Isn't that great?!? :-)Slow PortingOk, 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.How things workFirst, this is the sequence of events which occurs when the user
first types make in your port's directory.
You may find that having bsd.port.mk in another
window while you read this really helps to understand it.But do not worry if you do not really understand what
bsd.port.mk is doing, not many people do...
:->The fetch target is run. The
fetch target is responsible for making
sure that the tarball exists locally in
DISTDIR. If fetch
cannot find the required files in DISTDIR it
will look up the URL MASTER_SITES, which is
set in the Makefile, as well as our main FTP site at ,
where we put sanctioned distfiles as backup. It will then
attempt to fetch the named distribution file with
FETCH, assuming that the requesting site has
direct access to the Internet. If that succeeds, it will save
the file in DISTDIR for future use and
proceed.The extract target is run. It
looks for your port's distribution file (typically a gzip'd
tarball) in DISTDIR and unpacks it into a
temporary subdirectory specified by WRKDIR
(defaults to work).The patch target is run. First,
any patches defined in PATCHFILES are
applied. Second, if any patch files named
patch-* are found in
PATCHDIR (defaults to the
files subdirectory), they are applied at
this time in alphabetical order.The configure target is run. This
can do any one of many different things.If it exists, scripts/configure is
run.If HAS_CONFIGURE or
GNU_CONFIGURE is set,
WRKSRC/configure is
run.If USE_IMAKE is set,
XMKMF (default: xmkmf
-a) is run.The build target is run. This is
responsible for descending into the port's private working
directory (WRKSRC) and building it. If
USE_GMAKE is set, GNU make
will be used, otherwise the system make will
be used.The above are the default actions. In addition, you can define
targets
pre-something or
post-something,
or put scripts with those names, in the scripts
subdirectory, and they will be run before or after the default
actions are done.For example, if you have a post-extract
target defined in your Makefile, and a file
pre-build in the scripts
subdirectory, the post-extract target will
be called after the regular extraction actions, and the
pre-build 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.The default actions are done by the
bsd.port.mk targets
do-something.
For example, the commands to extract a port are in the target
do-extract. If you are not happy with the
default target, you can fix it by redefining the
do-something
target in your Makefile.The main targets (e.g.,
extract,
configure, etc.) do nothing more than
make sure all the stages up to that one are completed and call
the real targets or scripts, and they are not intended to be
changed. If you want to fix the extraction, fix
do-extract, but never ever change
the way extract operates!Now that you understand what goes on when the user types
make, let us go through the recommended steps to
create the perfect port.Getting the original sourcesGet the original sources (normally) as a compressed tarball
(foo.tar.gz or
foo.tar.Z) and copy
it into DISTDIR. Always use
mainstream sources when and where you
can.You will need to set the variable MASTER_SITES
to reflect where the original tarball resides. You will find
convenient shorthand definitions for most mainstream sites
in bsd.sites.mk. Please use these
sites—and the associated definitions—if
at all possible, to help avoid the problem of having the same
information repeated over again many times in the source base.
As these sites tend to change over time, this becomes a
maintenance nightmare for everyone involved.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, you might want to put a copy on a reliable FTP or HTTP
server that you control (e.g., your home page).If you cannot find somewhere convenient and reliable to put the
distfile
we can house it ourselves
on ftp.FreeBSD.org; however, this is the
least-preferred solution.
The distfile must be placed into
~/public_distfiles/ of someone's
freefall account.
Ask the person who commits your port to do this.
This person will also set MASTER_SITES to
MASTER_SITE_LOCAL and
MASTER_SITE_SUBDIR to their
freefall username.If your port's distfile changes all the time without any
kind of version update by the author,
consider putting the distfile on your home page and listing it as
the first MASTER_SITES. If you can, try
to talk the port author out of doing this; it
really does help to establish some kind of source code control.
Hosting your own version will prevent users
from getting checksum mismatch errors, and
also reduce the workload of maintainers of our FTP site. Also, if
there is only one master site for the port, it is recommended that
you house a backup at your site and list it as the second
MASTER_SITES.If your port requires some additional `patches' that are
available on the Internet, fetch them too and put them in
DISTDIR. Do not worry if they come from a site
other than where you got the main source tarball, we have a way to
handle these situations (see the description of PATCHFILES below).Modifying the portUnpack 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 careful
track 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.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.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.PatchingIn the preparation of the port, files that have been added or
changed can be picked up with a recursive &man.diff.1;
for later feeding to &man.patch.1;. Each set of patches you
wish to apply should be collected into a file named
patch-* where
* indicates
the pathnames of the files that are patched,
such as patch-Imakefile or
patch-src-config.h. These files should
be stored in PATCHDIR, from where they will be
automatically applied. All patches must be relative to
WRKSRC (generally the directory your port's
tarball unpacks itself into, that being where the build is done).
To make fixes and upgrades easier, you should avoid having more than
one patch fix the same file (e.g., patch-file and
patch-file2 both changing
WRKSRC/foobar.c).Please only use characters [-+._a-zA-Z0-9] for
naming your patches. Do not use any other characters besides them.
Do not name your patches like patch-aa or
patch-ab etc, always mention path and file name
in patch names.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 ($) signs, and
typically start with $Id or
$RCS.Using the recurse () option to
&man.diff.1; to generate patches is fine, but please take
a look at the resulting patches to make sure you do not 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. If you had to edit
configure.in and run
autoconf to regenerate
configure, do not take the diffs of
configure (it often grows to a few thousand
lines!); define USE_AUTOCONF_VER=213 and take the
diffs of configure.in.Quite often, there is a situation when the software being
ported, especially if it is primarily developed on &windows;, uses
the CR/LF convention for most of its source files. This may cause
problems with further patching, compiler warnings, scripts
execution (/bin/sh^M not found), etc. To
quickly convert those files from CR/LF to just LF, you can do
something like this:USE_REINPLACE= yes
post-extract:
@${FIND} -E ${WRKDIR} -type f -iregex ".*\.(c|cpp|h|txt)" -print0 | \
${XARGS} -0 ${REINPLACE_CMD} -e 's/[[:cntrl:]]*$$//'Of course, if you need to process each and every file,
above can be omitted. Be aware that this
piece of code will strip all trailing control characters from each
line of processed file (except \n).Also, if you had to delete a file, then you can do it in the
post-extract target rather than as part of
the patch. Once you are happy with the resulting diff, please split
it up into one source file per patch file.ConfiguringInclude any additional customization commands in your
configure script and save it in the
scripts subdirectory. As mentioned above, you
can also do this with Makefile targets and/or
scripts with the name pre-configure or
post-configure.Handling user inputIf your port requires user input to build, configure, or install,
you must set IS_INTERACTIVE in your Makefile. This
will allow overnight builds to skip your port if the
user sets the variable BATCH in his environment (and
if the user sets the variable INTERACTIVE, then
only those ports requiring interaction are
built). This will save a lot of wasted time on the set of
machines that continually build ports (see below).It is also recommended that if there are reasonable default
answers to the questions, you check the
PACKAGE_BUILDING variable and turn off the
interactive script when it is set. This will allow us to build the
packages for CDROMs and FTP.Configuring the MakefileConfiguring the Makefile is pretty simple, and again we suggest
that you look at existing examples before starting. Also, there is a
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.Now, consider the following problems in sequence as you design
your new Makefile:The original sourceDoes it live in DISTDIR as a standard
gzip'd tarball named something like
foozolix-1.2.tar.gz? If so, you can go on
to the next step. If not, you should look at overriding any of
the DISTVERSION, DISTNAME,
EXTRACT_CMD,
EXTRACT_BEFORE_ARGS,
EXTRACT_AFTER_ARGS,
EXTRACT_SUFX, or DISTFILES
variables, depending on how alien a format your port's
distribution file is. (The most common case is
EXTRACT_SUFX=.tar.Z, when the tarball is
condensed by regular compress, not
gzip.)In the worst case, you can simply create your own
do-extract target to override the
default, though this should be rarely, if ever,
necessary.NamingThe first part of the port's Makefile names
the port, describes its version number, and lists it in the correct
category.PORTNAME and PORTVERSIONYou should set PORTNAME to the
base name of your port, and PORTVERSION
to the version number of the port.PORTREVISION and
PORTEPOCHPORTREVISIONThe PORTREVISION variable is a
monotonically increasing value which is reset to 0 with
every increase of PORTVERSION (i.e.
every time a new official vendor release is made), and
appended to the package name if non-zero.
Changes to PORTREVISION are
used by automated tools (e.g. &man.pkg.version.1;)
to highlight the fact that a new package is
available.PORTREVISION should be increased
each time a change is made to the port which significantly
affects the content or structure of the derived
package.Examples of when PORTREVISION
should be bumped:Addition of patches to correct security
vulnerabilities, bugs, or to add new functionality to
the port.Changes to the port Makefile to enable or disable
compile-time options in the package.Changes in the packing list or the install-time
behavior of the package (e.g. change to a script
which generates initial data for the package, like ssh
host keys).Version bump of a port's shared library dependency
(in this case, someone trying to install the old
package after installing a newer version of the
dependency will fail since it will look for the old
libfoo.x instead of libfoo.(x+1)).Silent changes to the port distfile which have
significant functional differences, i.e. changes to
the distfile requiring a correction to
distinfo with no corresponding change to
PORTVERSION, where a diff
-ru of the old and new versions shows
non-trivial changes to the code.Examples of changes which do not require a
PORTREVISION bump:Style changes to the port skeleton with no
functional change to what appears in the resulting
package.Changes to MASTER_SITES or
other functional changes to the port which do not
affect the resulting package.Trivial patches to the distfile such as correction
of typos, which are not important enough that users of
the package should go to the trouble of
upgrading.Build fixes which cause a package to become
compilable where it was previously failing (as long as
the changes do not introduce any functional change on
any other platforms on which the port did previously
build). Since PORTREVISION reflects
the content of the package, if the package was not
previously buildable then there is no need to increase
PORTREVISION to mark a
change.A rule of thumb is to ask yourself whether a change
committed to a port is something which everyone
would benefit from having (either because of an
enhancement, fix, or by virtue that the new package will
actually work at all), and weigh that against that fact
that it will cause everyone who regularly updates their
ports tree to be compelled to update. If yes, the
PORTREVISION should be bumped.PORTEPOCHFrom time to time a software vendor or FreeBSD porter
will do something silly and release a version of their
software which is actually numerically less than the
previous version. An example of this is a port which goes
from foo-20000801 to foo-1.0 (the former will be
incorrectly treated as a newer version since 20000801 is a
numerically greater value than 1).In situations such as this, the
PORTEPOCH version should be increased.
If PORTEPOCH is nonzero it is appended
to the package name as described in section 0 above.
PORTEPOCH must never be decreased or reset
to zero, because that would cause comparison to a package
from an earlier epoch to fail (i.e. the package would not
be detected as out of date): the new version number (e.g.
1.0,1 in the above example) is still
numerically less than the previous version (20000801), but
the ,1 suffix is treated specially by
automated tools and found to be greater than the implied
suffix ,0 on the earlier package.Dropping or resetting PORTEPOCH
incorrectly leads
to no end of grief; if you do not understand the above discussion,
please keep after it until you do, or ask questions on
the mailing lists.It is expected that PORTEPOCH will
not be used for the majority of ports, and that sensible
use of PORTVERSION can often pre-empt
it becoming necessary if a future release of the software
should change the version structure. However, care is
needed by FreeBSD porters when a vendor release is made
without an official version number — such as a code
snapshot release. The temptation is to label the
release with the release date, which will cause problems
as in the example above when a new official release is
made.For example, if a snapshot release is made on the date
20000917, and the previous version of the software was
version 1.2, the snapshot release should be given a
PORTVERSION of 1.2.20000917 or similar,
not 20000917, so that the succeeding release, say 1.3, is
still a numerically greater value.Example of PORTREVISION and
PORTEPOCH usageThe gtkmumble port, version
0.10, is committed to the ports
collection:PORTNAME= gtkmumble
PORTVERSION= 0.10PKGNAME becomes
gtkmumble-0.10.A security hole is discovered which requires a local
FreeBSD patch. PORTREVISION is bumped
accordingly.PORTNAME= gtkmumble
PORTVERSION= 0.10
PORTREVISION= 1PKGNAME becomes
gtkmumble-0.10_1A new version is released by the vendor, numbered 0.2
(it turns out the author actually intended
0.10 to actually mean
0.1.0, not what comes after
0.9 - oops, too late now). Since the new minor
version 2 is numerically less than the
previous version 10, the
PORTEPOCH must be bumped to manually
force the new package to be detected as newer. Since it
is a new vendor release of the code,
PORTREVISION is reset to 0 (or removed
from the Makefile).PORTNAME= gtkmumble
PORTVERSION= 0.2
PORTEPOCH= 1PKGNAME becomes
gtkmumble-0.2,1The next release is 0.3. Since
PORTEPOCH never decreases, the version
variables are now:PORTNAME= gtkmumble
PORTVERSION= 0.3
PORTEPOCH= 1PKGNAME becomes
gtkmumble-0.3,1If PORTEPOCH were reset
to 0 with this upgrade, someone who had
installed the gtkmumble-0.10_1 package would not detect
the gtkmumble-0.3 package as newer, since
3 is still numerically less than
10. Remember, this is the whole point of
PORTEPOCH in the first place.PKGNAMEPREFIX and PKGNAMESUFFIXTwo optional variables, PKGNAMEPREFIX and
PKGNAMESUFFIX, are combined with
PORTNAME and
PORTVERSION to
form PKGNAME as
${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}.
Make sure this conforms to our guidelines for a good package
name. In particular, you are not allowed to use a
hyphen (-) in
PORTVERSION. Also, if the package name
has the language- or the
-compiled.specifics part (see below), use
PKGNAMEPREFIX and
PKGNAMESUFFIX, respectively. Do not make
them part of PORTNAME.Package Naming ConventionsThe 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 thousands of packages and users are going to
turn away if they hurt their eyes!The package name should look like
language_region-name-compiled.specifics-version.numbers.The package name is defined as
${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}.
Make sure to set the variables to conform to that format.FreeBSD strives to support the native language of its users.
The language- part should be a two
letter abbreviation of the natural language defined by ISO-639 if
the port is specific to a certain language. Examples are
ja for Japanese, ru for
Russian, vi for Vietnamese,
zh for Chinese, ko for
Korean and de for German.If the port is specific to a certain region within the
language area, add the two letter country code as well.
Examples are en_US for US English and
fr_CH for Swiss French.The language- part should
be set in the PKGNAMEPREFIX variable.The first letter of name part
should be lowercase. (The rest of the name can contain
capital letters, so use your own discretion when you are
converting a software name that has some capital letters in it.)
There is a tradition of naming perl 5 modules by
prepending p5- and converting the double-colon
separator to a hyphen; for example, the
Data::Dumper module becomes
p5-Data-Dumper. If the software in question
has numbers, hyphens, or underscores in its name, you may include
them as well (like kinput2).If the port can be built with different hardcoded defaults (usually
part of the directory name in a family of ports), the
-compiled.specifics part should state
the compiled-in defaults (the hyphen is optional). Examples are
papersize and font units.The -compiled.specifics part
should be set in the PKGNAMESUFFIX
variable.The version string should follow a dash
(-) and be a period-separated list of
integers and single lowercase alphabetics. In particular,
it is not permissible to have another dash inside the
version string. The only exception is the string
pl (meaning patchlevel), which can be
used only when there are no major and
minor version numbers in the software. If the software
version has strings like alpha, beta, rc, or pre, take
the first letter and put it immediately after a period.
If the version string continues after those names, the
numbers should follow the single alphabet without an extra
period between them.The idea is to make it easier to sort ports by looking
at the version string. In particular, make sure version
number components are always delimited by a period, and
if the date is part of the string, use the
yyyy.mm.dd
format, not
dd.mm.yyyy
or the non-Y2K compliant
yy.mm.dd
format.Here are some (real) examples on how to convert the name
as called by the software authors to a suitable package
name:Distribution NamePKGNAMEPREFIXPORTNAMEPKGNAMESUFFIXPORTVERSIONReasonmule-2.2.2(empty)mule(empty)2.2.2No changes requiredXFree86-3.3.6(empty)XFree86(empty)3.3.6No changes requiredEmiClock-1.0.2(empty)emiclock(empty)1.0.2No uppercase names for single programsrdist-1.3alpha(empty)rdist(empty)1.3.aNo strings like alpha
allowedes-0.9-beta1(empty)es(empty)0.9.b1No strings like beta
allowedmailman-2.0rc3(empty)mailman(empty)2.0.r3No strings like rc
allowedv3.3beta021.src(empty)tiff(empty)3.3What the heck was that anyway?tvtwm(empty)tvtwm(empty)pl11Version string always requiredpiewm(empty)piewm(empty)1.0Version string always requiredxvgr-2.10pl1(empty)xvgr(empty)2.10.1pl allowed only when no
major/minor version numbersgawk-2.15.6ja-gawk(empty)2.15.6Japanese language versionpsutils-1.13(empty)psutils-letter1.13Papersize hardcoded at package build timepkfonts(empty)pkfonts3001.0Package for 300dpi fontsIf 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
(yyyy.mm.dd)
as the version.CategorizationCATEGORIESWhen a package is created, it is put under
/usr/ports/packages/All and links are made from
one or more subdirectories of
/usr/ports/packages. The names of these
subdirectories are specified by the variable
CATEGORIES. 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 CDROM. Please take a look at the current list of categories and pick the ones
that are suitable for your port.This list also determines where in the ports tree the port is
imported. If you put more than one category here, it is assumed
that the port files will be put in the subdirectory with the name in
the first category. See below for more
discussion about how to pick the right categories.Current list of categoriesHere is the current list of port categories. Those
marked with an asterisk (*) are
virtual categories—those that do not have
a corresponding subdirectory in the ports tree. They are only
used as secondary categories, and only for search purposes.For non-virtual categories, you will find a one-line
description in the COMMENT in that
subdirectory's Makefile.CategoryDescriptionNotesaccessibilityPorts to help disabled users.afterstep*Ports to support the
AfterStep
window manager.arabicArabic language support.archiversArchiving tools.astroAstronomical ports.audioSound support.benchmarksBenchmarking utilities.biologyBiology-related software.cadComputer aided design tools.chineseChinese language support.commsCommunication software.Mostly software to talk to your serial port.convertersCharacter code converters.databasesDatabases.deskutilsThings that used to be on the desktop before
computers were invented.develDevelopment utilities.Do not put libraries here just because they are
libraries—unless they truly do not belong anywhere
else, they should not be in this category.dnsDNS-related software.editorsGeneral editors.Specialized editors go in the section for those
tools (e.g., a mathematical-formula editor will go
in math).elisp*Emacs-lisp ports.emulatorsEmulators for other operating systems.Terminal emulators do not belong
here—X-based ones should go to
x11 and text-based ones to either
comms or misc,
depending on the exact functionality.financeMonetary, financial and related applications.frenchFrench language support.ftpFTP client and server utilities.If your port speaks both FTP and HTTP, put it in
ftp with a secondary
category of www.gamesGames.germanGerman language support.gnome*Ports from the GNOME
Project.graphicsGraphics utilities.haskell*Software related to the Haskell language.hebrewHebrew language support.hungarianHungarian language support.ipv6*IPv6 related software.ircInternet Relay Chat utilities.japaneseJapanese language support.javaSoftware related to the Java language.The java category shall not be
the only one for a port. Save for ports directly related to
the Java language, porters are also encouraged not to
use java as the main category of a
port.kde*Ports from the K Desktop Environment (KDE)
Project.koreanKorean language support.langProgramming languages.linux*Linux applications and support utilities.lisp*Software related to the Lisp language.mailMail software.mathNumerical computation software and other utilities
for mathematics.mboneMBone applications.miscMiscellaneous utilitiesBasically things that
do not belong anywhere else.
If at all possible, try to
find a better category for your port than
misc, as ports tend to get overlooked
in here.multimediaMultimedia software.netMiscellaneous networking software.net-mgmtNetworking management software.newsUSENET news software.offix*Ports from the OffiX suite.palmSoftware support for the Palm™ series.parallel*Applications dealing with parallelism in computing.pear*Ports related to the Pear PHP framework.perl5*Ports that require Perl version 5 to run.plan9*Various programs from Plan9.polishPolish language support.portuguesePortuguese language support.printPrinting software.Desktop publishing tools
(previewers, etc.) belong here too.python*Software related to the Python language.ruby*Software related to the Ruby language.russianRussian language support.scienceScientific ports that do not fit into other
categories such as astro,
biology and
math.securitySecurity utilities.shellsCommand line shells.sysutilsSystem utilities.tcl76*Ports that use Tcl version 7.6 to run.tcl80*Ports that use Tcl version 8.0 to run.tcl81*Ports that use Tcl version 8.1 to run.tcl82*Ports that use Tcl version 8.2 to run.tcl83*Ports that use Tcl version 8.3 to run.textprocText processing utilities.It does not include
desktop publishing tools, which go to print.tk42*Ports that use Tk version 4.2 to run.tk80*Ports that use Tk version 8.0 to run.tk81*Ports that use Tk version 8.1 to run.tk82*Ports that use Tk version 8.2 to run.tk83*Ports that use Tk version 8.3 to run.tkstep80*Ports that use TkSTEP version 8.0 to run.ukrainianUkrainian language support.vietnameseVietnamese language support.windowmaker*Ports to support the WindowMaker window
manager.wwwSoftware related to the World Wide Web.HTML language
support belongs here too.x11The X Window System and friends.This category is only
for software that directly supports the window system. Do not
put regular X applications here; most of them should go
into other x11-* categories (see below).
If your port is an X
application, define USE_XLIB (implied by
USE_IMAKE) and put it in the appropriate
category.x11-clocksX11 clocks.x11-fmX11 file managers.x11-fontsX11 fonts and font utilities.x11-serversX11 servers.x11-toolkitsX11 toolkits.x11-wmX11 window managers.zope*Zope support.Choosing the right categoryAs many of the categories overlap, you often have to choose
which of the categories should be the primary category of your port.
There are several rules that govern this issue. Here is the list of
priorities, in decreasing order of precedence:The first category must be a physical category (see
above). This is
necessary to make the packaging work. Virtual categories and
physical categories may be intermixed after that.Language specific categories always come first. For
example, if your port installs Japanese X11 fonts, then your
CATEGORIES line would read japanese
x11-fonts.Specific categories are listed before less-specific ones. For
instance, an HTML editor should be listed as www
editors, not the other way around. Also, you should not
list net when the port belongs to
any of irc, mail,
mbone, news,
security, or www, as
net is included implicitly.x11 is used as a secondary category only
when the primary category is a natural language. In particular,
you should not put x11 in the category line
for X applications.Emacs modes should be
placed in the same ports category as the application
supported by the mode, not in
editors. For example, an
Emacs mode to edit source
files of some programming language should go into
lang.
misc
should not appear with any other non-virtual category.
If you have misc with something else in
your CATEGORIES line, that means you can
safely delete misc and just put the port
in that other subdirectory!If your port truly does not belong anywhere else, put it in
misc.If you are not sure about the category, please put a comment to
that effect in your &man.send-pr.1; submission so we can
discuss it before we import it. If you are a committer, send a note
to the &a.ports; so we can discuss it first. Too often, new ports are
imported to the wrong category only to be moved right away.
This causes unnecessary and undesirable bloat in the master
source repository.Proposing a new categoryAs the Ports Collection has grown over time, various new
categories have been introduced. New categories can either
be virtual categories—those that do
not have a corresponding subdirectory in the ports tree—
or physical categories—those that
do. The following text discusses the issues involved in creating
a new physical category so that you can understand them before
you propose one.Our existing practice has been to avoid creating a new
physical category unless either a large number of ports would
logically belong to it, or the ports that would belong to it
are a logically distinct group that is of limited general
interest (for instance, categories related to spoken human
languages), or preferably both.The rationale for this is that such a change creates a
fair amount of work for both the committers and also
for all users who track changes to the Ports Collection. In
addition, proposed category changes just naturally seem to
attract controversy. (Perhaps this is because there is no
clear consensus on when a category is too big,
nor whether categories should lend themselves to browsing (and
thus what number of categories would be an ideal number), and
so forth.)Here is the procedure:Propose the new category on &a.ports;. You should
include a detailed rationale for the new category,
including why you feel the existing categories are not
sufficient, and the list of existing ports proposed to move.
(If there are new ports pending in
GNATS that would fit this
category, list them too.) If you are the maintainer and/or
submitter, respectively, mention that as it may help you
to make your case.Participate in the discussion.If it seems that there is support for your idea,
file a PR which includes both the rationale and the list
of existing ports that need to be moved. Ideally, this
PR should also include patches for the following:Makefiles for the
new ports once they are repocopiedMakefile for the
new categoryMakefile for the
old ports' categoriesMakefiles for ports
that depend on the old ports(for extra credit, you can include the other
files that have to change, as per the procedure
in the Committer's Guide.)Since it affects the ports infrastructure and involves
not only performing repo-copies but also possibly running
regression tests on the build cluster, the PR should be
assigned to the &a.portmgr;.If that PR is approved, a committer will need to follow
the rest of the procedure that is
outlined in the Committer's Guide.Proposing a new virtual category should be similar to
the above but much less involved, since no ports will
actually have to move. In this case, the only patches to
include in the PR would be those to add the new category to the
CATEGORIESs of the affected ports.Proposing reorganizing all the categoriesOccasionally someone proposes reorganizing the categories
with either a 2-level structure, or some other kind of keyword
structure. To date, nothing has come of any of these proposals
because, while they are very easy to make, the effort involved to
retrofit the entire existing ports collection with any kind of
reorganization is daunting to say the very least. Please read
the history of these proposals in the mailing list archives before
you post this idea; furthermore, you should be prepared to be
challenged to offer a working prototype.The distribution filesThe second part of the Makefile describes the
files that must be downloaded in order to build the port, and where
they can be downloaded from.DISTVERSION/DISTNAMEDISTNAME is the name of the port as
called by the authors of the software.
DISTNAME defaults to
${PORTNAME}-${PORTVERSION}, so override it only if necessary.
DISTNAME is only used in two places.
First, the distribution file list
(DISTFILES) defaults to
${DISTNAME}${EXTRACT_SUFX}.
Second, the distribution file is expected to extract into a
subdirectory named WRKSRC, which defaults
to work/${DISTNAME}.Some vendor's distribution names which do not fit into the
${PORTNAME}-${PORTVERSION}-scheme can be handled
automatically by setting DISTVERSION.
PORTVERSION and DISTNAME will be
derived automatically, but can of course be overridden. The following
table lists some examples:DISTVERSIONPORTVERSION0.7.1d0.7.1.d10Alpha310.a33Beta7-pre23.b7.p28:f_178f.17PKGNAMEPREFIX and
PKGNAMESUFFIX do not affect
DISTNAME. Also note that if
WRKSRC is equal to
work/${PORTNAME}-${PORTVERSION}
while the original source archive is named something other than
${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX},
you should probably leave DISTNAME
alone— you are better off defining
DISTFILES than having to set both
DISTNAME and WRKSRC
(and possibly EXTRACT_SUFX).MASTER_SITESRecord the directory part of the FTP/HTTP-URL pointing at the
original tarball in MASTER_SITES. Do not forget
the trailing slash (/)!The make macros will try to use this
specification for grabbing the distribution file with
FETCH if they cannot find it already on the
system.It is recommended that you put multiple sites on this list,
preferably from different continents. This will safeguard against
wide-area network problems. We are even planning to add support
for automatically determining the closest master site and fetching
from there; having multiple sites will go a long way towards
helping this effort.If the original tarball is part of one of the popular
archives such as X-contrib, GNU, or Perl CPAN, you may be able
refer to those sites in an easy compact form using
MASTER_SITE_*
(e.g., MASTER_SITE_XCONTRIB and
MASTER_SITE_PERL_GNU). Simply set
MASTER_SITES to one of these variables and
MASTER_SITE_SUBDIR to the path within the
archive. Here is an example:MASTER_SITES= ${MASTER_SITE_XCONTRIB}
MASTER_SITE_SUBDIR= applicationsThese variables are defined in
/usr/ports/Mk/bsd.sites.mk. There are
new entries added all the time, so make sure to check the
latest version of this file before submitting a port.The user can also set the MASTER_SITE_*
variables in /etc/make.conf to override our
choices, and use their favorite mirrors of these popular archives
instead.EXTRACT_SUFXIf you have one distribution file, and it uses an odd suffix to
indicate the compression mechanism, set
EXTRACT_SUFX.For example, if the distribution file was named
foo.tgz instead of the more normal
foo.tar.gz, you would write:DISTNAME= foo
EXTRACT_SUFX= .tgzThe USE_BZIP2 and USE_ZIP
variables automatically set EXTRACT_SUFX to
.tar.bz2 or .zip as necessary. If
neither of these are set then EXTRACT_SUFX
defaults to .tar.gz.You never need to set both EXTRACT_SUFX and
DISTFILES.DISTFILESSometimes the names of the files to be downloaded have no
resemblance to the name of the port. For example, it might be
called source.tar.gz or similar. In other
cases the application's source code might be in several different
archives, all of which must be downloaded.If this is the case, set DISTFILES to be a
space separated list of all the files that must be
downloaded.DISTFILES= source1.tar.gz source2.tar.gzIf not explicitly set, DISTFILES defaults to
${DISTNAME}${EXTRACT_SUFX}.EXTRACT_ONLYIf only some of the DISTFILES must be
extracted—for example, one of them is the source code, while
another is an uncompressed document—list the filenames that
must be extracted in EXTRACT_ONLY.DISTFILES= source.tar.gz manual.html
EXTRACT_ONLY= source.tar.gzIf none of the DISTFILES
should be uncompressed then set EXTRACT_ONLY to
the empty string.EXTRACT_ONLY=PATCHFILESIf your port requires some additional patches that are available
by FTP or HTTP, set PATCHFILES to the names of
the files and PATCH_SITES to the URL of the
directory that contains them (the format is the same as
MASTER_SITES).If the patch is not relative to the top of the source tree
(i.e., WRKSRC) because it contains some extra
pathnames, set PATCH_DIST_STRIP accordingly. For
instance, if all the pathnames in the patch have an extra
foozolix-1.0/ in front of the filenames, then set
PATCH_DIST_STRIP=-p1.Do not worry if the patches are compressed; they will be
decompressed automatically if the filenames end with
.gz or .Z.If the patch is distributed with some other files, such as
documentation, in a gzip'd tarball, you cannot just use
PATCHFILES. If that is the case, add the name
and the location of the patch tarball to
DISTFILES and MASTER_SITES.
Then, use the EXTRA_PATCHES variable to
point to those files and bsd.port.mk
will automatically apply them for you. In particular, do
not copy patch files into the
PATCHDIR directory—that directory may
not be writable.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 pre-clean
target.Multiple distribution files or patches from different
sites and subdirectories
(MASTER_SITES:n)(Consider this to be a somewhat advanced topic;
those new to this document may wish to skip this section at first).
This section has information on the fetching mechanism
known as both MASTER_SITES:n and
MASTER_SITES_NN. We will refer to this
mechanism as MASTER_SITES:n
hereon.A little background first. OpenBSD has a neat feature
inside both DISTFILES and
PATCHFILES variables, both files and
patches can be postfixed with :n
identifiers where n both can be
[0-9] and denote a group designation.
For example:DISTFILES= alpha:0 beta:1In OpenBSD, distribution file alpha
will be associated with variable
MASTER_SITES0 instead of our common
MASTER_SITES and
beta with
MASTER_SITES1.This is a very interesting feature which can decrease
that endless search for the correct download site.Just picture 2 files in DISTFILES and
20 sites in MASTER_SITES, the sites slow
as hell where beta is carried by all
sites in MASTER_SITES, and
alpha can only be found in the 20th
site. It would be such a waste to check all of them if
maintainer knew this beforehand, would it not? Not a good
start for that lovely weekend!Now that you have the idea, just imagine more
DISTFILES and more
MASTER_SITES. Surely our
distfiles survey meister would appreciate the
relief to network strain that this would bring.In the next sections, information will follow on the
FreeBSD implementation of this idea. We improved a bit on
OpenBSD's concept.Simplified informationThis section tells you how to quickly prepare fine
grained fetching of multiple distribution files and
patches from different sites and subdirectories. We
describe here a case of simplified
MASTER_SITES:n usage. This will be
sufficient for most scenarios. However, if you need
further information, you will have to refer to the next
section.Some applications consist of multiple distribution
files that must be downloaded from a number of different
sites. For example,
Ghostscript consists of the
core of the program, and then a large number of driver
files that are used depending on the user's printer. Some
of these driver files are supplied with the core, but many
others must be downloaded from a variety of different
sites.To support this, each entry in
DISTFILES may be followed by a colon
and a tag name. Each site listed in
MASTER_SITES is then followed by a
colon, and the tag that indicates which distribution files
should be downloaded from this site.For example, consider an application with the source
split in two parts, source1.tar.gz
and source2.tar.gz, which must be
downloaded from two different sites. The port's
Makefile would include lines like
.Simplified use of MASTER_SITES:n
with 1 file per siteMASTER_SITES= ftp://ftp.example1.com/:source1 \
ftp://ftp.example2.com/:source2
DISTFILES= source1.tar.gz:source1 \
source2.tar.gz:source2Multiple distribution files can have the same tag.
Continuing the previous example, suppose that there was a
third distfile, source3.tar.gz, that
should be downloaded from
ftp.example2.com. The
Makefile would then be written like
.Simplified use of MASTER_SITES:n
with more than 1 file per siteMASTER_SITES= ftp://ftp.example1.com/:source1 \
ftp://ftp.example2.com/:source2
DISTFILES= source1.tar.gz:source1 \
source2.tar.gz:source2 \
source3.tar.gz:source2Detailed informationOkay, so the previous section example did not reflect
your needs? In this section we will explain in detail how
the fine grained fetching mechanism
MASTER_SITES:n works and how you can
modify your ports to use it.Elements can be postfixed with
:n where
n is
[^:,]+, i.e.,
n could conceptually be any
alphanumeric string but we will limit it to
[a-zA-Z_][0-9a-zA-Z_]+ for
now.Moreover, string matching is case sensitive;
i.e., n is different from
N.However, the following words cannot be used for
postfixing purposes since they yield special meaning:
default, all and
ALL (they are used internally in
item ).
Furthermore, DEFAULT is a special
purpose word (check item ).Elements postfixed with :n
belong to the group n,
:m belong to group
m and so forth.Elements without a postfix are groupless, i.e.,
they all belong to the special group
DEFAULT. If you postfix any
elements with DEFAULT, you are just
being redundant unless you want to have an element
belonging to both DEFAULT and other
groups at the same time (check item ).The following examples are equivalent but the
first one is preferred:MASTER_SITES= alpha
MASTER_SITES= alpha:DEFAULTGroups are not exclusive, an element may belong to
several different groups at the same time and a group
can either have either several different elements or
none at all. Repeated elements within the same group
will be simply that, repeated elements.When you want an element to belong to several
groups at the same time, you can use the comma
operator (,).Instead of repeating it several times, each time
with a different postfix, we can list several groups
at once in a single postfix. For instance,
:m,n,o marks an element that
belongs to group m,
n and o.All the following examples are equivalent but the
last one is preferred:MASTER_SITES= alpha alpha:SOME_SITE
MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE
MASTER_SITES= alpha:SOME_SITE,DEFAULT
MASTER_SITES= alpha:DEFAULT,SOME_SITEAll sites within a given group are sorted
according to MASTER_SORT_AWK. All
groups within MASTER_SITES and
PATCH_SITES are sorted as
well.Group semantics can be used in any of the
following variables MASTER_SITES,
PATCH_SITES,
MASTER_SITE_SUBDIR,
PATCH_SITE_SUBDIR,
DISTFILES, and
PATCHFILES according to the
following syntax:All MASTER_SITES,
PATCH_SITES,
MASTER_SITE_SUBDIR and
PATCH_SITE_SUBDIR elements must
be terminated with the forward slash
/ character. If any elements
belong to any groups, the group postfix
:n
must come right after the terminator
/. The
MASTER_SITES:n mechanism relies
on the existence of the terminator
/ to avoid confusing elements
where a :n is a valid part of
the element with occurrences where
:n denotes group
n. For compatibility purposes,
since the / terminator was not
required before in both
MASTER_SITE_SUBDIR and
PATCH_SITE_SUBDIR elements, if
the postfix immediate preceding character is not
a / then :n
will be considered a valid part of the element
instead of a group postfix even if an element is
postfixed with :n. See both
and .Detailed use of
MASTER_SITES:n in
MASTER_SITE_SUBDIRMASTER_SITE_SUBDIR= old:n new/:NEWDirectories within group
DEFAULT -> old:nDirectories within group
NEW -> newDetailed use of
MASTER_SITES:n with comma
operator, multiple files, multiple sites and
multiple subdirectoriesMASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \
http://site3/:group3 http://site4/:group4 \
http://site5/:group5 http://site6/:group6 \
http://site7/:DEFAULT,group6 \
http://site8/%SUBDIR%/:group6,group7 \
http://site9/:group8
DISTFILES= file1 file2:DEFAULT file3:group3 \
file4:group4,group5,group6 file5:grouping \
file6:group7
MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \
directory-one/:group6,DEFAULT \
directoryThe previous example results in the
following fine grained fetching. Sites are
listed in the exact order they will be
used.file1 will be
fetched fromMASTER_SITE_OVERRIDEhttp://site1/directory-trial:1/http://site1/directory-one/http://site1/directory/http://site2/http://site7/MASTER_SITE_BACKUPfile2 will be
fetched exactly as
file1 since they
both belong to the same groupMASTER_SITE_OVERRIDEhttp://site1/directory-trial:1/http://site1/directory-one/http://site1/directory/http://site2/http://site7/MASTER_SITE_BACKUPfile3 will be
fetched fromMASTER_SITE_OVERRIDEhttp://site3/MASTER_SITE_BACKUPfile4 will be
fetched fromMASTER_SITE_OVERRIDEhttp://site4/http://site5/http://site6/http://site7/http://site8/directory-one/MASTER_SITE_BACKUPfile5 will be
fetched fromMASTER_SITE_OVERRIDEMASTER_SITE_BACKUPfile6 will be
fetched fromMASTER_SITE_OVERRIDEhttp://site8/MASTER_SITE_BACKUPHow do I group one of the special variables from
bsd.sites.mk, e.g.,
MASTER_SITE_SOURCEFORGE?See .Detailed use of
MASTER_SITES:n with
MASTER_SITE_SOURCEFORGEMASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/}
DISTFILES= something.tar.gz:sourceforgesomething.tar.gz will be
fetched from all sites within
MASTER_SITE_SOURCEFORGE.How do I use this with PATCH*
variables?All examples were done with
MASTER* variables but they work
exactly the same for PATCH* ones as
can be seen in .Simplified use of
MASTER_SITES:n with
PATCH_SITES.PATCH_SITES= http://site1/ http://site2/:test
PATCHFILES= patch1:testWhat does change for ports? What does not?All current ports remain the same. The
MASTER_SITES:n feature code is only
activated if there are elements postfixed with
:n like
elements according to the aforementioned syntax rules,
especially as shown in item .The port targets remain the same:
checksum,
makesum,
patch,
configure,
build, etc. With the obvious
exceptions of do-fetch,
fetch-list,
master-sites and
patch-sites.do-fetch: deploys the
new grouping postfixed
DISTFILES and
PATCHFILES with their matching
group elements within both
MASTER_SITES and
PATCH_SITES which use matching
group elements within both
MASTER_SITE_SUBDIR and
PATCH_SITE_SUBDIR. Check .fetch-list: works
like old fetch-list with
the exception that it groups just like
do-fetch.master-sites and
patch-sites:
(incompatible with older versions) only return the
elements of group DEFAULT; in
fact, they execute targets
master-sites-default and
patch-sites-default
respectively.Furthermore, using target either
master-sites-all or
patch-sites-all is
preferred to directly checking either
MASTER_SITES or
PATCH_SITES. Also,
directly checking is not guaranteed to work in any
future versions. Check item
for more information on these new port
targets.New port targetsThere are
master-sites-n
and
patch-sites-n
targets which will list the elements of the
respective group n
within MASTER_SITES and
PATCH_SITES respectively. For
instance, both
master-sites-DEFAULT and
patch-sites-DEFAULT will
return the elements of group
DEFAULT,
master-sites-test and
patch-sites-test of group
test, and thereon.There are new targets
master-sites-all and
patch-sites-all which do
the work of the old
master-sites and
patch-sites ones. They
return the elements of all groups as if they all
belonged to the same group with the caveat that it
lists as many
MASTER_SITE_BACKUP and
MASTER_SITE_OVERRIDE as there
are groups defined within either
DISTFILES or
PATCHFILES; respectively for
master-sites-all and
patch-sites-all.DIST_SUBDIRDo not let your port clutter
/usr/ports/distfiles. 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 DIST_SUBDIR
to the name of the port (${PORTNAME} or
${PKGNAMEPREFIX}${PORTNAME}
should work fine). This will change
DISTDIR from the default
/usr/ports/distfiles to
/usr/ports/distfiles/DIST_SUBDIR,
and in effect puts everything that is required for your port into
that subdirectory.It will also look at the subdirectory with the same name on the
backup master site at ftp.FreeBSD.org.
(Setting DISTDIR explicitly in your
Makefile will not accomplish this, so please use
DIST_SUBDIR.)This does not affect the MASTER_SITES you
define in your Makefile.MAINTAINERSet your mail-address here. Please. :-)Note that only a single address without the comment part is
allowed as a MAINTAINER value.
The format used should be user@hostname.domain.
Please do not include any descriptive text such as your real
name in this entry—that merely confuses
bsd.port.mk. Instead, put that information
into your pkg-descr.For a detailed description of the responsibilities of maintainers,
refer to the MAINTAINER on
Makefiles section.If the maintainer of a port does not respond to an update
request from a user after two weeks (excluding major public
holidays), then that is considered a maintainer timeout, and the
update may be made without explicit maintainer approval. If the
maintainer does not respond within three months, then that
maintainer is considered absent without leave, and can be
replaced as the maintainer of the particular port in question.
Exceptions to this are anything maintained by the &a.portmgr;, or
the &a.security-officer;. No unauthorized commits may ever be
made to ports maintained by those groups.The &a.portmgr; reserves the right to revoke or override
anyone's maintainership for any reason, and the &a.security-officer;
reserves the right to revoke or override maintainership for security
reasons.COMMENTThis is a one-line description of the port.
Please do not include the package name (or
version number of the software) in the comment. The comment
should begin with a capital and end without a period. Here
is an example:COMMENT= A cat chasing a mouse all over the screenThe COMMENT variable should immediately follow the MAINTAINER
variable in the Makefile.Please try to keep the COMMENT line less than 70
characters, as it is displayed to users as a one-line
summary of the port.DependenciesMany ports depend on other ports. There are seven variables that
you can use to ensure that all the required bits will be on the
user's machine. There are also some pre-supported dependency
variables for common cases, plus a few more to control the behavior
of dependencies.LIB_DEPENDSThis variable specifies the shared libraries this port depends
on. It is a list of
lib:dir:target
tuples where lib is the name of the
shared library, dir is the
directory in which to find it in case it is not available, and
target is the target to call in that
directory. For example,
LIB_DEPENDS= jpeg.9:${PORTSDIR}/graphics/jpeg:install
will check for a shared jpeg library with major version 9, and
descend into the graphics/jpeg subdirectory
of your ports tree to build and install it if it is not found.
The target part can be omitted if it is
equal to DEPENDS_TARGET (which defaults to
install).The lib part is a regular
expression which is being looked up in the
ldconfig -r output. Values such as
intl.[5-7] and intl are
allowed. The first pattern,
intl.[5-7], will match any of:
intl.5, intl.6 or
intl.7. The second pattern,
intl, will match any version of the
intl library.The dependency is checked twice, once from within the
extract target and then from within the
install target. Also, the name of the
dependency is put into the package so that
&man.pkg.add.1; will automatically install it if it is
not on the user's system.RUN_DEPENDSThis variable specifies executables or files this port depends
on during run-time. It is a list of
path:dir:target
tuples where path is the name of the
executable or file, dir is the
directory in which to find it in case it is not available, and
target is the target to call in that
directory. If path starts with a slash
(/), it is treated as a file and its existence
is tested with test -e; otherwise, it is
assumed to be an executable, and which -s is
used to determine if the program exists in the search path.For example,RUN_DEPENDS= ${LOCALBASE}/etc/innd:${PORTSDIR}/news/inn \
wish8.0:${PORTSDIR}/x11-toolkits/tk80will check if the file or directory
/usr/local/etc/innd exists, and build and
install it from the news/inn subdirectory of
the ports tree if it is not found. It will also see if an
executable called wish8.0 is in the search
path, and descend into the x11-toolkits/tk80
subdirectory of your ports tree to build and install it if it is
not found.In this case, innd is actually an
executable; if an executable is in a place that is not expected
to be in the search path, you should use the full
pathname.The official search PATH used on the ports
build cluster is/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/X11R6/binThe dependency is checked from within the
install target. Also, the name of the
dependency is put into the package so that
&man.pkg.add.1; will automatically install it if it is
not on the user's system. The target
part can be omitted if it is the same as
DEPENDS_TARGET.BUILD_DEPENDSThis variable specifies executables or files this port
requires to build. Like RUN_DEPENDS, it is a
list of
path:dir:target
tuples. For example, BUILD_DEPENDS=
unzip:${PORTSDIR}/archivers/unzip will check
for an executable called unzip, and descend
into the archivers/unzip subdirectory of your
ports tree to build and install it if it is not found.build here means everything from extraction to
compilation. The dependency is checked from within the
extract target. The
target part can be omitted if it is
the same as DEPENDS_TARGETFETCH_DEPENDSThis variable specifies executables or files this port
requires to fetch. Like the previous two, it is a list of
path:dir:target
tuples. For example, FETCH_DEPENDS=
ncftp2:${PORTSDIR}/net/ncftp2 will check for an
executable called ncftp2, and descend into the
net/ncftp2 subdirectory of your ports tree to
build and install it if it is not found.The dependency is checked from within the
fetch target. The
target part can be omitted if it is the
same as DEPENDS_TARGET.EXTRACT_DEPENDSThis variable specifies executables or files this port
requires for extraction. Like the previous, it is a list of
path:dir:target
tuples. For example, EXTRACT_DEPENDS=
unzip:${PORTSDIR}/archivers/unzip will check
for an executable called unzip, and descend
into the archivers/unzip subdirectory of
your ports tree to build and install it if it is not found.The dependency is checked from within the
extract target. The
target part can be omitted if it is the
same as DEPENDS_TARGET.Use this variable only if the extraction does not already
work (the default assumes gzip) and cannot
be made to work using USE_ZIP or
USE_BZIP2 described in .PATCH_DEPENDSThis variable specifies executables or files this port
requires to patch. Like the previous, it is a list of
path:dir:target
tuples. For example, PATCH_DEPENDS=
${NONEXISTENT}:${PORTSDIR}/java/jfc:extract
will descend into the
java/jfc subdirectory of your ports tree to
build and install it if it is not found.The dependency is checked from within the
patch target. The
target part can be omitted if it is the
same as DEPENDS_TARGET.DEPENDSIf there is a dependency that does not fall into either of the
above categories, or your port requires having the source of
the other port extracted in addition to having it installed,
then use this variable. This is a list of
dir:target,
as there is nothing to check, unlike the previous four. The
target part can be omitted if it is the
same as DEPENDS_TARGET.USE_*A number of variables exist in order to encapsulate common
dependencies that many ports have. Although their use is
optional, they can help to reduce the verbosity of the port
Makefiles. Each of them is styled
as USE_*. The
usage of these variables is restricted to the port
Makefiles and
ports/Mk/bsd.*.mk and is not designed
to encapsulate user-settable options — use
WITH_* and
WITHOUT_*
for that purpose.It is always incorrect to set
any USE_*
in /etc/make.conf. For instance,
setting USE_GCC=3.2
would adds a dependency on gcc32 for every port,
including gcc32 itself!
The USE_*
variablesVariableMeansUSE_BZIP2The port's tarballs are compressed with
bzip2.USE_ZIPThe port's tarballs are compressed with
zip.USE_GMAKEThe port requires gmake to
build.USE_PERL5The port requires perl 5 to build and install. See
for additional variables that
can be set relating to perl.USE_X_PREFIXThe port installs in to X11BASE
rather than PREFIX. See
for additional variables that
can be set relating to X11.USE_AUTOMAKE_VERThe port uses GNU automake as part
of its build process. See
for additional variables that can be set relating to
automake.USE_AUTOCONF_VERThe port uses GNU autoconf as part
of its build process. See
for additional variables that can be set relating to
autoconf.USE_LIBTOOL_VERThe port uses GNU libtool as part of
its build process. See for
additional variables that can be set relating to
libtool.GMAKEThe full path for gmake if it is not
in the PATH.USE_BISONThe port uses bison for
building.USE_SDLThe port uses SDL for
building and running. See on how to use
USE_SDL.USE_GCCThe port requires a specific version of
gcc to build. The exact version can be
specified with value such as 3.2.
The minimal required version can be specified as
3.2+. The gcc from
the base system is used when it satisfies the requested
version, otherwise an appropriate gcc is
compiled from ports and the CC and
CXX variables are adjusted.
USE_GCC can't be used together with
USE_LIBTOOL_VER.NO_INSTALL_MANPAGESDo not use the install.man
target.
Define USE_XLIB=yes if your port requires
the X Window System to be installed (it is implied by
USE_IMAKE). Define
USE_GMAKE=yes if your port requires GNU
make instead of BSD make.
Define USE_AUTOCONF_VER=213 if your port requires
GNU autoconf to be run. Define USE_QT_VER=3 if
your port uses the latest Qt toolkit. Use
USE_PERL5=yes if your port requires version 5
of the perl language. (The last is especially important since
some versions of FreeBSD have perl5 as part of the base system
while others do not.)Notes on dependenciesAs mentioned above, the default target to call when a
dependency is required is DEPENDS_TARGET.
It defaults to install. This is a user
variable; it is never defined in a port's
Makefile. If your port needs a special way
to handle a dependency, use the :target part of
the *_DEPENDS variables instead of redefining
DEPENDS_TARGET.When you type make clean, its dependencies
are automatically cleaned too. If you do not wish this to happen,
define the variable NOCLEANDEPENDS in your
environment. This may be particularly desirable if the port
has something that takes a long time to rebuild in its
dependency list, such as KDE, GNOME or Mozilla.To depend on another port unconditionally, use the
variable ${NONEXISTENT} as the first field
of BUILD_DEPENDS or
RUN_DEPENDS. Use this only when you need to
get the source of the other port. You can often save
compilation time by specifying the target too. For
instance
BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract
will always descend to the jpeg port and extract it.Do not use DEPENDS unless there is no other
way the behavior you want can be accomplished. It will cause the
other port to always be built (and installed, by default), and the
dependency will go into the packages as well. If this is really
what you need, you should probably write it as
BUILD_DEPENDS and
RUN_DEPENDS instead—at least the
intention will be clear.Circular dependencies are fatalDo not introduce any circular dependencies into the
ports tree!The ports building technology does not tolerate
circular dependencies. If you introduce one, you will have
someone, somewhere in the world, whose FreeBSD installation will
break almost immediately, with many others quickly to follow.
These can really be hard to detect; if in doubt, before
you make that change, make sure you have done the following:
cd /usr/ports; make index. That process
can be quite slow on older machines, but you may be able to
save a large number of people—including yourself—
a lot of grief in the process.Makefile OptionsSome large applications can be built in a number of
configurations, adding functionality if one of a number of
libraries or applications is available. Examples include
choice of natural (human) language, GUI versus command-line,
or type of database to support. Since not all users
want those libraries or applications, the ports system
provides hooks that the port author can use to control which
configuration should be built. Supporting these properly will
make users happy, and effectively provide 2 or more ports for the
price of one.WITH_* and
WITHOUT_*These variables are designed to be set by the system
administrator. There are many that are standardized in
ports/Mk/bsd.*.mk; others are not,
which can be confusing. If you need to add such a
configuration variable, please consider using one of the
ones from the following list.You should not assume that a
WITH_*
necessarily has a corresponding
WITHOUT_*
variable and vice versa. In general, the default is
simply assumed.Unless otherwise specified, these variables are only
tested for being set or not set, rather than being set to
some kind of variable such as YES or
NO.
The WITH_*
and WITHOUT_*
variablesVariableMeansWITH_APACHE2If set, use
www/apache2
instead of the default of
www/apache.WITH_BERKELEY_DBDefine this variable to specify the ability to
use a variant of the Berkeley database package such as
databases/db41.
An associated variable,
WITH_BDB_VER, may be
set to values such as 2, 3, 4, 41 or 42.WITH_MYSQLDefine this variable to specify the ability to
use a variant of the MySQL database package such as
databases/mysql40-server.
An associated variable,
WANT_MYSQL_VER, may be
set to values such as 323, 40, 41, or 50.WITHOUT_NLSIf set, says that internationalization is not
needed, which can save compile time. By default,
internationalization is used.WITH_OPENSSL_BASEUse the version of OpenSSL in the base system.WITH_OPENSSL_PORTUse the version of OpenSSL from
security/openssh,
overwriting the version that was originally installed
in the base system.WITH_POSTGRESQLDefine this variable to specify the ability to
use a variant of the PostGreSQL database package such as
databases/postgresql72.
WITHOUT_X11If the port can be built both with and without
X support, then it should normally be built with
X support. If this variable is defined, then
the version that does not have X support should
be built instead.
OPTIONSBackgroundThe OPTIONS variable gives the user who
installs the port a dialog with the available options and saves
them to /var/db/ports/portname/options. Next
time when the port has to be rebuild, the options are reused. Never
again you will have to remember all the twenty
WITH_* and
WITHOUT_* options you
used to build this port!SyntaxThe syntax for the OPTIONS variable is:
OPTIONS= OPTION "descriptive text" default ...
The value for default is either ON or
OFF. Multiple repetitions of these three fields
are allowed.When the user runs make config (or runs
make build for the first time), the framework will
check for /var/db/ports/portname
/options.
If that file does not exist, it will use the values of
OPTIONS to create a dialogbox where the options
can be enabled or disabled. Then the options file is saved and the
selected variables will be used when building the port.Use make showconfig to see the saved
configuration. Use make rmconfig to remove the
saved configuration.ExampleSimple use of OPTIONSOPTIONS= FOO "Enable option foo" On \
BAR "Support feature bar" Off
.include <bsd.port.pre.mk>
.if defined(WITHOUT_FOO)
CONFIGURE_ARGS+= --without-foo
.else
CONFIGURE_ARGS+= --with-foo
.endif
.if defined(WITH_BAR)
RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar
.endif
.include <bsd.port.post.mk>Brokennessmake index does not follow
OPTIONS yet (ports/75727)PACKAGE_BUILDING is ignoring
OPTIONS (ports/75727?)Specifying the working directoryEach port is extracted in to a working directory, which must be
writable. The ports system defaults to having the
DISTFILES unpack in to a directory called
${DISTNAME}. In other words, if you have
set:PORTNAME= foo
PORTVERSION= 1.0then the port's distribution files contain a top-level directory,
foo-1.0, and the rest of the files are located
under that directory.There are a number of variables you can override if that is not the
case.WRKSRCThe variable lists the name of the directory that is created when
the application's distfiles are extracted. If our previous example
extracted into a directory called foo (and not
foo-1.0) you would write:WRKSRC= ${WRKDIR}/fooor possiblyWRKSRC= ${WRKDIR}/${PORTNAME}NO_WRKSUBDIRIf the port does not extract in to a subdirectory at all then
you should set NO_WRKSUBDIR to indicate
that.NO_WRKSUBDIR= yesCONFLICTSIf your package cannot coexist with other packages
(because of file conflicts, runtime incompatibility, etc.),
list the other package names in the CONFLICTS
variable. You can use shell globs like * and
? here. Packages names should be
enumerated the same way they appear in
/var/db/pkg. Please make sure that
CONFLICTS does not match this port's
package itself, or else forcing its installation with
FORCE_PKG_REGISTER will no longer work.
CONFLICTS automatically sets
IGNORE, which is more fully documented
in .Building mechanismsIf your package uses GNU make, set
USE_GMAKE=yes. If your package uses
configure, set
HAS_CONFIGURE=yes. If your package uses GNU
configure, set
GNU_CONFIGURE=yes (this implies
HAS_CONFIGURE). If you want to give some extra
arguments to configure (the default argument list
--prefix=${PREFIX} for GNU
configure and empty for non-GNU
configure), set those extra arguments in
CONFIGURE_ARGS. If your package uses GNU
autoconf, set
USE_AUTOCONF_VER=213. This implies
GNU_CONFIGURE, and will cause
autoconf to be run before
configure.If your package uses GNU configure, and
the resulting executable file has a strange name
like
i386-portbld-freebsd4.7-appname,
you will need to additionally override the
CONFIGURE_TARGET variable to specify the
target in the way required by scripts generated by recent
versions of autoconf. Add the following line
immediately after the GNU_CONFIGURE=yes line
in your Makefile:CONFIGURE_TARGET=--build=${MACHINE_ARCH}-portbld-freebsd${OSREL}If your package is an X application that creates
Makefiles from Imakefiles
using imake, then set
USE_IMAKE=yes. This will cause the configure
stage to automatically do an xmkmf -a. If the
flag is a problem for your port, set
XMKMF=xmkmf. If the port uses
imake but does not understand the
install.man target,
NO_INSTALL_MANPAGES=yes should be set. In
addition, the author of the original port should be shot. :->If your port's source Makefile has
something else than all as the main build
target, set ALL_TARGET accordingly. Same goes
for install and
INSTALL_TARGET.Special considerationsThere are some more things you have to take into account when you
create a port. This section explains the most common of those.Shared LibrariesIf your port installs one or more shared libraries, define a
INSTALLS_SHLIB make variable, which will instruct
a bsd.port.mk to run
${LDCONFIG} -m on the directory where the
new library is installed (usually
PREFIX/lib) during
post-install target to register it into the
shared library cache. This variable, when defined, will also
facilitate addition of an appropriate
@exec /sbin/ldconfig -m and
@unexec /sbin/ldconfig -R pair into your
pkg-plist file, so that a user who installed
the package can start using the shared library immediately and
de-installation will not cause the system to still believe the
library is there.If you need, you can override the default location where the new
library is installed by defining the LDCONFIG_DIRS
make variable, which should contain a list of directories into which
shared libraries are to be installed. For example if your port
installs shared libraries into
PREFIX/lib/foo and
PREFIX/lib/bar directories
you could use the following in your
Makefile:INSTALLS_SHLIB= yes
LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/barNote that content of LDCONFIG_DIRS is passed
through &man.sed.1; just like the rest of pkg-plist,
so PLIST_SUB substitutions also apply here. It is
recommended that you use %%PREFIX%% for
PREFIX, %%LOCALBASE%% for
LOCALBASE and %%X11BASE%% for
X11BASE.Ports with distribution restrictionsLicenses vary, and some of them place restrictions on how the
application can be packaged, whether it can be sold for profit, and so
on.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 for violating them by redistributing the
source or compiled binaries either via FTP/HTTP or CD-ROM. If in doubt,
please contact the &a.ports;.In situations like this, the variables described in the following
sections can be set.NO_PACKAGEThis variable indicates that we may not generate a binary
package of the application. For instance, the license may
disallow binary redistribution, or it may prohibit distribution
of packages created from patched sources.However, the port's DISTFILES may be
freely mirrored on FTP/HTTP. They may also be distributed on
a CD-ROM (or similar media) unless NO_CDROM
is set as well.NO_PACKAGE should also be used if the binary
package is not generally useful, and the application should always
be compiled from the source code. For example, if the application
has configuration information that is site specific hard coded in to
it at compile time, set NO_PACKAGE.NO_PACKAGE should be set to a string
describing the reason why the package should not be
generated.NO_CDROMThis variable alone indicates that, although we are allowed
to generate binary packages, we may put neither those packages
nor the port's DISTFILES onto a CD-ROM (or
similar media) for resale. However, the binary packages and
the port's DISTFILES will still be available
via FTP/HTTP. If this variable is set along with
NO_PACKAGE, then only the port's
DISTFILES will be available, and only via
FTP/HTTP.NO_CDROM should be set to a string
describing the reason why the port cannot be redistributed
on CD-ROM. For instance, this should be used if the port's license
is for non-commercial use only.RESTRICTEDSet this variable alone if the application's license permits
neither mirroring the application's DISTFILES
nor distributing the binary package in any way.NO_CDROM or NO_PACKAGE
should not be set along with RESTRICTED
since the latter variable implies the former ones.RESTRICTED should be set to a string
describing the reason why the port cannot be redistributed.
Typically, this indicates that the port contains proprietary
software and that the user will need to manually download the
DISTFILES, possibly after registering for the
software or agreeing to accept the terms of an
EULA.RESTRICTED_FILESWhen RESTRICTED or NO_CDROM
is set, this variable defaults to ${DISTFILES}
${PATCHFILES}, otherwise it is empty. If only some of the
distribution files are restricted, then set this variable to list
them.Note that the port committer should add an entry to
/usr/ports/LEGAL for every listed distribution
file, describing exactly what the restriction entails.Using perl
Variables for ports that use perlVariableMeansUSE_PERL5Says that the port uses perl 5 to build and run.USE_PERL5_BUILDSays that the port uses perl 5 to build.USE_PERL5_RUNSays that the port uses perl 5 to run.PERLThe full path of perl 5, either in the
system or installed from a port, but without the version
number. Use this if you need to replace
#!lines in scripts.PERL_CONFIGUREConfigure using Perl's MakeMaker. It implies
USE_PERL5.PERL_MODBUILDConfigure, build and install using Module::Build. It
implies PERL_CONFIGURE.Read only variablesPERL_VERSIONThe full version of perl installed (e.g.,
5.00503).PERL_VERThe short version of perl installed (e.g.,
5.005).PERL_LEVELThe installed perl version as an integer of the form MNNNPP
(e.g., 500503).PERL_ARCHWhere perl stores architecture dependent libraries.
Defaults to ${ARCH}-freebsd.PERL_PORTName of the perl port that is
installed (e.g., perl5).SITE_PERLDirectory name where site specific
perl packages go.
This value is added to PLIST_SUB.
Using X11
Variables for ports that use XUSE_X_PREFIXThe port installs in X11BASE, not
PREFIX.USE_XLIBThe port uses the X libraries.USE_MOTIFThe port uses the Motif toolkit. Implies
USE_XPM.USE_IMAKEThe port uses imake. Implies
USE_X_PREFIX.XMKMFSet to the path of xmkmf if not in the
PATH. Defaults to xmkmf
-a.
Variables for depending on individual parts of X11X_IMAKE_PORTPort providing imake and several
other utilities used to build X11.X_LIBRARIES_PORTPort providing X11 libraries.X_CLIENTS_PORTPort providing X clients.X_SERVER_PORTPort providing X server.X_FONTSERVER_PORTPort providing font server.X_PRINTSERVER_PORTPort providing print server.X_VFBSERVER_PORTPort providing virtual framebuffer server.X_NESTSERVER_PORTPort providing a nested X server.X_FONTS_ENCODINGS_PORTPort providing encodings for fonts.X_FONTS_MISC_PORTPort providing miscellaneous bitmap fonts.X_FONTS_100DPI_PORTPort providing 100dpi bitmap fonts.X_FONTS_75DPI_PORTPort providing 75dpi bitmap fonts.X_FONTS_CYRILLIC_PORTPort providing cyrillic bitmap fonts.X_FONTS_TTF_PORTPort providing &truetype; fonts.X_FONTS_TYPE1_PORTPort providing Type1 fonts.X_MANUALS_PORTPort providing developer oriented manual pages
Using X11 related variables in port# Use X11 libraries and depend on
# font server as well as cyrillic fonts.
RUN_DEPENDS= ${X11BASE}/bin/xfs:${X_FONTSERVER_PORT} \
${X11BASE}/lib/X11/fonts/cyrillic/crox1c.pcf.gz:${X_FONTS_CYRILLIC_PORT}
USE_XLIB= yesUsing automake, autoconf,
and libtool
Variables for ports that use automake, autoconf or
libtoolVariableMeansAUTOMAKEThe full path for automake if it is
not in the PATH.USE_AUTOMAKE_VERThe port uses automake. Valid values
for this variable are 14 and
15, and sets the
AUTOMAKE_DIR and
ACLOCAL_DIR variables
appropriately.AUTOMAKE_ARGSOne or more command line arguments to pass to
AUTOMAKE if
USE_AUTOMAKE_VER is set.AUTOMAKE_ENVOne or more environment variables to set (and their
values) before running AUTOMAKE.ACLOCALSet to the path of the GNU aclocal if
it is not in the PATH. The default is set
according to the USE_AUTOMAKE_VER
variable.ACLOCAL_DIRSet to the path of the GNU aclocal
shared directory. The default is set according to the
USE_AUTOMAKE_VER variable.AUTOMAKE_DIRSet to the path of the GNU automake
shared directory. The default is set according to the
USE_AUTOMAKE_VER variable.USE_AUTOCONF_VERSpecifies that the port uses autoconf.
Implies GNU_CONFIGURE.
The default value is 213.AUTOCONFSet to the path of GNU autoconf if it
is not in the PATH. The default is set
according to the USE_AUTOCONF_VER
variable.AUTOCONF_ARGSCommand line arguments to pass to
autoconf.AUTOCONF_ENVSet these
variable=value
pairs in the environment before running
autoconf.USE_AUTOHEADER_VERSpecifies that the port uses autoheader.
Implies USE_AUTOCONF_VER.
The default value is 213.AUTOHEADERSet to the path of GNU autoheader if
it is not in the PATH. The default is set
according to USE_AUTOCONF_VER.AUTORECONFSet to the path of GNU autoreconf if
it is not in the PATH. The default is set
according to USE_AUTOCONF_VER.AUTOSCANSet to the path of GNU autoscan if it
is not set in the PATH. The default is set
according to USE_AUTOCONF_VER.AUTOIFNAMESSet to the path of GNU autoifnames if
it is not set in the PATH. The default is set
according to USE_AUTOCONF_VER.USE_LIBTOOL_VERThe port uses libtool. Implies
GNU_CONFIGURE.
The default value is 13.LIBTOOLSet to the path of libtool if it is
not set in the PATH.LIBTOOLFILESThe files to patch for libtool.
Defaults to aclocal.m4 if
USE_AUTOCONF is defined,
configure otherwise.LIBTOOLFLAGSAdditional flags to pass to
ltconfig. Defaults to
--disable-ltlibs.
Using GNOMEThe FreeBSD/GNOME project uses its own set of variables
to define which GNOME components a
particular port uses. A
comprehensive
list of these variables exists within the FreeBSD/GNOME
project's homepage.Your port does not need to depend on GNOME if it merely installs
pkg-config metadata files to
PREFIX/libdata/pkgconfig.
As usual, your port should be prepared to clean up after itself
and remove that directory if it becomes empty.
Assuming that your port installs a file named
gtkmumble.pc to the said location, just add
the following lines to pkg-plist:libdata/pkgconfig/gtkmumble.pc
@unexec rmdir %B 2>/dev/null || trueThe latter line must appear immediately after the former one
so that %B expands correctly. Please refer
to &man.pkg.create.1; for a detailed description of the syntax
used in pkg-plist.Using KDE
Variables for ports that use KDEUSE_QT_VERThe port uses the Qt toolkit. Possible values are
1 and
3; each specify the major version
of Qt to use. Sets both MOC and
QTCPPFLAGSto default appropriate
values.USE_KDELIBS_VERThe port uses KDE libraries. Possible values are
3; each specify the major version
of KDE to use. Implies USE_QT_VER
of the appropriate version.USE_KDEBASE_VERThe port uses KDE base. Possible values are
3; each specify the major version
of KDE to use. Implies USE_KDELIBS_VER
of the appropriate version.MOCSet to the path of moc.
Default set according to USE_QT_VER
value.QTCPPFLAGSSet the CPPFLAGS to use when
processing Qt code. Default set according to
USE_QT_VER value.
Using JavaVariable definitionsIf your port needs a Java™ Development Kit (JDK) to
either build, run or even extract the distfile, then it should
define USE_JAVA.There are several JDKs in the ports collection, from various
vendors, and in several versions. If your port must use one of
these versions, you can define which one. The most current
version is java/jdk14.
Variables that may be set by ports that use JavaVariableMeansUSE_JAVAShould be defined for the remaining variables to have any
effect.JAVA_VERSIONList of space-separated suitable Java versions for
the port. An optional "+" allows you to
specify a range of versions (allowed values:
1.1[+] 1.2[+] 1.3[+] 1.4[+]).JAVA_OSList of space-separated suitable JDK port operating
systems for the port (allowed values: native
linux).JAVA_VENDORList of space-separated suitable JDK port vendors for
the port (allowed values: freebsd bsdjava sun ibm
blackdown).JAVA_BUILDWhen set, it means that the selected JDK port should
be added to the build dependencies of the port.JAVA_RUNWhen set, it means that the selected JDK port should
be added to the run dependencies of the port.JAVA_EXTRACTWhen set, it means that the selected JDK port should
be added to the extract dependencies of the port.USE_JIKESWhether the port should or should not use the
jikes bytecode compiler to build. When
no value is set for this variable, the port will use
jikes to build if available. You may
also explicitly forbid or enforce the use of
jikes (by setting 'no'
or 'yes'). In the later case, devel/jikes will be added to build
dependencies of the port. In any case that jikes
is actually used in place of javac, then the
HAVE_JIKES variable is defined by
bsd.java.mk.
Below is the list of all settings a port will receive after
setting USE_JAVA:
Variables provided to ports that use JavaVariableValueJAVA_PORTThe name of the JDK port (e.g.
'java/jdk14').JAVA_PORT_VERSIONThe full version of the JDK port (e.g.
'1.4.2'). If you only need the first
two digits of this version number, use
${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}.JAVA_PORT_OSThe operating system used by the JDK port (e.g.
'linux').JAVA_PORT_VENDORThe vendor of the JDK port (e.g.
'sun').JAVA_PORT_OS_DESCRIPTIONDescription of the operating system used by the JDK port
(e.g. 'Linux').JAVA_PORT_VENDOR_DESCRIPTIONDescription of the vendor of the JDK port (e.g.
'FreeBSD Foundation').JAVA_HOMEPath to the installation directory of the JDK (e.g.
'/usr/local/jdk1.3.1').JAVACPath to the Java compiler to use (e.g.
'/usr/local/jdk1.1.8/bin/javac' or
'/usr/local/bin/jikes').JARPath to the jar tool to use (e.g.
'/usr/local/jdk1.2.2/bin/jar' or
'/usr/local/bin/fastjar').APPLETVIEWERPath to the appletviewer utility (e.g.
'/usr/local/linux-jdk1.2.2/bin/appletviewer').JAVAPath to the java executable. Use
this for executing Java programs (e.g.
'/usr/local/jdk1.3.1/bin/java').JAVADOCPath to the javadoc utility
program.JAVAHPath to the javah program.JAVAPPath to the javap program.JAVA_KEYTOOLPath to the keytool utility program.
This variable is available only if the JDK is Java 1.2 or
higher.JAVA_N2APath to the native2ascii tool.JAVA_POLICYTOOLPath to the policytool program.
This variable is available only if the JDK is Java 1.2 or
higher.JAVA_SERIALVERPath to the serialver utility
program.RMICPath to the RMI stub/skeleton generator,
rmic.RMIREGISTRYPath to the RMI registry program,
rmiregistry.RMIDPath to the RMI daemon program rmid.
This variable is only available if the JDK is Java 1.2
or higher.JAVA_CLASSESPath to the archive that contains the JDK class
files. On JDK 1.2 or later, this is
${JAVA_HOME}/jre/lib/rt.jar. Earlier
JDKs used
${JAVA_HOME}/lib/classes.zip.HAVE_JIKESDefined whenever jikes is used by
the port (see USE_JIKES above).
You may use the java-debug make target
to get information for debugging your port. It will display the
value of many of the forecited variables.Additionally, the following constants are defined so all
Java ports may be installed in a consistent way:
Constants defined for ports that use JavaConstantValueJAVASHAREDIRThe base directory for everything related to Java.
Default: ${PREFIX}/share/java.
JAVAJARDIRThe directory where JAR files should be installed.
Default:
${JAVASHAREDIR}/classes.JAVALIBDIRThe directory where JAR files installed by other
ports are located. Default:
${LOCALBASE}/share/java/classes.
The related entries are defined in both
PLIST_SUB (documented in
) and
SUB_LIST.Building with AntWhen the port is to be built using Apache Ant, it has to
define USE_ANT. Ant is thus considered to be
the sub-make command. When no do-build target
is defined by the port, a default one will be set that simply
runs Ant according to MAKE_ENV,
MAKE_ARGS and ALL_TARGETS.
This is similar to the USE_GMAKE mechanism,
which is documented in .If jikes is used in place of
javac (see USE_JIKES in
), then Ant will automatically
use it to build the port.Best practicesWhen porting a Java library, your port should install the
JAR file(s) in ${JAVAJARDIR}, and everything
else under ${JAVASHAREDIR}/${PORTNAME}
(except for the documentation, see below). In order to reduce
the packing file size, you may reference the JAR file(s) directly
in the Makefile. Just use the following
statement (where myport.jar is the name
of the JAR file installed as part of the port):PLIST_FILES+= %%JAVAJARDIR%%/myport.jarWhen porting a Java application, the port usually installs
everything under a single directory (including its JAR
dependencies). The use of
${JAVASHAREDIR}/${PORTNAME} is strongly
encouraged in this regard. It is up the porter to decide
whether the port should install the additional JAR dependencies
under this directory or directly use the already installed ones
(from ${JAVAJARDIR}).Regardless of the type of your port (library or application),
the additional documentation should be installed in the
same location as for
any other port. The JavaDoc tool is known to produce a
different set of files depending on the version of the JDK that
is used. For ports that do not enforce the use of a particular
JDK, it is therefore a complex task to specify the packing list
(pkg-plist). This is one reason why
porters are strongly encouraged to use the
PORTDOCS macro. Moreover, even if you can
predict the set of files that will be generated by
javadoc, the size of the resulting
pkg-plist advocates for the use of
PORTDOCS.The default value for DATADIR is
${PREFIX}/share/${PORTNAME}. It is a good
idea to override DATADIR to
${JAVASHAREDIR}/${PORTNAME} for Java ports.
Indeed, DATADIR is automatically added to
PLIST_SUB (documented in ) so you may use
%%DATADIR%% directly in
pkg-plist.As for the choice of building Java ports from source or
directly installing them from a binary distribution, there is
no defined policy at the time of writing. However, people from
the &os; Java Project
encourage porters to have their ports built from source whenever
it is a trivial task.All the features that have been presented in this section
are implemented in bsd.java.mk. If you
ever think that your port needs more sophisticated Java support,
please first have a look at the
bsd.java.mk CVS log as it usually takes some time to
document the latest features. Then, if you think the support
you are lacking would be beneficial to many other Java ports,
feel free to discuss it on the &a.java;.Although there is a java category for
PRs, it refers to the JDK porting effort from the &os; Java
project. Therefore, you should submit your Java port in the
ports category as for any other port, unless
the issue you are trying to resolve is related to either a JDK
implementation or bsd.java.mk.Similarly, there is a defined policy regarding the
CATEGORIES of a Java port, which is detailed
in .Using Apache and PHPApache
Variables for ports that use ApacheUSE_APACHEThe port requires Apache.WITH_APACHE2The port requires Apache 2.0. Without this variable,
the port will depend on Apache 1.3.APXSFull path to the apxs binary
(read-only variable).
PHP
Variables for ports that use PHPUSE_PHPThe port requires PHP. The value yes
adds a dependency on PHP. The list of required PHP extensions
can be specified instead. Example: pcre xml
gettextDEFAULT_PHP_VERSelects which major version of PHP will be installed as
a dependency when no PHP is installed yet. Default is
4. Possible values: 4,
5BROKEN_WITH_PHPThe port does not work with PHP of the given version.
Possible values: 4,
5USE_PHPIZEThe port will be built as a PHP extension.USE_PHPEXTThe port will be treated as a PHP extension, including
installation and registration in the extension registry.USE_PHP_BUILDSet PHP as a build dependency.WANT_PHP_CLIWant the CLI (command line) version of PHP.WANT_PHP_CGIWant the CGI version of PHP.WANT_PHP_MODWant the Apache module version of PHP.WANT_PHP_SCRWant the CLI or the CGI version of PHP.WANT_PHP_WEBWant the Apache module or the CGI version of PHP.WANT_PHP_PEARWant the PEAR framework.
PEAR modulesPorting PEAR modules is a very simple process.Use the variables FILES,
TESTS, DATA,
SQLS, SCRIPTFILES,
DOCS and EXAMPLES to list the
files you want to install. All listed files will be automatically
installed into the appropriate locations and added to
pkg-plist.Include
${PORTSDIR}/devel/pear-PEAR/Makefile.common
on the last line of the Makefile.Example Makefile for PEAR classPORTNAME= Date
PORTVERSION= 1.4.3
CATEGORIES= devel www pear
MAINTAINER= example@domain.com
COMMENT= PEAR Date and Time Zone Classes
BUILD_DEPENDS= ${PEARDIR}/PEAR.php:${PORTSDIR}/devel/pear-PEAR
RUN_DEPENDS= ${BUILD_DEPENDS}
FILES= Date.php Date/Calc.php Date/Human.php Date/Span.php \
Date/TimeZone.php
TESTS= test_calc.php test_date_methods_span.php testunit.php \
testunit_date.php testunit_date_span.php wknotest.txt \
bug674.php bug727_1.php bug727_2.php bug727_3.php \
bug727_4.php bug967.php weeksinmonth_4_monday.txt \
weeksinmonth_4_sunday.txt weeksinmonth_rdm_monday.txt \
weeksinmonth_rdm_sunday.txt
DOCS= TODO
_DOCSDIR= .
.include <bsd.port.pre.mk>
.include "${PORTSDIR}/devel/pear-PEAR/Makefile.common"
.include <bsd.port.post.mk>Using Python
Most useful variables for ports that use PythonUSE_PYTHONThe port needs Python. Minimal required version can be
specified with values such as 2.3+.USE_PYDISTUTILSUse Python distutils for configuring, compiling and
installing. This is required when the port comes with
setup.py.PYTHON_PKGNAMEPREFIXUsed as a PKGNAMEPREFIX to distinguish
packages for different Python versions.
Example: py24-PYTHON_SITELIBDIRLocation of the site-packages tree. Useful when installing
Python modules. Always use
%%PYTHON_SITELIBDIR%% in
pkg-plist when possible. Default value:
lib/python2.4/site-packagesPYNUMERICAdd dependency on numeric extension.PYXMLAdd dependency on XML extension.USE_TWISTEDAdd dependency on twistedCore. The list of required
components can be specified as a value of this
variable. Example: web lore pair
flowUSE_ZOPEAdd dependency on Zope, a web application platform.
Change Python dependency to Python 2.3. Set
ZOPEBASEDIR containing a directory with
Zope installation.
A complete list of available variables can be found in
/usr/ports/Mk/bsd.python.mk.Using EmacsThis section is yet to be written.Using Ruby
Useful variables for ports that use RubyVariableDescriptionUSE_RUBYThe port requires Ruby.USE_RUBY_EXTCONFThe port uses extconf.rb to
configure.USE_RUBY_SETUPThe port uses setup.rb to
configure.RUBY_SETUPSet to the alternative name of
setup.rb. Common value is
install.rb.
The following table shows the selected variables available to port
authors via the ports infrastructure. These variables should be used
to install files into their proper locations. Use them in
pkg-plist as much as possible. These variables
should not be redefined in the port.
Selected read-only variables for ports that use RubyVariableDescriptionExample valueRUBY_PKGNAMEPREFIXUsed as a PKGNAMEPREFIX to distinguish
packages for different Ruby versions.ruby18-RUBY_VERSIONFull version of Ruby in the form of
x.y.z.1.8.2RUBY_SITELIBDIRArchitecture independent libraries installation
path./usr/local/lib/ruby/site_ruby/1.8RUBY_SITEARCHILIBDIRArchitecture dependent libraries installation
path./usr/local/lib/ruby/site_ruby/1.8/amd64-freebsd6RUBY_MODDOCDIRModule documentation installation path./usr/local/share/doc/ruby18/patsyRUBY_MODEXAMPLESDIRModule examples installation path./usr/local/share/examples/ruby18/patsy
A complete list of available variables can be found in
/usr/ports/Mk/bsd.ruby.mk.Using SDLThe USE_SDL variable is used to autoconfigure
the dependencies for ports which use an SDL based library like
devel/sdl12 and
x11-toolkits/sdl_gui.The following SDL libraries are recognized at the moment:sdl: devel/sdl12gfx: graphics/sdl_gfxgui: x11-toolkits/sdl_guiimage: graphics/sdl_imageldbad: devel/sdl_ldbadmixer: audio/sdl_mixermm: devel/sdlmmnet: net/sdl_netsound: audio/sdl_soundttf: graphics/sdl_ttfTherefore, if a port has a dependency on
net/sdl_net and
audio/sdl_mixer,
the syntax will be:USE_SDL= net mixerThe dependency devel/sdl12,
which is required by net/sdl_net and
audio/sdl_mixer, is automatically
added as well.If you use USE_SDL, it will automatically:Add a dependency on sdl12-config to
BUILD_DEPENDSAdd the variable SDL_CONFIG to
CONFIGURE_ENVAdd the dependencies of the selected libraries to the
LIB_DEPENDSTo check whether an SDL library is available, you can do it
with the WANT_SDL variable:WANT_SDL=yes
.include <bsd.port.pre.mk>
.if ${HAVE_SDL:Mmixer}!=""
USE_SDL+= mixer
.endif
.include <bsd.port.post.mk>MASTERDIRIf your port needs to build slightly different versions of
packages by having a variable (for instance, resolution, or paper
size) take different values, create one subdirectory per package to
make it easier for users to see what to do, but try to share as many
files as possible between ports. Typically you only need a very short
Makefile in all but one of the directories if you
use variables cleverly. In the sole Makefile,
you can use MASTERDIR to specify the directory
where the rest of the files are. Also, use a variable as part of
PKGNAMESUFFIX so
the packages will have different names.This will be best demonstrated by an example. This is part of
japanese/xdvi300/Makefile;PORTNAME= xdvi
PORTVERSION= 17
PKGNAMEPREFIX= ja-
PKGNAMESUFFIX= ${RESOLUTION}
:
# default
RESOLUTION?= 300
.if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \
${RESOLUTION} != 300 && ${RESOLUTION} != 400
@${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\""
@${ECHO} "Possible values are: 118, 240, 300 (default) and 400."
@${FALSE}
.endifjapanese/xdvi300 also has all the regular
patches, package files, etc. If you type make
there, it will take the default value for the resolution (300) and
build the port normally.As for other resolutions, this is the entirexdvi118/Makefile:RESOLUTION= 118
MASTERDIR= ${.CURDIR}/../xdvi300
.include "${MASTERDIR}/Makefile"(xdvi240/Makefile and
xdvi400/Makefile are similar). The
MASTERDIR definition tells
bsd.port.mk that the regular set of
subdirectories like FILESDIR and
SCRIPTDIR are to be found under
xdvi300. The RESOLUTION=118
line will override the RESOLUTION=300 line in
xdvi300/Makefile and the port will be built with
resolution set to 118.Shared library versionsPlease read our policy on
shared library versioning to understand what to do with
shared library versions in general. Do not blindly assume software
authors know what they are doing; many of them do not. It is very
important that these details are carefully considered, as we have
quite a unique situation where we are trying to have dozens of
potentially incompatible software pairs co-exist. Careless port
imports have caused great trouble regarding shared libraries in the
past (ever wondered why the port jpeg-6b has a
shared library version of 9?). If in doubt, send a message to the
&a.ports;. Most of the time, your job ends by determining the right
shared library version and making appropriate patches to implement
it.ManpagesThe MAN[1-9LN] variables will automatically add
any manpages to pkg-plist (this means you must
not list manpages in the
pkg-plist—see generating PLIST for more). It also
makes the install stage automatically compress or uncompress manpages
depending on the setting of NOMANCOMPRESS in
/etc/make.conf.If your port tries to install multiple names for manpages using
symlinks or hardlinks, you must use the MLINKS
variable to identify these. The link installed by your port will
be destroyed and recreated by bsd.port.mk
to make sure it points to the correct file. Any manpages
listed in MLINKS must not be listed in the
pkg-plist.To specify whether the manpages are compressed upon installation,
use the MANCOMPRESSED variable. This variable can
take three values, yes, no and
maybe. yes means manpages are
already installed compressed, no means they are
not, and maybe means the software already respects
the value of NOMANCOMPRESS so
bsd.port.mk does not have to do anything
special.MANCOMPRESSED is automatically set to
yes if USE_IMAKE is set and
NO_INSTALL_MANPAGES is not set, and to
no otherwise. You do not have to explicitly define
it unless the default is not suitable for your port.If your port anchors its man tree somewhere other than
PREFIX, you can use the
MANPREFIX to set it. Also, if only manpages in
certain sections go in a non-standard place, such as some perl modules
ports, you can set individual man paths using
MANsectPREFIX (where
sect is one of 1-9,
L or N).If your manpages go to language-specific subdirectories, set the
name of the languages to MANLANG. The value of
this variable defaults to "" (i.e., English
only).Here is an example that puts it all together.MAN1= foo.1
MAN3= bar.3
MAN4= baz.4
MLINKS= foo.1 alt-name.8
MANLANG= "" ja
MAN3PREFIX= ${PREFIX}/share/foobar
MANCOMPRESSED= yesThis states that six files are installed by this port;${PREFIX}/man/man1/foo.1.gz
${PREFIX}/man/ja/man1/foo.1.gz
${PREFIX}/share/foobar/man/man3/bar.3.gz
${PREFIX}/share/foobar/man/ja/man3/bar.3.gz
${PREFIX}/man/man4/baz.4.gz
${PREFIX}/man/ja/man4/baz.4.gzAdditionally ${PREFIX}/man/man8/alt-name.8.gz
may or may not be installed by your port. Regardless, a
symlink will be made to join the foo(1) manpage and
alt-name(8) manpage.Ports that require MotifThere are many programs that require a Motif library (available
from several commercial vendors, while there is a free clone reported
to be able to run many applications in
x11-toolkits/lesstif) 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 (for people who are compiling from
the port) or statically (for people who distribute packages).USE_MOTIFIf your port requires Motif, define this variable in the
Makefile. This will prevent people who do not own a copy of Motif
from even attempting to build it.MOTIFLIBThis variable will be set by bsd.port.mk to
be the appropriate reference to the Motif library. Please patch the
source of your port to reference this wherever the Motif library is referenced in the
Makefile or
Imakefile.There are two common cases:If the port refers to the Motif library as
-lXm in its Makefile or
Imakefile, simply substitute
${MOTIFLIB} for it.If the port uses XmClientLibs in its
Imakefile, change it to
${MOTIFLIB} ${XTOOLLIB}
${XLIB}.Note that MOTIFLIB (usually) expands to
-L/usr/X11R6/lib -lXm or
/usr/X11R6/lib/libXm.a, so there is no need to
add -L or -l in front.X11 fontsIf your port installs fonts for the X Window System, put them in
X11BASE/lib/X11/fonts/local.
This directory was new to XFree86 3.3.3. If it does not exist,
please create it, and print out a message urging the user to update
their XFree86 to 3.3.3 or newer, or at least add this directory to the
font path in /etc/XF86Config.Info filesIf your package needs to install GNU info files, they should be
listed in the INFO variable (without the trailing
.info), and appropriate installation/de-installation
code will be automatically added to the temporary
pkg-plist before package registration.The pkg-* filesThere are some tricks we have not mentioned yet about the
pkg-* files
that come in handy sometimes.pkg-messageIf you need to display a message to the installer, you may place
the message in pkg-message. This capability is
often useful to display additional installation steps to be taken
after a &man.pkg.add.1; or to display licensing
information.The pkg-message file does not need to be
added to pkg-plist. Also, it will not get
automatically printed if the user is using the port, not the
package, so you should probably display it from the
post-install target yourself.pkg-installIf your port needs to execute commands when the binary package
is installed with &man.pkg.add.1; you can do this via the
pkg-install script. This script will
automatically be added to the package, and will be run twice by
&man.pkg.add.1;: the first time as
${SH} pkg-install ${PKGNAME}
PRE-INSTALL and the second time as
${SH} pkg-install ${PKGNAME} POST-INSTALL.
$2 can be tested to determine which mode
the script is being run in. The PKG_PREFIX
environmental variable will be set to the package installation
directory. See &man.pkg.add.1; for
additional information.This script is not run automatically if you install the port
with make install. If you are depending on it
being run, you will have to explicitly call it from your port's
Makefile, with a line like
PKG_PREFIX=${PREFIX} ${SH} ${PKGINSTALL}
${PKGNAME} PRE-INSTALL.pkg-deinstallThis script executes when a package is removed.
This script will be run twice by &man.pkg.delete.1;.
The first time as ${SH} pkg-deinstall ${PKGNAME}
DEINSTALL and the second time as
${SH} pkg-deinstall ${PKGNAME} POST-DEINSTALL.
pkg-reqIf your port needs to determine if it should install or not, you
can create a pkg-reqrequirements
script. It will be invoked automatically at
installation/de-installation time to determine whether or not
installation/de-installation should proceed.The script will be run at installation time by
&man.pkg.add.1; as
pkg-req ${PKGNAME} INSTALL.
At de-installation time it will be run by
&man.pkg.delete.1; as
pkg-req ${PKGNAME} DEINSTALL.Changing pkg-plist based on make
variablesSome ports, particularly the p5- ports,
need to change their pkg-plist depending on
what options they are configured with (or version of
perl, in the case of p5-
ports). To make this easy, any instances in the
pkg-plist of %%OSREL%%,
%%PERL_VER%%, and
%%PERL_VERSION%% will be substituted for
appropriately. The value of %%OSREL%% is the
numeric revision of the operating system (e.g.,
4.9). %%PERL_VERSION%% is
the full version number of perl (e.g.,
5.00502) and %%PERL_VER%%
is the perl version number minus
the patchlevel (e.g., 5.005). Several other
%%VARS%% related to
port's documentation files are described in the relevant section.If you need to make other substitutions, you can set the
PLIST_SUB variable with a list of
VAR=VALUE
pairs and instances of
%%VAR%% will be
substituted with VALUE in the
pkg-plist.For instance, if you have a port that installs many files in a
version-specific subdirectory, you can put something likeOCTAVE_VERSION= 2.0.13
PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}in the Makefile and use
%%OCTAVE_VERSION%% wherever the version shows up
in pkg-plist. That way, when you upgrade the port,
you will not have to change dozens (or in some cases, hundreds) of
lines in the pkg-plist.This substitution (as well as addition of any manual pages) will be done between
the pre-install and
do-install targets, by reading from
PLIST and writing to
TMPPLIST
(default:
WRKDIR/.PLIST.mktmp). So if
your port builds PLIST
on the fly, do so in or
before pre-install. Also, if your port
needs to edit the resulting file, do so in
post-install to a file named
TMPPLIST.Another possibility to modify port's packing list is based
on setting the variables PLIST_FILES and
PLIST_DIRS. The value of each variable
is regarded as a list of pathnames to
write to TMPPLIST
along with PLIST
contents. Names listed in PLIST_FILES
and PLIST_DIRS are subject to
%%VAR%%
substitution, as described above.
Except for that, names from PLIST_FILES
will appear in the final packing list unchanged,
while @dirrm will be
prepended to names from PLIST_DIRS.
To take effect, PLIST_FILES and
PLIST_DIRS must be set before
TMPPLIST is written,
i.e. in pre-install or earlier.Changing the names of
pkg-* filesAll the names of pkg-* files
are defined using variables so you can change them in your
Makefile if need be. This is especially useful
when you are sharing the same pkg-* files
among several ports or have to write to one of the above files (see
writing to places other than
WRKDIR for why it is a bad idea to write
directly into the pkg-* subdirectory).Here is a list of variable names and their default
values. (PKGDIR defaults to
${MASTERDIR}.)VariableDefault valueDESCR${PKGDIR}/pkg-descrPLIST${PKGDIR}/pkg-plistPKGINSTALL${PKGDIR}/pkg-installPKGDEINSTALL${PKGDIR}/pkg-deinstallPKGREQ${PKGDIR}/pkg-reqPKGMESSAGE${PKGDIR}/pkg-messagePlease change these variables rather than overriding
PKG_ARGS. If you change
PKG_ARGS, those files will not correctly be
installed in /var/db/pkg upon install from a
port.Making use of SUB_FILES and
SUB_LISTThe SUB_FILES and SUB_LIST
variables are useful for dynamic values in port files, such as the
installation PREFIX in
pkg-message.The SUB_FILES variable specifies a list
of files to be automatically modified. Each
file in the
SUB_FILES list must have a corresponding
file.in present
in FILESDIR. A modified version will
be created in WRKDIR. Files defined as a
value of USE_RC_SUBR and
USE_RCORDER are automatically added to
SUB_FILES. For the files
pkg-message,
pkg-install, pkg-deinstall
and pkg-reg, the corresponding Makefile variable
is automatically set to point to the processed version.The SUB_LIST variable is a list of
VAR=VALUE pairs. For each pair
%%VAR%% will get replaced
with VALUE in each file listed in
SUB_FILES. Several common pairs are
automatically defined: PREFIX,
LOCALBASE, X11BASE,
DATADIR, DOCSDIR,
EXAMPLESDIR. Any line beginning with
@comment will be deleted from resulting files
after a variable substitution.The following example will replace %%ARCH%%
with the system architecture
in a pkg-message:SUB_FILES= pkg-message
SUB_LIST= ARCH=${ARCH}Note that for this example, the
pkg-message.in file must exist in
FILESDIR.Example of a good pkg-message.in:Now it's time to configure this package.
Copy %%PREFIX%%/share/examples/putsy/%%ARCH%%.conf into your home directory
as .putsy.conf and edit it.Testing your portRunning make describeSeveral of the &os; port maintenance tools, such as
&man.portupgrade.1;, rely on a database called
/usr/ports/INDEX which keeps track of such
items as port dependencies. INDEX is created
by the top-level ports/Makefile via
make index, which descends into each
port subdirectory and executes make describe
there. Thus, if make describe fails in any
port, no one can generate INDEX, and many
people will quickly become unhappy.It is important to be able to generate this file no
matter what options are present in make.conf,
so please avoid doing things such as using .error
statements when (for instance) a dependency is not satisfied.How to avoid using .errorAssume that someone has the line
USE_POINTYHAT=yes
in make.conf. The first of
the next two Makefile snippets will
cause make index to fail, while the
second one will not:.if USE_POINTYHAT
.error "POINTYHAT is not supported"
.endif.if USE_POINTYHAT
IGNORE=POINTYHAT is not supported
.endifIf make describe produces a string
rather than an error message, you are probably safe. See
bsd.port.mk for the meaning of the
string produced.Also note that running a recent version of
portlint (as specified in the next section)
will cause make describe to be run
automatically.PortlintDo check your work with portlint
before you submit or commit it. portlint
warns you about many common errors, both functional and
stylistic. For a new (or repocopied) port,
portlint -A is the most thorough; for an
existing port, portlint -C is sufficient.Since portlint uses heuristics to
try to figure out errors, it can produce false positive
warnings. In addition, occasionally something that is
flagged as a problem really cannot be done in any other
way due to limitations in the ports framework. When in
doubt, the best thing to do is ask on &a.ports;.PREFIXDo try to make your port install relative to
PREFIX. The value of this variable will be set
to LOCALBASE (default
/usr/local). If
USE_X_PREFIX or USE_IMAKE is
set, PREFIX will be X11BASE (default
/usr/X11R6). If
USE_LINUX_PREFIX is set, PREFIX
will be LINUXBASE (default
/compat/linux).Avoiding the hard-coding of /usr/local or
/usr/X11R6 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 /usr/local (or
/usr/X11R6 for X ports that do not use imake)
in the various scripts/Makefiles in the port to read
${PREFIX}, as this variable is automatically passed
down to every stage of the build and install processes.Make sure your application is not installing things in
/usr/local instead of PREFIX.
A quick test for this is to do this is:&prompt.root; make clean; make package PREFIX=/var/tmp/port-nameIf anything is installed outside of PREFIX,
the package creation process will complain that it
cannot find the files.This does not test for the existence of internal references,
or correct use of LOCALBASE for references to
files from other ports. Testing the installation in
/var/tmp/port-name
to do that while you have it installed would do that.Do not set USE_X_PREFIX unless your port
truly requires it (i.e., it links against X libs or it needs to
reference files in X11BASE).The variable PREFIX 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.Also, refer to programs/files from other ports with the
variables mentioned above, not explicit pathnames. For instance, if
your port requires a macro PAGER to be the full
pathname of less, use the compiler flag:
-DPAGER=\"${LOCALBASE}/bin/less\"
instead of
-DPAGER=\"/usr/local/bin/less\". This way it will
have a better chance of working if the system administrator has
moved the whole /usr/local tree somewhere else.UpgradingWhen you notice that a port is out of date compared to the latest
version from the original authors, you should first ensure that you
have the latest
port. You can find them in the
ports/ports-current directory of the &os; FTP mirror
sites. However, if you are working with more than a few
ports, you will probably find it easier to use
CVSup to keep your whole ports collection
up-to-date, as described in the
Handbook.
This will have the added benefit of tracking all the ports'
dependencies.The next step is to see if there is an update already pending.
To do this, you have two options. There is a searchable interface
to the
FreeBSD Problem Report (PR) database (also known as
GNATS). Select ports in the
dropdown, and enter the name of the port.However, sometimes people forget to put the name of the port
into the Synopsis field in an unambiguous fashion. In that case,
you can try the
FreeBSD Ports Monitoring System (also known as
portsmon). This system attempts to classify
port PRs by portname. To search for PRs about a particular port,
- use the
+ use the
Overview of One Port.If there is no pending PR, the next step is to send an email
to the port's maintainer, as shown by
make maintainer. 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); you would not want to duplicate their work. Note that
unmaintained ports are listed with a maintainer of
ports@FreeBSD.org, which is just the general
ports mailing list, so sending mail there
probably will not help in this case.If the maintainer asks you to do the upgrade or there is
no maintainer, then you have a chance to help out &os; by
preparing the update yourself! Please make the changes and save
the result of the
recursive diff output
of the new and old
ports directories (e.g., if your modified port directory is
called superedit and the original is in our tree
as superedit.bak, then save the result of
diff -ruN superedit.bak superedit). Either
unified or context diff is fine, but port committers generally
prefer unified diffs. Note the use of the -N
option—this is the accepted way to force diff to properly
deal with the case of new files being added or old files being
deleted. Before sending us the diff, please examine the
output to make sure all the changes make sense. To
simplify common operations with patch files, you can use
/usr/ports/Tools/scripts/patchtool.py.
Before using it, please read
/usr/ports/Tools/scripts/README.patchtool.If the port is unmaintained, and you are actively using
it yourself, please consider volunteering to become its
maintainer. &os; has over 2000 ports without maintainers,
and this is an area where more volunteers are always needed.
(For a detailed description of the responsibilities of maintainers,
refer to the
MAINTAINER on Makefiles section.) The best way to
send us the diff is by including it via &man.send-pr.1; (category
ports). If you are volunteering to maintain the
port,
be sure to put [maintainer update] at the beginning
of your synopsis line and set the Class of your PR
to maintainer-update. Otherwise, the
Class of your PR should be
change-request. Please mention any added or
deleted files in the message, as they have to be explicitly specified
to &man.cvs.1; when doing a commit. If the diff is more than about 20KB,
please compress and uuencode it; otherwise, just include it in the PR
as is.Before you &man.send-pr.1;, you should review the
Writing the problem report section in the Problem
Reports article; it contains far more information about how to write
useful problem reports.If your upgrade is motivated by security concerns or a
serious fault in the currently committed port, please notify
the &a.portmgr; to request immediate rebuilding and
redistribution of your port's package. Unsuspecting users
of &man.pkg.add.1; will otherwise continue to install the
old version via pkg_add -r for several
weeks.Once again, please use &man.diff.1; and not &man.shar.1; to send
updates to existing ports!Now that you have done all that, you will want to read about
how to keep up-to-date in .Ports securityWhy security is so importantBugs are occasionally introduced to the software.
Arguably, the most dangerous of them are those opening
security vulnerabilities. From the technical viewpoint,
such vulnerabilities are to be closed by exterminating
the bugs that caused them. However, the policies for
handling mere bugs and security vulnerabilities are
very different.A typical small bug affects only those users who have
enabled some combination of options triggering the bug.
The developer will eventually release a patch followed
by a new version of the software, free of the bug, but
the majority of users will not take the trouble of upgrading
immediately because the bug has never vexed them. A
critical bug that may cause data loss represents a graver
issue. Nevertheless, prudent users know that a lot of
possible accidents, besides software bugs, are likely to
lead to data loss, and so they make backups of important
data; in addition, a critical bug will be discovered
really soon.A security vulnerability is all different. First,
it may remain unnoticed for years because often it does
not cause software malfunction. Second, a malicious party
can use it to gain unauthorized access to a vulnerable
system, to destroy or alter sensitive data; and in the
worst case the user will not even notice the harm caused.
Third, exposing a vulnerable system often assists attackers
to break into other systems that could not be compromised
otherwise. Therefore closing a vulnerability alone is
not enough: the audience should be notified of it in most
clear and comprehensive manner, which will allow to
evaluate the danger and take appropriate actions.Fixing security vulnerabilitiesWhile on the subject of ports and packages, a security
vulnerability may initially appear in the original
distribution or in the port files. In the former case,
the original software developer is likely to release a
patch or a new version instantly, and you will
only need to update the port promptly with respect to
the author's fix. If the fix is delayed for some reason,
you should either mark the port as
FORBIDDEN
or introduce a patch file of your own to the port. In
the case of a vulnerable port, just fix the port as soon as
possible. In either case, the
standard procedure for submitting your change should
be followed unless you have rights to commit it directly
to the ports tree.Being a ports committer is not enough to commit to
an arbitrary port. Remember that ports usually have
maintainers, whom you should respect.Please make sure that the port's revision is bumped
as soon as the vulnerability has been closed.
That is how the users who upgrade installed packages
on a regular basis will see they need to run an update.
Besides, a new package will be built and distributed
over FTP and WWW mirrors, replacing the vulnerable one.
PORTREVISION should be bumped unless
PORTVERSION has changed in the course
of correcting the vulnerability. That is you should
bump PORTREVISION if you have added a
patch file to the port, but you should not if you have updated
the port to the latest software version and thus already
touched PORTVERSION. Please refer to the
corresponding section
for more information.Keeping the community informedThe VuXML databaseA very important and urgent step to take as early as
a security vulnerability is discovered is to notify the
community of port users about the jeopardy. Such
notification serves two purposes. First, should the danger
be really severe, it will be wise to apply an instant workaround,
e.g., stop the affected network service or even deinstall
the port completely, until the vulnerability is closed.
Second, a lot of users tend to upgrade installed packages
just occasionally. They will know from the notification
that they must update the package
without delay as soon as a corrected version is available.Given the huge number of ports in the tree,
a security advisory cannot be issued on each incident
without creating a flood and losing the attention of
the audience by the time it comes to really serious
matters. Therefore security vulnerabilities found in
ports are recorded in the FreeBSD VuXML
database. The Security Officer Team members
are monitoring it for issues requiring their
intervention.If you have committer rights, you can update the VuXML
database by yourself. So you will both help the Security
Officer Team and deliver the crucial information to the
community earlier. However, if you are not a committer,
or you believe you have found an exceptionally severe
vulnerability, or whatever, please do not hesitate to
contact the Security Officer Team directly as described
on the FreeBSD
Security Information page.All right, you elected the hard way. As it may be obvious
from its title, the VuXML database is essentially an
XML document. Its source file vuln.xml
is kept right inside the port security/vuxml. Therefore
the file's full pathname will be
PORTSDIR/security/vuxml/vuln.xml.
Each time you discover a security vulnerability in a
port, please add an entry for it to that file.
Until you are familiar with VuXML, the best thing you can
do is to find an existing entry fitting your case, then copy
it and use as a template.A short introduction to VuXMLThe full-blown XML is complex and far beyond the scope of
this book. However, to gain basic insight on the structure
of a VuXML entry, you need only the notion of tags. XML
tag names are enclosed in angle brackets. Each opening
<tag> must have a matching closing </tag>.
Tags may be nested. If nesting, the inner tags must be
closed before the outer ones. There is a hierarchy of
tags, i.e. more complex rules of nesting them. Sounds
very similar to HTML, doesn't it? The major difference
is that XML is eXtensible, i.e. based
on defining custom tags. Due to its intrinsic structure,
XML puts otherwise amorphous data into shape. VuXML is
particularly tailored to mark up descriptions of security
vulnerabilities.Now let's consider a realistic VuXML entry:<vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9">
<topic>Several vulnerabilities found in Foo</topic>
<affects>
<package>
<name>foo</name>
<name>foo-devel</name>
<name>ja-foo</name>
<range><ge>1.6</ge><lt>1.9</lt></range>
<range><ge>2.*</ge><lt>2.4_1</lt></range>
<range><eq>3.0b1</eq></range>
</package>
<package>
<name>openfoo</name>
<range><lt>1.10_7</lt></range>
<range><ge>1.2,1</ge><lt>1.3_1,1</lt></range>
</package>
</affects>
<description>
<body xmlns="http://www.w3.org/1999/xhtml">
<p>J. Random Hacker reports:</p>
<blockquote
cite="http://j.r.hacker.com/advisories/1">
<p>Several issues in the Foo software may be exploited
via carefully crafted QUUX requests. These requests will
permit the injection of Bar code, mumble theft, and the
readability of the Foo administrator account.</p>
</blockquote>
</body>
</description>
<references>
<freebsdsa>SA-10:75.foo</freebsdsa>
<freebsdpr>ports/987654</freebsdpr>
<cvename>CAN-2010-0201</cvename>
<cvename>CAN-2010-0466</cvename>
<bid>96298</bid>
<certsa>CA-2010-99</certsa>
<certvu>740169</certvu>
<uscertsa>SA10-99A</uscertsa>
<uscertta>SA10-99A</uscertta>
<mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&m=203886607825605</mlist>
<url>http://j.r.hacker.com/advisories/1</url>
</references>
<dates>
<discovery>2010-05-25</discovery>
<entry>2010-07-13</entry>
<modified>2010-09-17</entry>
</dates>
</vuln>The tag names are supposed to be self-descriptive,
so we shall take a closer look only at fields you will need
to fill in by yourself:This is the top-level tag of a VuXML entry. It has
a mandatory attribute, vid,
specifying a universally unique identifier (UUID) for
this entry (in quotes). You should generate a UUID
for each new VuXML entry (and do not forget to substitute
it for the template UUID unless you are writing the
entry from scratch). You can use &man.uuidgen.1; in
FreeBSD 5.x, or you may install the port devel/p5-Data-UUID and issue
the following command:perl -MData::UUID -le 'print lc new Data::UUID->create_str'This is a one-line description of the issue found.The names of packages affected are listed there.
Multiple names can be given since several packages may be
based on a single master port or software product. This
may include stable and development branches, localized
versions, and slave ports featuring different choices of
important build-time configuration options.It is your responsibility to find all such related
packages when writing a VuXML entry. Keep in mind that
make search name=foo is your friend.
The primary points to look for are as follows:the foo-devel variant
for a foo port;other variants with a suffix like
-a4 (for print-related packages),
-without-gui (for packages with X
support disabled), or similar;jp-, ru-,
zh-, and other possible localized
variants in the corresponding national categories of
the ports collection.Affected versions of the package(s) are specified
there as one or more ranges using a combination of
<lt>, <le>,
<eq>, <ge>,
and <gt> elements. The
version ranges given should not overlap.In a range specification, * (asterisk)
denotes the smallest version number. In particular,
2.* is less than 2.a.
Therefore an asterisk may be used for a range to match all
possible alpha, beta,
and RC versions. For instance,
<ge>2.*</ge><lt>3.*</lt>
will selectively match every 2.x version while
<ge>2.0</ge><lt>3.0</lt>
will obviously not since the latter misses
2.r3 and matches
3.b.The above example
specifies that affected are versions from 1.6
to 1.9 inclusive, versions
2.x before 2.4_1,
and version 3.0b1.Several related package groups (essentially, ports)
can be listed in the <affected>
section. This can be used if several software products
(say FooBar, FreeBar and OpenBar) grow from the same code base
and still share its bugs and vulnerabilities. Note the
difference from listing multiple names within a single
<package> section.The version ranges should allow for
PORTEPOCH and
PORTREVISION if applicable.
Please remember that according to the collation rules,
a version with a non-zero PORTEPOCH is
greater than any version without
PORTEPOCH, e.g., 3.0,1
is greater than 3.1 or even than
8.9.This is a summary of the issue.
XHTML is used in this field. At least enclosing
<p> and </p>
should appear. More complex mark-up may be used, but only for
the sake of accuracy and clarity: No eye candy please.This section contains references to relevant documents.
As many references as apply are encouraged.This is a
FreeBSD
security advisory.This is a
FreeBSD
problem report.This is a Mitre
CVE identifier.This is a
SecurityFocus
Bug ID.This is a
US-CERT
security advisory.This is a
US-CERT
vulnerability note.This is a
US-CERT
Cyber Security Alert.This is a
US-CERT
Technical Cyber Security Alert.This is a URL to an archived posting in a mailing list.
The attribute msgid is optional and
may specify the message ID of the posting.This is a generic URL. It should be used only if none of
the other reference categories apply.This is the date when the issue was disclosed
(YYYY-MM-DD).This is the date when the entry was added
(YYYY-MM-DD).This is the date when any information in the entry
was last modified (YYYY-MM-DD).
New entries must not include this field. It should be added
upon editing an existing entry.Testing your changes to the VuXML databaseAssume you just wrote or filled in an entry for a
vulnerability in the package clamav
that has been fixed in version 0.65_7.As a prerequisite, you need to install fresh versions of the
ports security/portaudit and
security/portaudit-db.First, check whether there already is an entry for this
vulnerability. If there were such entry, it would match the
previous version of the package,
0.65_6:&prompt.user; packaudit
&prompt.user; portaudit clamav-0.65_6To run packaudit, you must have
permission to write to its
DATABASEDIR,
typically /var/db/portaudit.If there is none found, you get the green light to add
a new entry for this vulnerability. Now you can generate
a brand-new UUID (assume it's
74a9541d-5d6c-11d8-80e3-0020ed76ef5a) and
add your new entry to the VuXML database. Please verify
its syntax after that as follows:&prompt.user; cd ${PORTSDIR}/security/vuxml && make validateYou will need at least one of the following packages
installed: textproc/libxml2,
textproc/jade.Now rebuild the portaudit database
from the VuXML file:&prompt.user; packauditTo verify that the <affected>
section of your entry will match correct package(s), issue
the following command:&prompt.user; portaudit -f /usr/ports/INDEX -r 74a9541d-5d6c-11d8-80e3-0020ed76ef5aPlease refer to &man.portaudit.1; for better understanding
of the command syntax.Make sure that your entry produces no spurious matches
in the output.Now check whether the right package versions are matched
by your entry:&prompt.user; portaudit clamav-0.65_6 clamav-0.65_7
Affected package: clamav-0.65_6 (matched by clamav<0.65_7)
Type of problem: clamav remote denial-of-service.
Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html>
1 problem(s) found.Obviously, the former version should match while the
latter one should not.Finally, verify whether the web page generated from the
VuXML database looks like expected:&prompt.user; mkdir -p ~/public_html/portaudit
&prompt.user; packaudit
&prompt.user; lynx ~/public_html/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.htmlIf VuXML still scares you...As an easy alternative to writing VuXML, you may opt to add
a single line to a different file with much simpler syntax,
PORTSDIR/security/portaudit-db/database/portaudit.txt,
which resides within the port security/portaudit-db, and
send a request for review to the Security Officer Team
as described on the FreeBSD
Security Information page.A line in that file consists of four fields
separated by |, a pipe character.
The first field is a &man.pkg.version.1; pattern
expression matching the vulnerable packages. The second
field contains URLs to relevant information, separated
by space characters. The third field is a one-line
description of the issue. The fourth and last field
is the entry's UUID.You may want take a closer look at existing entries in
portaudit.txt before adding your
first line to that file.Dos and Don'tsIntroductionHere is a list of common dos and don'ts that you encounter during
the porting process. You should check your own port against this list,
but you can also check ports in the PR database that others have
submitted. Submit any comments on ports you check as described in
Bug Reports and General
Commentary. Checking ports in the PR database will both make
it faster for us to commit them, and prove that you know what you are
doing.Stripping BinariesDo not strip binaries manually unless you have to. All binaries
should be stripped, but the INSTALL_PROGRAM
macro will install and strip a binary at the same time (see the next
section).If you need to strip a file, but do not wish to use the
INSTALL_PROGRAM macro,
${STRIP_CMD} will strip your program. This is
typically done within the post-install
target. For example:post-install:
${STRIP_CMD} ${PREFIX}/bin/xdlUse the &man.file.1; command on the installed executable to
check whether the binary is stripped or not. If it does not say
not stripped, it is stripped. Additionally,
&man.strip.1; will not strip a previously stripped program; it
will instead exit cleanly.INSTALL_* macrosDo use the macros provided in bsd.port.mk
to ensure correct modes and ownership of files in your own
*-install targets.INSTALL_PROGRAM is a command to install
binary executables.INSTALL_SCRIPT is a command to install
executable scripts.INSTALL_DATA is a command to install
sharable data.INSTALL_MAN is a command to install
manpages and other documentation (it does not compress
anything).These are basically the install command with
all the appropriate flags. See below for an example on how to use
them.WRKDIRDo not write anything to files outside
WRKDIR. WRKDIR is the only
place that is guaranteed to be writable during the port build (see
installing ports from a CDROM for an
example of building ports from a read-only tree). If you need to
modify one of the pkg-*
files, do so by redefining a variable, not by
writing over it.WRKDIRPREFIXMake sure your port honors WRKDIRPREFIX.
Most ports do not have to worry about this. In particular, if you
are referring to a WRKDIR of another port, note
that the correct location is
WRKDIRPREFIXPORTSDIR/subdir/name/work not PORTSDIR/subdir/name/work or .CURDIR/../../subdir/name/work or some such.Also, if you are defining WRKDIR yourself,
make sure you prepend
${WRKDIRPREFIX}${.CURDIR} in the
front.Differentiating operating systems and OS versionsYou 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 older FreeBSD systems and cross-port
to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD,
NetBSD, and OpenBSD.The preferred way to tell 4.3BSD/Reno (1990) and newer versions
of the BSD code apart is by using the BSD macro
defined in
sys/param.h.
Hopefully that
file is already included; if not, add the code:#if (defined(__unix__) || defined(unix)) && !defined(USG)
#include <sys/param.h>
#endifto the proper place in the .c file. We
believe that every system that defines these two symbols has
sys/param.h. If you find a system that
does not, we would like to know. Please send mail to the
&a.ports;.Another way is to use the GNU Autoconf style of doing
this:#ifdef HAVE_SYS_PARAM_H
#include <sys/param.h>
#endifDo not forget to add -DHAVE_SYS_PARAM_H to the
CFLAGS in the Makefile for
this method.Once you have sys/param.h included, you may
use:#if (defined(BSD) && (BSD >= 199103))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:#if (defined(BSD) && (BSD >= 199306))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).The value of the BSD macro is
199506 for the 4.4BSD-Lite2 code base. This is
stated for informational purposes only. It should not be used to
distinguish between versions of FreeBSD based only on 4.4-Lite vs.
versions that have merged in changes from 4.4-Lite2. The
__FreeBSD__ macro should be used instead.Use sparingly:__FreeBSD__ is defined in all versions of
FreeBSD. Use it if the change you are making
only affects FreeBSD. Porting gotchas like
the use of sys_errlist[] vs
strerror() are Berkeley-isms, not FreeBSD
changes.In FreeBSD 2.x, __FreeBSD__ is defined to
be 2. In earlier versions, it is
1. Later versions always bump it to match
their major version number.If you need to tell the difference between a FreeBSD 1.x
system and a FreeBSD 2.x or above system, usually the right answer
is to use the BSD macros described above. If
there actually is a FreeBSD specific change (such as special
shared library options when using ld) then it
is OK to use __FreeBSD__ and #if
__FreeBSD__ > 1 to detect a FreeBSD 2.x and later
system. If you need more granularity in detecting FreeBSD
systems since 2.0-RELEASE you can use the following:#if __FreeBSD__ >= 2
#include <osreldate.h>
# if __FreeBSD_version >= 199504
/* 2.0.5+ release specific code here */
# endif
#endifIn the hundreds of ports that have been done, there have only
been one or two cases where __FreeBSD__ 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.__FreeBSD_version valuesHere is a convenient list of
__FreeBSD_version values as defined in
sys/param.h:
__FreeBSD_version valuesRelease__FreeBSD_version2.0-RELEASE1194112.1-CURRENT199501, 1995032.0.5-RELEASE1995042.2-CURRENT before 2.11995082.1.0-RELEASE1995112.2-CURRENT before 2.1.51995122.1.5-RELEASE1996072.2-CURRENT before 2.1.61996082.1.6-RELEASE1996122.1.7-RELEASE1996122.2-RELEASE2200002.2.1-RELEASE220000 (no change)2.2-STABLE after 2.2.1-RELEASE220000 (no change)2.2-STABLE after texinfo-3.92210012.2-STABLE after top2210022.2.2-RELEASE2220002.2-STABLE after 2.2.2-RELEASE2220012.2.5-RELEASE2250002.2-STABLE after 2.2.5-RELEASE2250012.2-STABLE after ldconfig -R merge2250022.2.6-RELEASE2260002.2.7-RELEASE2270002.2-STABLE after 2.2.7-RELEASE2270012.2-STABLE after &man.semctl.2; change2270022.2.8-RELEASE2280002.2-STABLE after 2.2.8-RELEASE2280013.0-CURRENT before &man.mount.2; change3000003.0-CURRENT after &man.mount.2; change3000013.0-CURRENT after &man.semctl.2; change3000023.0-CURRENT after ioctl arg changes3000033.0-CURRENT after ELF conversion3000043.0-RELEASE3000053.0-CURRENT after 3.0-RELEASE3000063.0-STABLE after 3/4 branch3000073.1-RELEASE3100003.1-STABLE after 3.1-RELEASE3100013.1-STABLE after C++ constructor/destructor order
change3100023.2-RELEASE3200003.2-STABLE3200013.2-STABLE after binary-incompatible IPFW and
socket changes3200023.3-RELEASE3300003.3-STABLE3300013.3-STABLE after adding &man.mkstemp.3;
to libc3300023.4-RELEASE3400003.4-STABLE3400013.5-RELEASE3500003.5-STABLE3500014.0-CURRENT after 3.4 branch4000004.0-CURRENT after change in dynamic linker
handling4000014.0-CURRENT after C++ constructor/destructor
order change4000024.0-CURRENT after functioning &man.dladdr.3;4000034.0-CURRENT after __deregister_frame_info dynamic
linker bug fix (also 4.0-CURRENT after EGCS 1.1.2
integration)
4000044.0-CURRENT after &man.suser.9; API change
(also 4.0-CURRENT after newbus)4000054.0-CURRENT after cdevsw registration change4000064.0-CURRENT after the addition of so_cred for
socket level credentials4000074.0-CURRENT after the addition of a poll syscall
wrapper to libc_r4000084.0-CURRENT after the change of the kernel's
dev_t type to struct
specinfo pointer4000094.0-CURRENT after fixing a hole
in &man.jail.2;4000104.0-CURRENT after the sigset_t
datatype change4000114.0-CURRENT after the cutover to the GCC 2.95.2
compiler4000124.0-CURRENT after adding pluggable linux-mode
ioctl handlers4000134.0-CURRENT after importing OpenSSL4000144.0-CURRENT after the C++ ABI change in GCC 2.95.2
from -fvtable-thunks to -fno-vtable-thunks by
default4000154.0-CURRENT after importing OpenSSH4000164.0-RELEASE4000174.0-STABLE after 4.0-RELEASE4000184.0-STABLE after the introduction of delayed
checksums.4000194.0-STABLE after merging libxpg4 code into
libc.4000204.0-STABLE after upgrading Binutils to 2.10.0, ELF
branding changes, and tcsh in the base system.4000214.1-RELEASE4100004.1-STABLE after 4.1-RELEASE4100014.1-STABLE after &man.setproctitle.3; moved from
libutil to libc.4100024.1.1-RELEASE4110004.1.1-STABLE after 4.1.1-RELEASE4110014.2-RELEASE4200004.2-STABLE after combining libgcc.a and
libgcc_r.a, and associated GCC linkage changes.4200014.3-RELEASE4300004.3-STABLE after wint_t introduction.4300014.3-STABLE after PCI powerstate API merge.4300024.4-RELEASE4400004.4-STABLE after d_thread_t introduction.4400014.4-STABLE after mount structure changes (affects
filesystem klds).4400024.4-STABLE after the userland components of smbfs
were imported.4400034.5-RELEASE4500004.5-STABLE after the usb structure element rename.4500014.5-STABLE after the
sendmail_enable &man.rc.conf.5;
variable was made to take the value
NONE.4500044.5-STABLE after moving to XFree86 4 by default
for package builds.4500054.5-STABLE after accept filtering was fixed so
that is no longer susceptible to an easy DoS.4500064.6-RELEASE4600004.6-STABLE &man.sendfile.2; fixed to comply with
documentation, not to count any headers sent against
the amount of data to be sent from the file.4600014.6.2-RELEASE4600024.6-STABLE4601004.6-STABLE after MFC of `sed -i'.4601014.6-STABLE after MFC of many new pkg_install
features from the HEAD.4601024.7-RELEASE4700004.7-STABLE470100Start generated __std{in,out,err}p references rather
than __sF. This changes std{in,out,err} from a
compile time expression to a runtime one.4701014.7-STABLE after MFC of mbuf changes to replace
m_aux mbufs by m_tag's4701024.7-STABLE gets OpenSSL 0.9.74701034.8-RELEASE4800004.8-STABLE4801004.8-STABLE after &man.realpath.3; has been made
thread-safe4801014.8-STABLE 3ware API changes to twe.4801024.9-RELEASE4900004.9-STABLE4901004.9-STABLE after e_sid was added to struct
kinfo_eproc.4901014.9-STABLE after MFC of libmap functionality
for rtld.4901024.10-RELEASE4910004.10-STABLE4911004.10-STABLE after MFC of revision 20040629 of
the package tools4911014.10-STABLE after VM fix dealing with unwiring
of fictitious pages4911024.11-RELEASE4920004.11-STABLE4921005.0-CURRENT5000005.0-CURRENT after adding addition ELF header fields,
and changing our ELF binary branding method.5000015.0-CURRENT after kld metadata changes.5000025.0-CURRENT after buf/bio changes.5000035.0-CURRENT after binutils upgrade.5000045.0-CURRENT after merging libxpg4 code into
libc and after TASKQ interface introduction.5000055.0-CURRENT after the addition of AGP
interfaces.5000065.0-CURRENT after Perl upgrade to 5.6.05000075.0-CURRENT after the update of KAME code to
2000/07 sources.5000085.0-CURRENT after ether_ifattach() and
ether_ifdetach() changes.5000095.0-CURRENT after changing mtree defaults
back to original variant, adding -L to follow
symlinks.5000105.0-CURRENT after kqueue API changed.5000115.0-CURRENT after &man.setproctitle.3; moved from
libutil to libc.5000125.0-CURRENT after the first SMPng commit.5000135.0-CURRENT after <sys/select.h> moved to
<sys/selinfo.h>.5000145.0-CURRENT after combining libgcc.a and
libgcc_r.a, and associated GCC linkage changes.5000155.0-CURRENT after change allowing libc and libc_r
to be linked together, deprecating -pthread
option.5000165.0-CURRENT after switch from struct ucred to
struct xucred to stabilize kernel-exported API for
mountd et al.5000175.0-CURRENT after addition of CPUTYPE make variable
for controlling CPU-specific optimizations.5000185.0-CURRENT after moving machine/ioctl_fd.h to
sys/fdcio.h5000195.0-CURRENT after locale names renaming.5000205.0-CURRENT after Bzip2 import.
Also signifies removal of S/Key.5000215.0-CURRENT after SSE support.5000225.0-CURRENT after KSE Milestone 2.5000235.0-CURRENT after d_thread_t,
and moving UUCP to ports.5000245.0-CURRENT after ABI change for descriptor
and creds passing on 64 bit platforms.5000255.0-CURRENT after moving to XFree86 4 by default for
package builds, and after the new libc strnstr() function
was added.5000265.0-CURRENT after the new libc strcasestr() function
was added.5000275.0-CURRENT after the userland components of smbfs
were imported.5000285.0-CURRENT after the new C99 specific-width
integer types were added.(Not incremented.)5.0-CURRENT after a change was made in the return
value of &man.sendfile.2;.5000295.0-CURRENT after the introduction of the
type fflags_t, which is the
appropriate size for file flags.5000305.0-CURRENT after the usb structure element rename.5000315.0-CURRENT after the introduction of
Perl 5.6.1.5000325.0-CURRENT after the
sendmail_enable &man.rc.conf.5;
variable was made to take the value
NONE.5000335.0-CURRENT after mtx_init() grew a third argument.5000345.0-CURRENT with Gcc 3.1.5000355.0-CURRENT without Perl in /usr/src5000365.0-CURRENT after the addition of &man.dlfunc.3;5000375.0-CURRENT after the types of some struct
sockbuf members were changed and the structure was
reordered.5000385.0-CURRENT after GCC 3.2.1 import.
Also after headers stopped using
_BSD_FOO_T_ and started using _FOO_T_DECLARED.
This value can also be used as a conservative
estimate of the start of &man.bzip2.1; package
support.5000395.0-CURRENT after various changes to disk functions
were made in the name of removing dependency on disklabel
structure internals.5000405.0-CURRENT after the addition of &man.getopt.long.3;
to libc.5000415.0-CURRENT after Binutils 2.13 upgrade, which
included new FreeBSD emulation, vec, and output format.
5000425.0-CURRENT after adding weak pthread_XXX stubs
to libc, obsoleting libXThrStub.so. 5.0-RELEASE.5000435.0-CURRENT after branching for RELENG_5_0500100<sys/dkstat.h> is empty and should
not be included.5001015.0-CURRENT after the d_mmap_t interface
change.5001025.0-CURRENT after taskqueue_swi changed to run
without Giant, and taskqueue_swi_giant added to run
with Giant.500103cdevsw_add() and cdevsw_remove() no
longer exists.
Appearance of MAJOR_AUTO allocation facility.5001045.0-CURRENT after new cdevsw initialization method.500105devstat_add_entry() has been replaced by
devstat_new_entry()500106Devstat interface change; see sys/sys/param.h 1.149500107Token-Ring interface changes.500108Addition of vm_paddr_t.5001095.0-CURRENT after &man.realpath.3; has been made
thread-safe5001105.0-CURRENT after &man.usbhid.3; has been synced with
NetBSD5001115.0-CURRENT after new NSS implementation
and addition of POSIX.1 getpw*_r, getgr*_r
functions5001125.0-CURRENT after removal of the old rc system.5001135.1-RELEASE.5010005.1-CURRENT after branching for RELENG_5_1.5011005.1-CURRENT after correcting the semantics of
sigtimedwait(2) and sigwaitinfo(2).5011015.1-CURRENT after adding the lockfunc and lockfuncarg
fields to &man.bus.dma.tag.create.9;.5011025.1-CURRENT after GCC 3.3.1-pre 20030711 snapshot
integration.5011035.1-CURRENT 3ware API changes to twe.5011045.1-CURRENT dynamically-linked /bin and /sbin
support and movement of libraries to /lib.5011055.1-CURRENT after adding kernel support for
Coda 6.x.5011065.1-CURRENT after 16550 UART constants moved from
<dev/sio/sioreg.h> to
<dev/ic/ns16550.h>.
Also when libmap functionality was unconditionally
supported by rtld.5011075.1-CURRENT after PFIL_HOOKS API update5011085.1-CURRENT after adding kiconv(3)5011095.1-CURRENT after changing default operations
for open and close in cdevsw5011105.1-CURRENT after changed layout of cdevsw501111 5.1-CURRENT after adding kobj multiple inheritance
501112 5.1-CURRENT after the if_xname change in
struct ifnet501113 5.1-CURRENT after changing /bin and /sbin to
be dynamically linked5011145.2-RELEASE5020005.2.1-RELEASE5020105.2-CURRENT after branching for RELENG_5_25021005.2-CURRENT after __cxa_atexit/__cxa_finalize
functions were added to libc.5021015.2-CURRENT after change of default thread library
from libc_r to libpthread.5021025.2-CURRENT after device driver API megapatch.
5021035.2-CURRENT after getopt_long_only() addition.
5021045.2-CURRENT after NULL is made into ((void *)0)
for C, creating more warnings.
5021055.2-CURRENT after pf is linked to the build and
install.
5021065.2-CURRENT after time_t is changed to a
64-bit value on sparc64.
5021075.2-CURRENT after Intel C/C++ compiler support in some headers and execve(2) changes to be more strictly conforming to POSIX.
5021085.2-CURRENT after the introduction of the
bus_alloc_resource_any API
5021095.2-CURRENT after the addition of UTF-8 locales
5021105.2-CURRENT after the removal of the getvfsent(3)
API
5021115.2-CURRENT after the addition of the .warning
directive for make.5021125.2-CURRENT after ttyioctl() was made mandatory
for serial drivers.5021135.2-CURRENT after import of the ALTQ framework.
5021145.2-CURRENT after changing sema_timedwait(9) to
return 0 on success and a non-zero error code on
failure.
5021155.2-CURRENT after changing kernel dev_t to
be pointer to struct cdev *.
5021165.2-CURRENT after changing kernel udev_t to dev_t.
5021175.2-CURRENT after adding support for CLOCK_VIRTUAL
and CLOCK_PROF to clock_gettime(2) and clock_getres(2).
5021185.2-CURRENT after changing network interface
cloning overhaul.
5021195.2-CURRENT after the update of the package tools
to revision 20040629.
5021205.2-CURRENT after marking Bluetooth code as
non-i386 specific.
5021215.2-CURRENT after the introduction of the KDB
debugger framework, the conversion of DDB into a
backend and the introduction of the GDB backend.
5021225.2-CURRENT after change to make
VFS_ROOT take a struct
thread argument as does vflush. Struct kinfo_proc
now has a user data pointer.
The switch of the default X implementation to
xorg was also made at this time.
5021235.2-CURRENT after the change to separate the way
ports rc.d and legacy scripts are started.
5021245.2-CURRENT after the backout of the
previous change.
5021255.2-CURRENT after the removal of
kmem_alloc_pageable() and the import of gcc 3.4.2.
5021265.2-CURRENT after changing the UMA kernel
API to allow ctors/inits to fail.
5021275.2-CURRENT after the change of the
vfs_mount signature as well as global replacement of
PRISON_ROOT with SUSER_ALLOWJAIL for the suser(9)
API.
5021285.3-BETA/RC before the pfil API change5030005.3-RELEASE5030015.3-STABLE after branching for RELENG_5_35031005.3-STABLE after addition of glibc style
&man.strftime.3; padding options.5031015.3-STABLE after OpenBSD's nc(1) import MFC.5031025.4-PRERELEASE after the MFC of the fixes in
<src/include/stdbool.h> and
<src/sys/i386/include/_types.h>
for using the GCC-compatibility of the Intel C/C++ compiler.5031035.4-PRERELEASE after the MFC of the change of
ifi_epoch from wall clock time to uptime.5031045.4-PRERELEASE after the MFC of the fix of EOVERFLOW check in vswprintf(3).5031055.4-RELEASE.5040005.4-STABLE after branching for RELENG_5_45041005.4-STABLE after increasing the default
thread stacksizes5041015.4-STABLE after the addition of sha2565041026.0-CURRENT6000006.0-CURRENT after permanently enabling PFIL_HOOKS
in the kernel.
6000016.0-CURRENT after initial addition of
ifi_epoch to struct if_data. Backed out after a
few days. Do not use this value.
6000026.0-CURRENT after the re-addition of the
ifi_epoch member of struct if_data.
6000036.0-CURRENT after addition of the struct inpcb
argument to the pfil API.
6000046.0-CURRENT after addition of the "-d
DESTDIR" argument to newsyslog.
6000056.0-CURRENT after addition of glibc style
&man.strftime.3; padding options.
6000066.0-CURRENT after addition of 802.11 framework
updates.
6000076.0-CURRENT after changes to VOP_*VOBJECT() functions
and introduction of MNTK_MPSAFE flag for Giantfree filesystems.
6000086.0-CURRENT after addition of the cpufreq framework
and drivers.
6000096.0-CURRENT after importing OpenBSD's nc(1).6000106.0-CURRENT after removing semblance of SVID2
matherr() support.6000116.0-CURRENT after increase of default thread stacks'
size.6000126.0-CURRENT after fixes in
<src/include/stdbool.h> and
<src/sys/i386/include/_types.h>
for using the GCC-compatibility of the Intel C/C++ compiler.6000136.0-CURRENT after EOVERFLOW checks in vswprintf(3) fixed.6000146.0-CURRENT after changing the struct if_data
member, ifi_epoch, from wall clock time to uptime.6000156.0-CURRENT after LC_CTYPE disk format changed.6000166.0-CURRENT after NLS catalogs disk format changed.6000176.0-CURRENT after LC_COLLATE disk format changed.600018Installation of acpica includes into /usr/include.600019Addition of MSG_NOSIGNAL flag to send(2) API.600020Addition of fields to cdevsw600021Removed gtar from base system.600022LOCAL_CREDS, LOCAL_CONNWAIT socket options added to unix(4).600023&man.hwpmc.4; and related tools added to 6.0-CURRENT.600024struct icmphdr added to 6.0-CURRENT.600025pf updated to 3.7.600026Kernel libalias and ng_nat introduced.600027POSIX ttyname_r(3) made available through unistd.h and libc.6000286.0-CURRENT after libpcap updated to v0.9.1 alpha 096.6000296.0-CURRENT after importing NetBSD's if_bridge(4).6000306.0-CURRENT after struct ifnet was broken out
of the driver softcs.6000316.0-CURRENT after the import of libpcap v0.9.1.6000327.0-CURRENT.700000
Note that 2.2-STABLE sometimes identifies itself as
2.2.5-STABLE after the 2.2.5-RELEASE. The pattern
used to be year followed by the month, but we decided to change it
to a more straightforward major/minor system starting from 2.2.
This is because the parallel development on several branches made
it infeasible to classify the releases simply by their real
release dates. If you are making a port now, you do not have to
worry about old -CURRENTs; they are listed here just for your
reference.Writing something after
bsd.port.mkDo not write anything after the .include
<bsd.port.mk> line. It usually can be avoided by
including bsd.port.pre.mk somewhere in the
middle of your Makefile and
bsd.port.post.mk at the end.You need to include either the
bsd.port.pre.mk/bsd.port.post.mk pair or
bsd.port.mk only; do not mix these two usages.bsd.port.pre.mk only defines a few
variables, which can be used in tests in the
Makefile, bsd.port.post.mk
defines the rest.Here are some important variables defined in
bsd.port.pre.mk (this is not the complete list,
please read bsd.port.mk for the complete
list).VariableDescriptionARCHThe architecture as returned by uname
-m (e.g., i386)OPSYSThe operating system type, as returned by
uname -s (e.g.,
FreeBSD)OSRELThe release version of the operating system (e.g.,
2.1.5 or
2.2.7)OSVERSIONThe numeric version of the operating system; the same as
__FreeBSD_version.PORTOBJFORMATThe object format of the system
(elf or aout;
note that for modern versions of FreeBSD,
aout is deprecated.)LOCALBASEThe base of the local tree (e.g.,
/usr/local/)X11BASEThe base of the X11 tree (e.g.,
/usr/X11R6)PREFIXWhere the port installs itself (see more on
PREFIX).If you have to define the variables
USE_IMAKE, USE_X_PREFIX, or
MASTERDIR, do so before including
bsd.port.pre.mk.Here are some examples of things you can write after
bsd.port.pre.mk:# no need to compile lang/perl5 if perl5 is already in system
.if ${OSVERSION} > 300003
BROKEN= perl is in system
.endif
# only one shlib version number for ELF
.if ${PORTOBJFORMAT} == "elf"
TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}
.else
TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR}
.endif
# software already makes link for ELF, but not for a.out
post-install:
.if ${PORTOBJFORMAT} == "aout"
${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so
.endifYou did remember to use tab instead of spaces after
BROKEN= and
TCL_LIB_FILE=, did you not?
:-).Install additional documentationIf your software has some documentation other than the standard
man and info pages that you think is useful for the user, install it
under PREFIX/share/doc.
This can be done, like the previous item, in the
post-install target.Create a new directory for your port. The directory name should
reflect what the port is. This usually means
PORTNAME. 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
PKGNAME.Make the installation dependent on the variable
NOPORTDOCS so that users can disable it in
/etc/make.conf, like this:post-install:
.if !defined(NOPORTDOCS)
${MKDIR} ${DOCSDIR}
${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR}
.endifHere are some handy variables and how they are expanded
by default when used
in the Makefile:DATADIR gets expanded to
PREFIX/share/PORTNAME.DOCSDIR gets expanded to
PREFIX/share/doc/PORTNAME.EXAMPLESDIR gets expanded to
PREFIX/share/examples/PORTNAME.These variables are exported to PLIST_SUB.
Their values will appear there as pathnames relative to
PREFIX if possible.
That is, share/doc/PORTNAME
will be substituted for %%DOCSDIR%%
in the packing list by default, and so on.
(See more on pkg-plist substitution
here.)All documentation files and directories installed should
be included in pkg-plist with the
%%PORTDOCS%% prefix, for example:%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
%%PORTDOCS%%%%DOCSDIR%%/CONTACT
%%PORTDOCS%%@dirrm %%DOCSDIR%%As an alternative to enumerating the documentation files
in pkg-plist, a port can set the variable
PORTDOCS to a list of file names and shell
glob patterns to add to the final packing list.
The names will be relative to DOCSDIR.
Therefore, a port that utilizes PORTDOCS and
uses a non-default location for its documentation should set
DOCSDIR accordingly.
If a directory is listed in PORTDOCS
or matched by a glob pattern from this variable,
the entire subtree of contained files and directories will be
registered in the final packing list. PORTDOCS
should not be set if NOPORTDOCS is in
effect. Installing the documentation at PORTDOCS
as shown above remains up to the port itself.
A typical example of utilizing PORTDOCS
looks as follows:.if !defined(NOPORTDOCS)
PORTDOCS= *
.endifYou can also use the pkg-message file to
display messages upon installation. See the section on using
pkg-message for details.
The pkg-message file does not need to be
added to pkg-plist.SubdirectoriesTry to let the port put things in the right subdirectories of
PREFIX. 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 lib, which does
not work well with the BSD paradigm. Many of the files should be
moved to one of the following: etc
(setup/configuration files), libexec
(executables started internally), sbin
(executables for superusers/managers), info
(documentation for info browser) or share
(architecture independent files). See &man.hier.7; for details;
the rules governing
/usr pretty much apply to
/usr/local too. The exception are ports
dealing with USENET news. They may use
PREFIX/news as a destination
for their files.Cleaning up empty directoriesDo make your ports clean up after themselves when they are
de-installed. This is usually accomplished by adding
@dirrm lines for all directories that are
specifically created by the port. You need to delete subdirectories
before you can delete parent directories. :
lib/X11/oneko/pixmaps/cat.xpm
lib/X11/oneko/sounds/cat.au
:
@dirrm lib/X11/oneko/pixmaps
@dirrm lib/X11/oneko/sounds
@dirrm lib/X11/onekoHowever, sometimes @dirrm will give you
errors because other ports also share the same subdirectory. You
can call rmdir from @unexec to
remove only empty directories without warning.@unexec rmdir %D/share/doc/gimp 2>/dev/null || trueThis will neither print any error messages nor cause
&man.pkg.delete.1; to exit abnormally even if
PREFIX/share/doc/gimp is not
empty due to other ports installing some files in there.UIDs and GIDsIf your port requires a certain user to be on the installed
system, let the pkg-install script call
pw to create it automatically. Look at
net/cvsup-mirror for an example.If your port must use the same user/group ID number when it is
installed as a binary package as when it was compiled, then you must
choose a free UID from 50 to 999 and register it below. Look at
japanese/Wnn6 for an example.Make sure you do not use a UID already used by the system or
other ports.This is the current list of UIDs between 50 and 999.bind:*:53:53:Bind Sandbox:/:/sbin/nologin
majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent
rdfdb:*:55:55:rdfDB Daemon:/var/db/rdfdb:/bin/sh
spamd:*:58:58:SpamAssassin user:/var/spool/spamd:/sbin/nologin
cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent
gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh
proxy:*:62:62:Packet Filter pseudo-user:/nonexistent:/nonexistent
uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent
pop:*:68:6:Post Office Owner (popper):/nonexistent:/sbin/nologin
wnn:*:69:7:Wnn:/nonexistent:/nonexistent
pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh
oracle:*:71:71::0:0:Oracle:/usr/local/oracle7:/sbin/nologin
ircd:*:72:72:IRC daemon:/nonexistent:/nonexistent
ircservices:*:73:73:IRC services:/nonexistent:/nonexistent
ifmail:*:75:66:Ifmail user:/nonexistent:/nonexistent
www:*:80:80:World Wide Web Owner:/nonexistent:/sbin/nologin
alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent
qmaild:*:82:81:QMail user:/var/qmail:/nonexistent
qmaill:*:83:81:QMail user:/var/qmail:/nonexistent
qmailp:*:84:81:QMail user:/var/qmail:/nonexistent
qmailq:*:85:82:QMail user:/var/qmail:/nonexistent
qmailr:*:86:82:QMail user:/var/qmail:/nonexistent
qmails:*:87:82:QMail user:/var/qmail:/nonexistent
mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin
vpopmail:*:89:89:VPop Mail User:/usr/local/vpopmail:/nonexistent
firebird:*:90:90:Firebird Database Administrator:/usr/local/firebird:/bin/sh
mailman:*:91:91:Mailman User:/usr/local/mailman:/sbin/nologin
gdm:*:92:92:GDM Sandbox:/:/sbin/nologin
jabber:*:93:93:Jabber Daemon:/nonexistent:/nonexistent
p4admin:*:94:94:Perforce admin:/usr/local/perforce:/sbin/nologin
interch:*:95:95:Interchange user:/usr/local/interchange:/sbin/nologin
squeuer:*:96:96:SQueuer Owner:/nonexistent:/bin/sh
mud:*:97:97:MUD Owner:/nonexistent:/bin/sh
msql:*:98:98:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh
rscsi:*:99:99:Remote SCSI:/usr/local/rscsi:/usr/local/sbin/rscsi
squid:*:100:100:squid caching-proxy pseudo user:/usr/local/squid:/sbin/nologin
quagga:*:101:101:Quagga route daemon pseudo user:/usr/local/etc/quagga:/sbin/nologin
ganglia:*:102:102:Ganglia User:/nonexistent:/sbin/nologin
sgeadmin:*:103:103:Sun Grid Engine Admin:/nonexistent:/sbin/nologin
slimserv:*:104:104:Slim Devices SlimServer pseudo-user:/nonexistent:/sbin/nologin
dnetc:*:105:105:distributed.net client and proxy pseudo-user:/nonexistent:/sbin/nologin
clamav:*:106:106:Clamav Antivirus:/nonexistent:/sbin/nologin
cacti:*:107:107:Cacti Sandbox:/nonexistent:/sbin/nologin
webkit:*:108:108:WebKit Default User:/usr/local/www/webkit:/bin/sh
quickml:*:109:109:quickml Server:/nonexistent:/sbin/nologin
vscan:*:110:110:Scanning Virus Account:/var/amavis:/bin/sh
fido:*:111:111:Fido System:/usr/local/fido:/bin/sh
dcc:*:112:112:Distributed Checksum Clearinghouse:/nonexistent:/sbin/nologin
amavis:*:113:113:Amavis-stats Account:/nonexistent:/sbin/nologin
dhis:*:114:114:DHIS Daemon:/nonexistent:/sbin/nologin
_symon:*:115:115:Symon Account:/var/empty:/sbin/nologin
postfix:*:125:125:Postfix Mail System:/var/spool/postfix:/sbin/nologin
rbldns:*:153:153:rbldnsd pseudo-user:/nonexistent:/sbin/nologin
sfs:*:171:171:Self-Certifying File System:/nonexistent:/sbin/nologin
agk:*:172:172:AquaGateKeeper:/nonexistent:/nonexistent
polipo:*:173:173:polipo web cache:/nonexistent:/sbin/nologin
bogomilter:*:174:174:milter-bogom:/nonexistent:/sbin/nologin
moinmoin:*:192:192:MoinMoin User:/nonexistent:/sbin/nologin
sympa:*:200:200:Sympa Owner:/nonexistent:/sbin/nologin
dspam:*:202:202:Dspam:/nonexistent:/sbin/nologin
_tor:*:256:256:Tor anonymising router:/var/db/tor:/bin/sh
ldap:*:389:389:OpenLDAP Server:/nonexistent:/sbin/nologin
drweb:*:426:426:Dr.Web Mail Scanner:/nonexistent:/sbin/nologin
courier:*:465:465:Courier Mail Server:/nonexistent:/sbin/nologin
_bbstored:*:505:505::0:0:BoxBackup Store Daemon:/nonexistent:/bin/sh
qtss:*:554:554:Darwin Streaming Server:/nonexistent:/sbin/nologin
ircdru:*:555:555:Russian hybrid IRC server:/nonexistent:/bin/sh
messagebus:*:556:556:D-BUS Daemon User:/nonexistent:/sbin/nologin
bnetd:*:700:700:Bnetd user:/nonexistent:/sbin/nologin
bopm:*:717:717:Blitzed Open Proxy Monitor:/nonexistent:/bin/sh
bacula:*:910:910:Bacula Daemon:/var/db/bacula:/sbin/nologinThis is the current list of reserved GIDs.bind:*:53:
rdfdb:*:55:
spamd:*:58:
cyrus:*:60:
proxy:*:62:
authpf:*:63:
uucp:*:66:
xten:*:67:
dialer:*:68:
network:*:69:
pgsql:*:70:
www:*:80:
qnofiles:*:81:
qmail:*:82:
mysql:*:88:
vpopmail:*:89:
firebird:*:90:
mailman:*:91:
gdm:*:92:
jabber:*:93:
p4admin:*:94:
interch:*:95:
squeuer:*:96:
mud:*:97:
msql:*:98:
rscsi:*:99:
squid:*:100:
quagga:*:101:
ganglia:*:102:
sgeadmin:*:103:
slimserv:*:104:
dnetc:*:105:
clamav:*:106:
cacti:*:107:
webkit:*:108:
quickml:*:109:
vscan:*:110:
fido:*:111:
dcc:*:112:
amavis:*:113:
dhis:*:114:
_symon:*:115:
postfix:*:125:
maildrop:*:126:
rbldns:*:153:
sfs:*:171:
agk:*:172:
polipo:*:173:
moinmoin:*:192:
sympa:*:200:
dspam:*:202:
_tor:*:256:
ldap:*:389:
drweb:*:426:
courier:*:465:
_bbstored:*:505:
qtss:*:554:
ircdru:*:555:
messagebus:*:556:
realtime:*:557:
bnetd:*:700:
bopm:*:717:
bacula:*:910:Please include a notice when you submit a port (or an upgrade)
that reserves a new UID or GID in this range. This allows us to
keep the list of reserved IDs up to date.Do things rationallyThe Makefile should do things simply and
reasonably. If you can make it a couple of lines shorter or more
readable, then do so. Examples include using a make
.if construct instead of a shell
if construct, not redefining
do-extract if you can redefine
EXTRACT* instead, and using
GNU_CONFIGURE instead of CONFIGURE_ARGS
+= --prefix=${PREFIX}.If you find yourself having to write a lot
of new code to try to do something, please go back and review
bsd.port.mk to see if it contains an
existing implementation of what you are trying to do. While
hard to read, there are a great many seemingly-hard problems for
which bsd.port.mk already provides a
shorthand solution.Respect both CC and
CXXThe port should respect both CC
and CXX variables. What we mean by this
is that the port should not set the values of these variables
absolutely, overriding existing values; instead, it should append
whatever values it needs to the existing values. This is so that
build options that affect all ports can be set globally.If the port does not respect these variables,
please add NO_PACKAGE=ignores either cc or
cxx to the Makefile.An example of a Makefile respecting
both CC and CXX
variables follows. Note the ?=:CC?= gccCXX?= g++Here is an example which respects neither
CC nor CXX
variables:CC= gccCXX= g++Both CC and CXX
variables can be defined on FreeBSD systems in
/etc/make.conf. The first example
defines a value if it was not previously set in
/etc/make.conf, preserving any
system-wide definitions. The second example clobbers
anything previously defined.Respect CFLAGSThe port should respect the CFLAGS variable.
What we mean by this is that the port should not set the value of
this variable absolutely, overriding the existing value; instead,
it should append whatever values it needs to the existing value.
This is so that build options that affect all ports can be set
globally.If it does not, please add NO_PACKAGE=ignores
cflags to the Makefile.An example of a Makefile respecting
the CFLAGS variable follows. Note the
+=:CFLAGS+= -Wall -WerrorHere is an example which does not respect the
CFLAGS variable:CFLAGS= -Wall -WerrorThe CFLAGS variable is defined on
FreeBSD systems in /etc/make.conf. The
first example appends additional flags to the
CFLAGS variable, preserving any system-wide
definitions. The second example clobbers anything previously
defined.You should remove optimization flags from the third party
Makefiles. System CFLAGS
contains system-wide optimization flags. An example from
an unmodified Makefile:CFLAGS= -O3 -funroll-loops -DHAVE_SOUNDUsing system optimization flags, the
Makefile would look similar to the
following example:CFLAGS+= -DHAVE_SOUNDConfiguration filesIf your port requires some configuration files in
PREFIX/etc, do
not just install them and list them in
pkg-plist. That will cause
&man.pkg.delete.1; to delete files carefully edited by
the user and a new installation to wipe them out.Instead, install sample files with a suffix
(filename.sample
will work well) and print out a message pointing out that the
user has to copy and edit the file before the software can be made
to work.FeedbackDo 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.README.htmlDo not include the README.html file. This
file is not part of the cvs collection but is generated using the
make readme command.
Marking a port BROKEN, FORBIDDEN, or otherwise not installableIn certain cases users should be prevented from installing
a port. For instance, there may come a time when a particular port
will contain a security vulnerability, will be radically
broken and needs many hours of tender loving care, or is
generally obsoleted, but for one reason or another should
remain in the tree (and get fixed, right?). To tell a user that
a port should not be installed, there are several
make variables that can be used in a port's
Makefile. The value of the following
make variables will be the reason that is
given back to users for why the port refuses to install itself.
Please use the correct make variable as
each make variable conveys radically different meanings to
both users, and to automated systems that depend on the
Makefiles, such as
the ports build cluster,
FreshPorts, and
portsmon.BROKEN is reserved for ports that
do not compile or install. This will prevent users
from wasting their time trying to install the port.
The build cluster will still attempt to try to build
them to see if the underlying problem has been
resolved.FORBIDDEN is used for ports that
do contain a security vulnerability or induce grave
concern regarding the security of a FreeBSD system with
a given port installed (ex: a reputably insecure program
or a program that provides easily exploitable services).
Ports should be marked as FORBIDDEN
as soon as a particular piece of software has a
vulnerability and there is no released upgrade. Ideally
ports should be upgraded as soon as possible when a
security vulnerability is discovered so as to reduce the
number of vulnerable FreeBSD hosts (we like being known
for being secure), however sometimes there is a
noticeable time gap between disclosure of a
vulnerability and an updated release of the
vulnerable software. Do not mark a port
FORBIDDEN for any reason other than
security.IGNORE is reserved for ports that
should not be built for some other reason. The build
cluster will not, under any
circumstances, build ports marked as
IGNORE. For instance, use
IGNORE when a port:compiles but does not run properlydoes not work on the installed version of &os;requires &os; kernel sources to build, but the
user does not have them installedhas a distfile which may not be automatically
fetched due to licensing restrictionsdoes not work with a currently installed portIf a port would conflict with a currently installed
port, use
CONFLICTS instead.
CONFLICTS will set
IGNORE by itself.If a port sould be marked IGNORE
only on certain architectures, there are two other
convenience variables that will automatically set
IGNORE for you:
ONLY_FOR_ARCHS and
NOT_FOR_ARCHS. Examples:ONLY_FOR_ARCHS= i386 amd64NOT_FOR_ARCHS= alpha ia64 sparc64Do remember that BROKEN and
FORBIDDEN are to be used as a
last resort if a port is not upgradeable. Permanently
broken ports should be removed from the tree
entirely.When it makes sense to do so, users can be warned about
a pending port removal with DEPRECATED
and EXPIRATION_DATE. The former is
simply a string stating why the port is scheduled for removal;
the latter is a string in ISO 8601 format (YYYY-MM-DD). Both
will be shown to the user.It is possible to set DEPRECATED
without an EXPIRATION_DATE (for
instance, recommending a newer version of the port), but
the converse does not make any sense.There is no set policy on how much notice to give.
Current practice seems to be one month for security-related
issues and two months for build issues. This also gives any
interested committers a little time to fix the problems.Necessary workaroundsSometimes it is necessary to work around bugs in
software included with older versions of &os;.Some versions of &man.make.1; were broken
on at least 4.8 and 5.0 with respect to handling
comparisons based on OSVERSION.
This would often lead to failures during
make describe (and thus, the overall
ports make index). The workaround is
to enclose the conditional comparison in spaces, e.g.:
if ( ${OSVERSION} > 500023 )
Be aware that test-installing a port on 4.9 or 5.2
will not detect this problem.MiscellaneaThe files
pkg-descr and pkg-plist
should each be double-checked. If you are reviewing a port and feel
they can be worded better, do so.Do not copy more copies of the GNU General Public License into
our system, please.Please be careful to note any legal issues! Do not let us
illegally distribute software!If you are stuck…Do look at existing examples and the
bsd.port.mk file before asking us questions!
;-)Do ask us questions if you have any trouble! Do not just beat
your head against a wall! :-)A Sample MakefileHere is a sample Makefile that you can use to
create a new port. Make sure you remove all the extra comments (ones
between brackets)!It is recommended that you follow this format (ordering of
variables, empty lines between sections, etc.). This format is
designed so that the most important information is easy to locate. We
recommend that you use portlint to check the
Makefile.[the header...just to make it easier for us to identify the ports.]
# New ports collection makefile for: xdvi
[the "version required" line is only needed when the PORTVERSION
variable is not specific enough to describe the port.]
# Date created: 26 May 1995
[this is the person who did the original port to FreeBSD, in particular, the
person who wrote the first version of this Makefile. Remember, this should
not be changed when upgrading the port later.]
# Whom: Satoshi Asami <asami@FreeBSD.org>
#
# $FreeBSD$
[ ^^^^^^^^^ This will be automatically replaced with RCS ID string by CVS
when it is committed to our repository. If upgrading a port, do not alter
this line back to "$FreeBSD$". CVS deals with it automatically.]
#
[section to describe the port itself and the master site - PORTNAME
and PORTVERSION are always first, followed by CATEGORIES,
and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR.
PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that.
Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then
EXTRACT_ONLY, as necessary.]
PORTNAME= xdvi
PORTVERSION= 18.2
CATEGORIES= print
[do not forget the trailing slash ("/")!
if you are not using MASTER_SITE_* macros]
MASTER_SITES= ${MASTER_SITE_XCONTRIB}
MASTER_SITE_SUBDIR= applications
PKGNAMEPREFIX= ja-
DISTNAME= xdvi-pl18
[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) whom 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
COMMENT= A DVI Previewer for the X Window System
[dependencies -- can be empty]
RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript
LIB_DEPENDS= Xpm.5:${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>Automated package list creationFirst, make sure your port is almost complete, with only
pkg-plist missing.Next, create a temporary directory tree into which your port can be
installed, and install any dependencies.
port-type should be local
for non-X ports and x11-4 or x11
for ports which install into the directory hierarchy of XFree86 4
or an earlier XFree86 release, respectively.&prompt.root; mkdir /var/tmp/port-name
&prompt.root; mtree -U -f /etc/mtree/BSD.port-type.dist -d -e -p /var/tmp/port-name
&prompt.root; make depends PREFIX=/var/tmp/port-nameStore the directory structure in a new file.&prompt.root; (cd /var/tmp/port-name && find -d * -type d) | sort > OLD-DIRSCreate an empty pkg-plist file:&prompt.root; touch pkg-plistIf your port honors PREFIX (which it should)
you can then install the port and create the package list.&prompt.root; make install PREFIX=/var/tmp/port-name
&prompt.root; (cd /var/tmp/port-name && find -d * \! -type d) | sort > pkg-plistYou must also add any newly created directories to the packing
list.&prompt.root; (cd /var/tmp/port-name && find -d * -type d) | sort | comm -13 OLD-DIRS - | sort -r | sed -e 's#^#@dirrm #' >> pkg-plistFinally, you need to tidy up the packing list by hand; it is not
all automated. Manual pages should be listed in
the port's Makefile under
MANn, and not in the
package list. User configuration files should be removed, or
installed as
filename.sample.
The info/dir file should not be listed
and appropriate install-info lines should
be added as noted in the info
files section. Any
libraries installed by the port should be listed as specified in the
shared libraries section.Alternatively, use the plist script in
/usr/ports/Tools/scripts/ to build the
package list automatically. The first step is the same as
above: take the first three lines, that is,
mkdir, mtree and
make depends. Then build and install the
port:&prompt.root; make install PREFIX=/var/tmp/port-nameAnd let plist create the
pkg-plist file:&prompt.root; /usr/ports/Tools/scripts/plist -Md -m /etc/mtree/BSD.port-type.dist /var/tmp/port-name > pkg-plistThe packing list still have to tidied up the by hand as
stated above.Keeping UpThe &os; Ports Collection is constantly changing. Here is
some information on how to keep up.FreshPortsOne of the easiest ways to learn about updates that have
already been committed is by subscribing to
FreshPorts.
You can select multiple ports to monitor. Maintainers are
strongly encouraged to subscribe, because they will receive
notification of not only their own changes, but also any
changes that any other &os; committer has made. (These are
often necessary to keep up with changes in the underlying
ports framework—although it would be most polite to
receive an advance heads-up from those committing such changes,
sometimes this is overlooked or just simply impractical.
Also, in some cases, the changes are very minor in nature.
We expect everyone to use their best judgement in these
cases.)If you wish to use FreshPorts, all you need is an
account. If your registered email address is
@FreeBSD.org, you will see the opt-in link on the
right hand side of the webpages.
For those of you who already have a FreshPorts account, but are not
using your @FreeBSD.org email address,
just change your email to @FreeBSD.org, subscribe,
then change it back again.FreshPorts also has
a sanity test feature which automatically tests each commit to the
FreeBSD ports tree. If subscribed to this service, you will be
notified of any errors which FreshPorts detects during sanity
testing of your commits.The Web Interface to the Source RepositoryIt is possible to browse the files in the source repository by
using a web interface. Changes that affect the entire port system
are now documented in the
CHANGES file. Changes that affect individual ports
are now documented in the
UPDATING file. However, the definitive answer to any
question is undoubtedly to read the source code of
bsd.port.mk, and associated files.The &os; Ports Mailing ListIf you maintain ports, you should consider following the
&a.ports;. Important changes to the way ports work will be announced
there, and then committed to CHANGES.The &os; Port Building Cluster on
pointyhat.FreeBSD.orgOne of the least-publicized strengths of &os; is that
an entire cluster of machines is dedicated to continually
building the Ports Collection, for each of the major OS
releases and for each Tier-1 architecture. You can find
the results of these builds at
package building logs
and errors.Individual ports are built unless they are specifically
marked with IGNORE. Ports that are
marked with BROKEN will still be attempted,
to see if the underlying problem has been resolved. (This
is done by passing TRYBROKEN to the
port's Makefile.)The &os; Port Distfile SurveyThe build cluster is dedicated to building the latest
release of each port with distfiles that have already been
fetched. However, as the Internet continually changes,
distfiles can quickly go missing. The FreeBSD
Ports distfiles survey attempts to query every
download site for every port to find out if each distfile
is still currently available. Maintainers are asked to
check this report periodically, not only to speed up the
building process for users, but to help avoid wasting
bandwidth of the sites that volunteer to host all these
distfiles.The &os; Ports Monitoring SystemAnother handy resource is the
-
+
FreeBSD Ports Monitoring System (also known as
portsmon). This system comprises a
database that processes information from several sources
and allows its to be browsed via a web interface. Currently,
the ports Problem Reports (PRs), the error logs from
the build cluster, and individual files from the ports
collection are used. In the future, this will be expanded
to include the distfile survey, as well as other sources.To get started, you can view all information about a
particular port by using the
-
+
Overview of One Port.As of this writing, this is the only resource available
that maps GNATS PR entries to portnames. (PR submitters
do not always include the portname in their Synopsis, although
we would prefer that they did.) So, portsmon)
is a good place to start if you want to find out whether an
existing port has any PRs filed against it and/or any build
errors; or, to find out if a new port that you may be thinking
about creating has already been submitted.
diff --git a/zh_CN.GB2312/books/porters-handbook/book.sgml b/zh_CN.GB2312/books/porters-handbook/book.sgml
index f8fdcae710..1ae9bbac4a 100644
--- a/zh_CN.GB2312/books/porters-handbook/book.sgml
+++ b/zh_CN.GB2312/books/porters-handbook/book.sgml
@@ -1,8995 +1,8995 @@
%books.ent;
]>
FreeBSD Porter 手册The FreeBSD Documentation Project2000 年 4 月200020012002200320042005The FreeBSD Documentation
Project
&bookinfo.trademarks;
&bookinfo.legalnotice;
介绍几乎每个人都是通过 FreeBSD Ports Collection
在 FreeBSD 上面装应用程序 (“ports”)的。
就像FreeBSD的其他部分一样, 它主要来自于志愿者的努力。
所以在阅读这份文档的时候请务必记住这些。在 FreeBSD 的世界里, 任何人都能提交新的 port,
或志愿地维护一个已有的 port, 如果那个 port 没人维护的话 —
不需要任何特殊的权限来做这件事情。自行制作 port那么, 您有兴趣创建自己的 port 或升级现有的 port?
太好了。下面的内容将会提供一些创建FreeBSD port的指导。
如果想升级一个现有的 port, 那么您应该在看完这些内容并阅读
。因为这份文档不是十分详细, 您还应该再参考一下
/usr/ports/Mk/bsd.port.mk, 所有 port
的 Makefile 文件都会包含它。 即使不是每天都去摆弄 Makefile,
您也会从那个文件里面获得很多知识, 里面的注释非常详细。
还有要补充一下,如果您有其他的问题, 可以给&a.ports;
这个 mailing list 发信。在这份文档里提到的大部分的变量
(VAR)
是不能修改的。 大多 (但不是全部) 都在
/usr/ports/Mk/bsd.port.mk
的开始部分进行了介绍; 其他一些也应该可以在那里找到。
注意这些文件使用了非标准的制表符:
Emacs 和
Vim 应该能在打开文件的时候自动识别它,
而 &man.vi.1; 和 &man.ex.1 则需要在打开文件的时候通过
:set tabstop=4 来修正默认的设置。简单的 port这一章主要介绍如何快速创建一个简单的 port。
很多时候, 这点内容是不够的, 您需要阅读这份文档中更深入的内容。首先, 需要取得包含源代码的 tar包, 并把它放到
DISTDIR变量所指的地方。 默认的情况下, 这应该是
/usr/ports/distfiles。下面的内容假定您不需要修改软件的源代码就能在 FreeBSD
上编译通过。 如果需要修改代码, 就需要参考下一章的内容了。编写 Makefile最简单的 Makefile
应该是这个样子的:# New ports collection makefile for: oneko
# Date created: 5 December 1994
# Whom: asami
#
# $FreeBSD$
#
PORTNAME= oneko
PORTVERSION= 1.1b
CATEGORIES= games
MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
MAINTAINER= asami@FreeBSD.org
COMMENT= A cat chasing a mouse all over the screen
MAN1= oneko.1
MANCOMPRESSED= yes
USE_IMAKE= yes
.include <bsd.port.mk>看看您是否能够看懂。 不必担心
$FreeBSD$
那一行, 当这个 port 被导入到 ports 树里的时候,
CVS 会自动填写它。 您可以在
示范的 Makefile那章找到更多的细节。创建描述文件有 2 个描述文件对于任何一个 port 来说是必须的,
不论它是不是打算成为 package。 它们是
pkg-descr 和
pkg-plist。 这两个文件使用 pkg-
前缀以区别于其他文件。pkg-descr (关于 port 的冗长描述文件)这是 port 里一个较长的描述文件。
使用一段或几段文件文字来简明的描述这个 ports 是用来做什么的。这 不是 手册或者对如何
深入使用/编译这个port的说明! 要是您从
README 或者联机手册里面中复制文字的话,
请务必小心; 通常, 它们不是对这个 port
简明扼要的描述, 或者用了难以使用的格式 (比如,
联机手册里有迫使两端对齐的空格)。
如果要移植的软件有官方的WWW网页, 您应该在这里列出来。
使用 WWW: 作为前缀来表示
一个网站,
这样其他的自动工具就能正常工作了。建议您在文件的最后留下您的名字,
就像这样:This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
:
(etc.)
WWW: http://www.oneko.org/
- Satoshi
asami@cs.berkeley.edupkg-plist (port 的装箱单)这份文件列出了 port 安装的所有文件。
之所以也被称为 装箱单 (“packing list”) 是因为 package
的制作就是将这份列表里的文件打包。
这个文件中, 路径是相对于安装的路径的 (通常是
/usr/local 或
/usr/X11R6)。 如果您使用
MANn
变量的话, 请不要在这里列出任何联机手册。下面是一个简单的例子:bin/oneko
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpm
@dirrm lib/X11/oneko参考 &man.pkg.create.1; 的联机手册以获得更多有关装箱单的细节您应该在列表里列出所有的文件而不仅仅是目录名。
如果这个 port 在安装的过程中给自己创建了目录,
则一定要加入 @dirrm 以便在删除这个
port 时能将这些目录也一并删除。建议您将这个文件里的所有的文件名按字母排序。
这样, 在升级这个port的时候就能够更方便地核实所做的修改。手工创建一份这样的文件列表将会是一件非常枯燥的事情。
如果 port 要安装非常多的文件的话, 请参考 自动创建这个文件列表
一节, 会帮您省下不少时间。只有一种情况可以不用 pkg-plist文件。
如果这个 port 只安装很少量的一些文件或目录的话,
这些文件和目录就可以分别列在 Makefile 的
PLIST_FILES和PLIST_DIRS
变量里。 举个例子来说, 我们可以在上面那个
oneko port 里面不用
pkg-plist, 而把下面的这几行加到
Makefile 里面:PLIST_FILES= bin/oneko \
lib/X11/app-defaults/Oneko \
lib/X11/oneko/cat1.xpm \
lib/X11/oneko/cat2.xpm \
lib/X11/oneko/mouse.xpm
PLIST_DIRS= lib/X11/oneko当然, 如果一个 port 不需要给它自己创建目录的话,
就不用设置 PLIST_DIRS 变量了。这样列出 port 要安装的文件很目录的代价就是,
将无法使用在 &man.pkg.create.1; 里面介绍的命令来建立 package。
因此, 这种方法仅仅适合一些简单的 port,
因为它会让这些 port 变得更为简单。 此外,
这样做也有助于减少 port collection 中的文件数量。
请在打算采用 pkg-plist 前考虑一下这个方法。稍后我们将看到 pkg-plist 和
PLIST_FILES 如何处理
更复杂的任务。创建校验和文件只要键入 make makesum,
port 便会自动创建 distinfo文件。如果下载的文件的校验和经常变化,
而您又能确保它们的来源可靠 (比如, 来自于CD制造商,
或每天构建生成的文档文件), 就应该在 IGNOREFILES
里面标明这些文件。 这样, 再运行
make makesum 的时候便不会把这些标记
IGNORE 的文件计算在内了。
测试 port应当确定您的 port 确实做了您希望它们做的事情,
包括打包。下面是需要重点检查的一些重要的工作。pkg-plist 中没有包括任何不想安装的文件pkg-plist 包含了所有应该安装的文件您的 port 能够使用 reinstall
多次安装。您的 port 能在 deinstall 以后自动完成
清理推荐的测试顺序make installmake packagemake deinstallpkg_add package-namemake deinstallmake reinstallmake package确信在 package 和
deinstall 阶段没有任何警告。
第三步以后, 检查是否所有新建的目录都被正确删除了。
在第四步以后, 试着运行一下所装的软件,
确保当它以 package 方式安装的时候也能正常工作。用 portlint 来检查 port请使用 portlint 命令来检查您的
port 是否符合我们的规范。 portlint
程序是 ports collection 的一部分。 另外, 您也许要检查
Makefile
是否符合规范, 以及
package
是否被恰当地命名。提交 port首先, 确信您已经阅读了
该做什么和不该做什么 一节。既然您很满意您的 port, 剩下的工作便是把它放进
FreeBSD 的 ports树, 使得其他的人也喜欢它。 我们不需要您的
work 目录或者
pkgname.tgz 包, 所以现在可以删除它们了。
下一步,只要把
shar `find port_dir`命令的输出
放在一份 bug 报告中, 用 &man.send-pr.1; 程序提交 (请参阅
Bug Reports and General Commentary 以获得更多关于
&man.send-pr.1;的详情。) 如果未压缩的
port 大于 20KB, 您可能希望把它压缩成 tar 包, 并在把它加进
bug报告前使用 &man.uuencode.1; (虽然小于 20KB
的 bug 报告也可以使用采用 uuencode 编码的 tar包,
但是我们并不鼓励这样做。) 确保您的 bug 报告按照 ports
和 change-request 分类, (注意不要把
Bug 报告标记成 机密, 即 confidential 的!)
在 PR 的 Description 一栏里填写一下您的
port 的简单描述, 同时将 shar 或 uuencode 编码的 tar 文件填在
Fix 那一栏。在问题报告里面使用了一段好的描述,
能使我们的工作变得更容易。 我们更倾向于这样的描述:
用 New port: <category>/<portname>
<short description of the port>
来说明这是一个新的 port, 而用
Update port: <category>/<portname>
<short description of the update>
来说明这是对一个已有的 port 的升级。 如果您坚持使用这样的方案,
那么我们将更容易更方便地阅读您的 PR。再次声明, 不要包含原始的distfile,
work目录, 或者您用
make package 制作的包。在您提交的您的 port 以后请耐心等待。
有时在一个 port 正式加入 FreeBSD 之前需要花费好几个月,
尽管也有可能是几天。 您可以查看
正等待被 commit 到 FreeBSD 的 port。一旦我们看过了您的报告, 有必要的话我们会联系您,
并把它放到 ports 树里。 您的名字也会出现在
Additional FreeBSD Contributors
和其他的文件。 不是很棒吗!?
:-)复杂的 Porting好了, 也许工作没那么简单, port 需要做些修改才能够在
FreeBSD 上跑起来。 在这一章里,
我们将会一步步举例来介绍应该如何修改来使您的
port 能在 FreeBSD 上面运行。整个系统是如何运转的?首先, 这一系列的动作是由用户在您的
port 目录里敲入 make 后发生的。
您也许会发现在另外的一个窗口里阅读一下
bsd.port.mk 将会有助于您的理解。要是您不是非常明白 bsd.port.mk
是做什么的话, 也不用太担心, 很多人都不知道的...
:->fetch 会首先被执行。
fetch 将检查在本地的
DISTDIR 目录里是否存在
tar 包。 如果 fetch
没有找到就会查找 Makefile 中定义的
MASTER_SITES URL, 还有我们的主
FTP 站点 ,
在那里我们备份了所有被认可的 distfile。 假设那个
MASTER_SITES 站点是直接连在 Internet 上的,
就会试着用 FETCH 指定的程序取回
distfile。 如果成功的话, 文件会被保存在DISTDIR
所指定的目录以备稍后使用。接下来会执行 extract。
它会在 DISTDIR 中寻找您的
tar 包 (通常是用 gzip 压缩的 tar 包),然后解压缩到由
WRKDIR 所指定的临时目录里
(默认为work目录)。下一步是执行 patch。
首先任何在 PATCHFILES 中定义的补丁都会被打上。
然后, 在由 PATCHDIR 指定的目录
(默认为 files目录)
中发现的patch-*,
它们将会以文件名的字母顺序被先后打上。configure会被执行。
这一步骤可能会有以下几种情形。如果存在 scripts/configure,
就会执行它如果定义了 HAS_CONFIGURe
或者 GNU_CONFIGURE, 就会执行
WRKSRC/configure。如果定义了USE_IMAGE, 就会执行
XMKMF (默认为: xmkmf
-a)。build会被执行。
这一步将会进入ports的工作目录
(WRKSRC)
然后进行编译。如果定义了USE_GMAKE,
就会使用 GNU make, 反之,
则会使用系统默认的 make。以上都是系统默认的步骤。 您也可以定义
pre-something 或者
post-something,
或者把以此命名的脚本放到
scripts 目录,
它们会在默认的动作之前或之后被执行。举个例子, 如果您在您的 Makefile
里定义了post-extract, 并在
script 目录里放了一个
pre-build 脚本,
那么在 tar 包解开之后
post-extract 将被调用,
pre-build 脚本会在默认的编译之前被执行。
我们推荐您在 Makefile
定义所有的动作, 如果不是十分复杂的话,
这样, 别人能更容易明白您的 port
需要执行哪些非默认的动作。默认的行为都是由 bsd.port.mk 定义的
do-something
来表示的。 例如, port 中用来解压缩的命令是由
do-extract 来定义的。
如果您对默认的设置不满意, 可以通过在
Makefile 重新定义
do-someting
来做些改变。主 动作 (例如
extract、
configure, 等等)
仅仅是用来确定所有相应的阶段都完成了,
以及调用真实的动作或脚本, 它们不应被修改。
如果您想要修改解压缩这个动作,
可以修改 do-extract,
但永远都不要改变 extract
的操作!我们已经介绍了在用户敲入 make
之后会发生哪些事情了。 接下来我们将进行进一步的学习,
来看一看如何创建一个理想的 port。获取源代码获取源代码的 tar 包 (通常是
foo.tar.gz 或者
foo.tar.Z) 并把它们放进
DISTDIR。 最好使用 主流 的版本。您需要设置变量 MASTER_SITES
来指向原始 tar 包的获取位置。 您可以在
bsd.sites.mk
里找到一些速度较快的主流站点。 请使用这些站点 —
和相关的定义 — 如果可能的话,
应尽量避免在同一个源代码树里出现大量重复的信息。
这些站点会随着时间而变化,
如果每个人都随意加入的话会使维护变得非常困难。如果您找不到一个有很好网络连接的
FTP/HTTP 站点, 或者它们使用了非标准的格式,
您也许就会想在您自己的 FTP 或 HTTP
服务器上放上一份副本。如果您找不到可靠的地方放置 distfiles,
我们也可以提供给您一些空间来保存它。
我们自己的 ftp.FreeBSD.org;
然而这只是一个折衷的办法。 distfile 必须放进某人在
freefall 上的
~/public_distfiles/
目录中。 可以要求帮助您 commit port 的人来放这个
distfile, 而这个人也需要把 MASTER_SITES、
MASTER_SITE_LOCAL 以及
MASTER_SITE_SUBDIR 的设置,
改为在 freefall 上的用户名。如果您的 port 的 distfile 一直在变化,
而作者拒绝改变其版本号, 您可以考虑把 distfiles
放在自己的主页, 并在 MASTER_SITES
里把原作者的列为首选位置。 如果可能, 试着与 port
的作者沟通一下让他不要这么做, 这将有助于建立对源代码的控制。
在您的主页上放置您自己的 distfile 会避免用户得到
checksum mismatch
的错误, 而且能减轻我们 FTP 站点维护人员的工作量。
如果您的port只有一个主站点的话, 我们建议您在自己的网站上做一份备份,
并他列为 MASTER_SITES的第2项。如果您的 port 需要来自网络上的一些补丁, 请把它们放到
DISTDIR里。 不用担心它们跟源代码不是来自同一站点。
我们有办法处理 (参阅下面的
补丁文件)。修改 port解开 tar 包, 对源代码做出合理的修改使得这个 port
能在最新版本的 FreeBSD 上面运行。
一定要 仔细记录 您所做的每处改动,
包括删除、添加、修改的文件等等, 这些修改以后会在您的 port
中以脚本或补丁的方式出现, 并且能通过运行它们来自动完成您对
port 的改动要求。如果您的 port 要求用与用户交互/配置来完成编译或安装的话,
您可以看一下 Larry Wall 的经典的 Configure
脚本, 适当地模仿一下。 Port collection 的目的,
就是使每个 port 占用最少的空间,
并做到软件的 即插即用。除非明确地声明, 否则您提交给
FreeBSD ports collection 的补丁,
脚本和其他的文件都将被假定以标准的 BSD 版权发布。打补丁在您制作 port 的过程中, 文件的添加或修改都可以用
&man.diff.1; 做成补丁, 使得今后的能够使用 &man.patch.1;
在安装过程中自动对 port 做出相应的修改。
每一个您想要打的补丁应该以
patch-*
这样形式的文件名保存, *
表示将要被打补丁的文件名,
例如 patch-Imakefile
或 patch-src-config.h 这样。
这些文件应该被放在 PATCHDIR 里,
这样这些补丁都会被自动打上。
所有的补丁必须相对于 WRKSRC 的
(port 会把 tarball 解压缩在那里, 并完成余下的其他动作)。
为了使修改和升级变得更容易, 应避免使用多个
patch 去修改同一个文件 (比如,
patch-file 和 patch-file2
都修改 WRKSRC/foobar.c
就应被避免)。只有 [-+._a-zA-Z0-9] 这些字符,
可以出现在补丁的文件名中, 请务必不要使用除这些字符以外的其他字符。
不要把您的补丁命名成 patch-aa
或 patch-ab 等这样的名字,
最好能在补丁名中提到路径和文件名。不要把 RCS 字符串放进补丁。 我们把文件放进 ports
树的时候, CVS 会损坏它们, 当我们再 check out 出来的时候,
它们就会和原来的不一样, 从而导致打补丁失败。 RCS 字符串
是由美元符号 ($) 围绕的,
通常由 $Id 或
$RCS 开头。使用 &man.diff.1; 的递归选项()
很好, 但是请检查一下最后输出的 patch,
确保没有任何的垃圾信息。 特别地, 有 2 种文件不需要 diff,
并且应该删除: 一种是 Makefile,
当您的port使用了Imake,
或者 GNU configure 等等的话。
如果您不得不编辑configure.in
以使 autoconf 去生成
configure, 不要使用
configure 来做 diff
(这常常会有好几千行长!); 请定义
USE_AUTOCONF_VER=213 并对应
configure.in 来制作 diff。往往在移植某个软件的时候会遇到这样一种情况,
特别是这个软件是在 &windows; 上开发的时候,
大多数的源代码都需要进行CR/LF的转换。
这也许会给以后打补丁, 编译警告、 脚本执行造成问题 (
/bin/sh^M not found) 等等。
您能加入以下这行代码来快速地把那些文件从
CR/LF 转换到 LF:USE_REINPLACE= yes
post-extract:
@${FIND} -E ${WRKDIR} -type f -iregex ".*\.(c|cpp|h|txt)" -print0 | \
${XARGS} -0 ${REINPLACE_CMD} -e 's/[[:cntrl:]]*$$//'当然, 如果您想要处理所有文件的话,
就可以省略上面的 选项。
请注意这段代码会从被处理文件的每一行里面剔除所有的控制字符。
(但不包括 \n)。假如需要删除文件, 您可以在
post-extract 里面做这件事,
而不是在把它作为一个补丁。 一旦您对您所做修改的感觉比较满意,
那么请把diff输出分成一个补丁对应一个源文件。配置把任何附加的配置命令加进您的
configure 脚本并把它保存到
scripts 子目录。 如前面提到的那样,
您也能在 Makefile 和/或
使用 pre-configure 或
post-configure 的脚本来做同样的事情。处理用户输入如果您的 port 要求用户的输入以便配置编译、 或安装配置过程,
就必须在 Makefile 里设置
IS_INTERACTIVE 变量。
如果用户设置了 BATCH 的话,
这将让用户能跳过您的 port 来完成
通宵编译 (如果用户设置了
INTERACTIVE的话, 那么 只有
那些要求互动的 port 才会被编译)
这将给那些不停编译 ports 的机器省下很多时间。通常我们还建议,
如果对于那些问题能有合理的缺省答案的话, 应检查一下
PACKAGE_BUILDING 变量,
并根据其设置决定是否执行关闭交互脚本。
这将允许我们为 CDROM 和 FTP 来编译 package。配置 Makefile配置 Makefile 是相当简单的,
我们在此建议您在开始之前看一下现有的例子。
在这份手册里也有一个
Makefile例子,
照着里面变量的顺序来写能使得您的 port
更容易地被其他人看懂。现在, 当您开始编写您新的Makefile
的时候, 可以依次思考一下以下的问题:作者发布的代码放在 DISTDIR 中的是不是标准的用 gzip 压缩的
tar 包, 例如 foozolix-1.2.tar.gz?
如果是, 可以先略过这一节。 如果不是,
您应当看看是不是要覆盖这些变量: DISTVERSION、
DISTNAME、
EXTRACT_CMD、
EXTRACT_BEFORE_ARGS、
EXTRACT_AFTER_ARGS、
EXTRACT_SUFX,
DISTFILES,取决于您 port 的 distfile
格式有多么怪异。 (最常见的一个例子便是
EXTRACT_SUFX=.tar.Z, 一般这是因为 tar
包是用 compress 而不是
gzip 压缩的时候。)最糟的情况是, 您需要自己编写
do-extract
来覆盖默认的定义, 尽管这不常见,
但如果遇到了, 还是需要这么做。命名Makefile 的第一部分便是 port
的名字、 版本号, 以及它所属的分类。PORTNAME 和 PORTVERSION您应该把 PORTNAME 设置为您
port 的名字, PORTVERSION
则是 port 的版本号。PORTREVISION 和
PORTEPOCHPORTREVISION (port 的修订版本号)PORTERVISION
变量是一个单调递增的值, 如果不为
0, 就会被加到包名的后面,
当 PORTVERSION 增加
的时候应被置 0 (也就是当官方有新版本发布的时候)。
PORTREVISION
会被自动化工具 (比如 &man.pkg.version.1;)
用来检测是否存在可用的新版本。每当 port 发生变化并对生成的
package 的内容或结构有显著影响时,
都应增加 PORTREVISION
值。下面是一些应当修改 PORTREVISION
的情况:有新的补丁用来修正安全漏洞、
错误, 或给 port 添加了新的功能。修改了 Makefile
里编译时开启或禁用的选项。修改了要安装文件的列表或安装时的行为
(例如, 修改了一个用来给 package
初始化数据的脚本, 如 ssh host keys)。一个port依赖的共享库版本改变
(在这种情况下, 当安装了新版本的共享库,
后再去安装较早的软件就会出错,
因为它们要依赖老的 libfoo.x
而不是libfoo.(x+1))。原作者修改了 port distfile, 并且 distfile
的新老版本之间用
diff -ru 只能发现一些细微的变化,
这时我们只需要对
distinfo 做相应的修正,
而不需要修改
PORTVERSION。不需要修改
PORTREVISION 的例子:port 结构风格的改变,
但对于打成的包没有功能的上的变化。MASTER_SITES
发生变化, 或进行了对 port 功能的修改,
但不致影响最后打成的包。对 distfiles 诸如修正拼写错误之类的补丁,
对用户而言没有升级上的麻烦。对一个原本编译失败的包的修改,
使其可编译, 而没有加入新功能。 因为
PORTREVISION
表示包的内容发生了变化,
如果先前没有可编译的包, 也就不需要修改
PORTREVISION
来表示变化。一个修改并提交 port 的原则是:
使得别人能从中受益 (改进、 修改已有错误,
或使新的 package 能够运行),
您还要权衡一下这是否应让那些经常更新
ports 树的人升级,
如果回答是 是 的话,
PORTREVISION
就应该修改了。PORTEPOCH (port 的加权版本号)有时软件商或 FreeBSD 的
porter 会使用比旧版的版本号小的数字做为新版本号的情况。
举例来说, 从
foo-20000801 到 foo-1.0 (从形式上来说这是不对的,
因为 20000801 在数值上比1大很多)。在这种情况下, PORTEPOCH
应当增加。 如果
PORTEPOCH 非 0,
就应当加到包名字的后面。
PORTEPOCH
永远不能被减少或清零,
因为那样会导致与前一时期的 package
比较版本时产生不正确的结果。
(就是说, 那个 package 就不会被检测到已经过时了。)
新的版本号 (比如前面在前面那个例子中的
1.0,1) 在数值上比前一个版本
(20000801) 小, 但多数自动化的工具会认为
,1
后缀意味着比前一个包的后缀 ,0 大。错误的去除或重置
PORTEPOCH
会导致很多不幸发生; 如果您还不明白前面的讨论,
请多阅读几次直至明白为止,
或到邮件列表上来提问。大多数 port 都不会用到
PORTEPOCH,
并且如果某个软件的下一个版本改变了版本号结构的话,
用巧妙的方法来设定 PORTVERSION
也能避免使用 PORTEPOCH。 然而,
FreeBSD porter 也需要注意, 当有新版本的软件发布,
但并非正式版本时 — 比如
snapshot 版本,
原作者可能会使用当时的日期来命名,
这在新的 官方 版本发布的时候,
就很容易引起前面提到的问题。举个例子, 如果 snapshot 版本的发布日期是
20000917, 这个软件的上一个版本是1.2,
那么这个版本的 PORTVERSIN 应该设为
1.2.20000917 或类似的样子, 而不是20000917,
这样在 1.3 发布以后,
新版本就可以在数值上大于旧的版本了。关于 PORTREVISION 和
PORTEPOCH 的用例gtkmumble port,版本号
0.10, 被提交到
ports collection:PORTNAME= gtkmumble
PORTVERSION= 0.10PKGNAME 变成
gtkmumble-0.10。然后有人发现了一个安全漏洞,
需要用一个FreeBSD的补丁。 PORTREVISION
就要相应的增加。PORTNAME= gtkmumble
PORTVERSION= 0.10
PORTREVISION= 1PKGNAME变成了
gtkmumble-0.10_1软件的作者发布了新的版本, 版本为
0.2 (作者本来的意思是,
用 0.10 表示
0.1.0,而不是指
0.9 之后的那个版本 - 但是现在太迟了)。
因为现在的次版本号 2
在数值上比上一个版本 10 小,
PORTEPOCH 必须增加,
以使新的 package 被认为是 更新的。
由于那是作者发布的一个新版本, 因此
PORTREVISION 应被置0 (或者从
Makefile 里面删除它)。PORTNAME= gtkmumble
PORTVERSION= 0.2
PORTEPOCH= 1PKGNAME 变成了
gtkmumble-0.2,1下一个版本将会是 0.3。
由于 PORTEPOCH 从不减少,
那么就无须改动:PORTNAME= gtkmumble
PORTVERSION= 0.3
PORTEPOCH= 1PKGNAME 变成
gtkmumble-0.3,1如果在这次升级中 PORTEPOCH
被置为了0, 那么在装了
gtkmumble-0.10_1 包的机器上就无法检测到
gtkmumble-0.3 包的更新,
因为 3 在数值上比
10 小。 记住, 这是
PORTEPOCH 最重要的地方。PKGNAMEPREFIX 和 PKGNAMESUFFIX2 个可选的变量, PKGNAMEPREFIX 和
PKGNAMESUFFIX 可以和
PORTNAME 还有
PORTVERSION 配合使用,
形成像这样的 PKGNAME:
${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}。
请确定符合我们的
包命名规则。
当然, 不 允许在
PORTVERSION
中使用连字符 (-)。 如果包名有
language- 或
-compiled.specifics 部分 (见下文),
请分别用 PKGNAMEPREFIX 和
PKGNAMESUFFIX, 不要直接加到
PORTNAME 中。包命名规则以下是您在命名您的包时应当遵守的规则。
这将使得我们放包的目录更利于浏览,
因为我们已经有数以万计的包了,
如果用户觉得查看包名很困难的话,
他们会很快走开的。一个包的名字应该看起来像这样:
language_region-name-compiled.specifics-version.numbers。要像这样来定义包的名字:
${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}。
确保所有的变量符合上面的格式。FreeBSD 会尽力去支持用户当地的语言。
如果这个 port 是某种语言专用的, 那么
language- 部分应该是
由 ISO-639 定义的自然语言的 2 个字母缩写。 比如,
ja是表示日本, ru
是表示俄罗斯, vi 表示越南,
zh 表示中国, ko
表示韩国, de 表示德国。如果是针对某种语言的某一地区的话,
再要加上2个字母的国家代码。 例如,
en_US 表示美国英语,
fr_CH 表示瑞士法语。language- 部分应该在
PKGNAMEPREFIX 变量里设置。name 部分的首字母应该
小写。 (余下的部分能包含大写字母, 所以当您
要转换一个包含大写字母软件的名字时, 您需要
自己做出判断。) 对于perl 5
模块的命名, 有个传统的规则是, 在前面
加上 p5-
并把两个冒号的部分改为连字号, 如:
Data::Dumper 模块变成
p5-Data-Dumper。
如果软件的名字里还有数字、 连字号、 下划线,
您也可以把这些包括进来 (例如 kinput2)。如果这个 port 能将不同的默认设置
硬编码
进程序 (通常是部分的目录名), 那么
-compiled.specifics
应该声明被编译进去的默认设置 (连字号是可选的)。
这样的用例包括纸张大小和不同的字体。-compiled.specifics
部分应该在 PKGNAMESUFFIX
变量里设置。版本号应该紧随在连字号
(-) 后面并由数字和字母组成。
特别指出, 另外的连字号是不允许出现在版本号里的。
唯一例外的是字符串 pl
(表示 patchlevel),
只能
用在软件没有主版本号和次版本号的情况下。
如果软件的版本号里出现了像
alpha, beta,
rc, pre,
取第一个字母把它放在小数点的后面。
如果在版本号里一直出现那些名字,
那么在数字和字母之间不应有多余的小数点。这个方法是为了更容易得凭版本号来排序 port。
特别注意的是, 确保版本号之间的每部分都由小数点来分隔,
如果日期也是版本号的一部分, 就用这样的格式,
yyyy.mm.dd
或者
dd.mm.yyyy
这样的格式, 而非
yy.mm.dd,
因为后者不适合表示千年的格式。这里是一些真实的例子,
我们藉此说明如何把软件作者对软件的命名,
转换为适合我们包的命名方式:发行版的名字PKGNAMEPREFIXPORTNAMEPKGNAMESUFFIXPORTVERSION说明mule-2.2.2(空)mule(空)2.2.2没什么需要修改的XFree86-3.3.6(空)XFree86(空)3.3.6没什么需要修改的EmiClock-1.0.2(空)emiclock(空)1.0.2程序的名字不能使用大写字母rdist-1.3alpha(空)rdist(空)1.3.a像 alpha
这样的字符串是不允许出现的es-0.9-beta1(空)es(空)0.9.b1像 beta
这样的字符串是不允许出现的mailman-2.0rc3(空)mailman(空)2.0.r3像 rc
这样的字符串是不允许出现的v3.3beta021.src(空)tiff(空)3.3那个是啥鬼东西?tvtwm(空)tvtwm(空)pl11总需要有个版本号吧piewm(空)piewm(空)1.0总需要有个版本号吧xvgr-2.10pl1(空)xvgr(空)2.10.1pl 只允许在没有
主/次 版本号的情况下才能出现gawk-2.15.6ja-gawk(空)2.15.6日文版psutils-1.13(空)psutils-letter1.13纸张大小已经在编译的时候被硬编码到程序里了pkfonts(空)pkfonts3001.0300dpi 字体的包如果在原始的代码里没有版本号,
或者原作者并不打算开发另外的版本,
就应把版本号设成 1.0 (就像前面
piewm 的例子那样)。 否则,
要求原始的作者加上版本号或使用日期
(yyyy.mm.dd)
来作为版本号。分类CATEGORIES (所属分类)在包制作完成之后,
它会被放在 /usr/ports/packages/All,
并建立一系列来自
/usr/ports/packages
下子目录的符号连接。 这些子目录的名称是由
CATEGORIES
指定的。 这将方便于那些用户在 FTP 站点或 CDROM
的一大堆包里面寻找自己想要的包。 请查看一下
目前的分类表,
并找出一个适合您 port 的分类。此列表也会决定您的 port 在 port
目录中的位置。 如果您在这里设定了 1 个以上的分类,
则认为您 port 文件应放到以第一个分类命名的子目录中。 请参阅
后面
关于如何选择正确分类的更多讨论。目前的分类表这是目前 port 中的分类。 那些用星号
(*) 标记的是
虚拟分类 —
它们在ports树里没有相应的子目录,
因而只用来做为次要的分类, 用以方便搜索。对于非虚拟的分类来说,
您会看到在相对应子目录中的 Makefile
里有写在 COMMENT 里的单行描述。分类描述注意事项accessibility帮助残障人士的 port。afterstep*对于
AfterStep
窗口管理器的支持。arabic阿拉伯语言支持。archivers压缩与备份工具。astro有关天文学的 port。audio声音支持。benchmarks测评程序。biology生物学相关的软件。cad计算机辅助设计工具。chinese中文语言支持。comms通讯软件。大部分是用于串口通讯的。converters字符编码转换。databases数据库。deskutils在发明计算机以前就已经在桌面上使用的东西。devel程序开发工具。不要把开发库放在这里 —
除非您再也找不到更合适的分类,
否则就不该放在这个分类里。dnsDNS 相关的软件。editors通用编辑器。有特殊用途的编辑器应该被置于相应的分类中
(比如, 数学-方程式
编辑器应该放在 math 分类里。elisp*Emacs-lisp相关的port。emulators其他操作系统的模拟器。终端模拟器 不应该
属于这个分类 — 基于 X 的应该放在
x11 而基于文本模式的应该放到
comms 或 misc
中去, 取决于具体的功能。finance货币、 金融以及相关的应用程序。french法语语言支持。ftpFTP 客户端和服务器端的程序。如果您的 port 同时支持 FTP 和 HTTP 的话,
把它放进 ftp 并把
www 做为第二分类。games游戏。german德语语言支持。gnome*关于
GNOME
项目的支持。graphics图形图象程序。haskell*有关 Haskell 编程语言的软件。hebrew希伯来语语言支持。hungarian匈牙利语语言支持。ipv6*IPv6 相关软件。ircIRC 相关程序japanese日语语言支持。java有关 Java 编程语言的软件。java 分类对于一个
port 来说并不是唯一的分类。
最好用来放和 Java 语言相关的 port,
而且我们鼓励不要把 java
做为一个 port 的主分类。kde*K 桌面环境 (KDE)
相关的软件。korean韩语语言支持。lang编程语言。linux*Linux 相关的应用程序。lisp*和 Lisp 编程语言有关的软件。mail电子邮件软件。math数值计算和其他数学相关的软件。mboneMBone 应用程序。misc各式各样的实用程序。通常不属于其他的任何分类,
如果可能的话, 尽量为您的 port 选择
misc
以外的分类, 因为在这里的
port 比较容易被人忽略。multimedia多媒体软件。net各种网络相关的软件。net-mgmt网络管理软件。newsUSENET新闻组相关软件。offix*OffiX 相关套件。palmPalm™ 系列相关软件。parallel*并行计算相关软件。pear*Pear PHP 架构相关软件。perl5*Perl5 相关的软件。plan9*Plan9 相关程序。polish波兰语语言语言支持。portuguese葡萄牙语语言支持。print打印相关的软件。桌面出版工具 (打印预览工具等等)
也可以放在此分类里。python*Python 编程语言相关的软件。ruby*Ruby 编程语言相关的软件。russian俄语语言支持。science科学相关但不适合放在
astro、
biology, 以及
math 分类的 port。security安全相关的实用程序。shells命令行 shell。sysutils系统相关的实用程序。tcl76*依赖于 Tcl 7.6 版运行的 port。tcl80*依赖于 Tcl 8.0 版运行的 port。tcl81*依赖于 Tcl 8.1 版运行的 port。tcl82*依赖于 Tcl 8.2 版运行的 port。tcl83*依赖于 Tcl 8.3 版运行的 port。textproc文本处理的实用程序。这个分类并不适合于那些应该放到
print 的桌面出版工具。tk42*依赖于 Tk 4.2 版运行的 port。tk80*依赖于 Tk 8.0 版运行的 port。tk81*依赖于 Tk 8.1 版运行的 port。tk82*依赖于 Tk 8.2 版运行的 port。tk83*依赖于 Tk 8.3 版运行的 port。tkstep80*需要 TkSTEP 8.0 来运行的 port。ukrainian乌克兰语语言支持。vietnamese越南语语言支持。windowmaker*WindowMaker 窗口管理器的相关支持。wwwWord Wide Web的相关软件。HTML语言相关的支持也可以放在这个分类里。x11X Window System以及相关软件。这个分类是给那些直接支持X Window System
的软件的。 不要把常规的 X 应用程序也放进这里;
它们中的大多数都应被归类到
x11-* (参见下文)。
如果您的 port 是
X 应用程序, 应定义 USE_XLIB
(使用 USER_IMAKE 隐含包括它),
然后把它放到合适的分类里。x11-clocksX11 下的时钟程序。x11-fmX11 下的文件管理器。x11-fontsX11 下的字体以及相关工具。x11-serversX11 服务器。x11-toolkitsX11 工具包。x11-wmX11 窗口管理器。zope*Zope 相关的支持。选择正确的分类由于不少分类是重复的, 您通常在用哪个分类作为您
port 的主分类上做出选择。 下面有几条规则能帮您解决这个问题。
这是一个带优先级的表, 按优先级降序罗列:第一个分类必须是个物理的分类 (参阅
前面)。
这对于制作包是必要的。
虚拟分类和物理分类可能在包制作完成后混合在一起。对于特定语言的分类通常放在第一位。
例如, 如果您的 port 会安装一些 X11 的日文字体,
那么 CATEGORIES那行
就应该是 japanese x11-fonts。有特定意义的分类应当被列在无特定意义的前面。
例如, HTML 编辑器应该是这样的 www
editors, 而不是其他的什么。 同样地,
您不应该列出 net, 如果 port 属于
irc、 mail、
mbone、 news、
security, 或是 www,
因为 net 可以表示它们的超集。只有当主要的分类是一门自然语言的时候,
x11 能被做为第二分类。
需要特别指出的是, 您不应把 X 的应用程序也归类为
x11。Emacs
模式应当于相应的应用程序放在同一个分类里, 而不是
editors 分类。 举例来说,
一个用于编辑某种编程语言源代码的
Emacs
模式应该被归为
lang 一类。
misc
分类的 port 不能有其他非虚拟的分类。
如果您在您的 CATEGORIES
里设了 misc 和另外的分类,
那意味着可以安全地删除 misc
并把 port 放到其他的子目录中了!如果您的 port 确实不属于现有的分类,
才把它放到 misc。如果您不能确定使用哪个分类, 请在您提交的
&man.send-pr.1; 里加上一行注释,
这样我们就能在导入进 port 树之前讨论一下。
如果您是 committer, 发一份备忘到 &a.ports;
先讨论一下。 很多情况是新的 port 被加到错误的分类里,
然后又立即被移走。这会造成源代码库不必要和不良的膨胀。提议建立新的分类由于 Ports Collection 在持续增长, 已经引入了许多新的分类。
新的分类既可以是 虚拟的 分类 —
这些分类在整个 ports 目录中没有属于自己的子目录 —
或 物理的 分类 — 它们有自己的子目录。
接下来我们将讨论与建立新的物理分类有关的事项,
以便帮助您理解如何提议建立新的分类。我们目前的做法是避免建立新的物理分类, 除非有非常多的 port
应被归入这一分类, 或者 port 属于某一特定的小团体 (例如,
与某种人类语言相关), 或两者皆是。这样做的原因是这类修改会让 committer 和用户都不得不进行 许多工作
来在 Ports Collection 进行或追踪修改。 此外,
提议新的分类通常都会引起争论。 (可能这是因为关于某个分类是否
太大 一直没有非常一致的意见的缘故,
另一方面, 分类是否能够能够有助于浏览 (以及多少个分类是合适的),
等等, 也都是问题。)下面是具体的步骤:在 &a.ports; 提议新的分类。 您应提供建立新分类的详细依据,
包括为什么认为现有的分类不够, 以及希望移动位置的一系列 port
的名字。 (如果有尚在
GNATS 而未 commit 的 port,
也应一一列出。) 如果您是相关 port 的监护人或提交者,
说明这一情况可能有助于您的提议得到通过。参与讨论。如果有人支持您的建议, 应及时提交一个 PR,
其中包括提议 PR 的理由, 以及需要移动的 port 的列表。
理想情况下, 这个 PR 也应包含针对下列文件的补丁:进行 repocopy 之后对 Makefile
进行的修改新分类的 Makefile旧分类的 Makefile依赖于旧 port 的 port 的
Makefile(此外, 作为一项加分因素,
您还可以提供一些其它需要修改的文件,
按照 Committer 指南所介绍的流程。)由于这是一项影响 ports 基础设施的变动,
它不仅涉及 repo-copy 的使用,
而且也可能会影响构建集群的衰退测试操作,
因此这类 PR 应分派给 &a.portmgr;。如果这一 PR 得到批准, 某个 committer 将按照在
Committer 指南 中所介绍的步骤来完成余下的工作。提议新的虚拟分类和上述过程类似, 但会容易许多,
因为不需要实际地移动任何 port。 这种情况下, PR 应附带的补丁,
就只需要修改影响到的 port 的 Makefile, 以便在其中的
CATEGORIES 中加入新的分类了。提议对分类进行重新组织有些时候会有一些人提议重新将分类组织为 2-层 或某种基于关键字的结构。
目前为止, 还没有进行任何相关的改变, 因为尽管这些修改比较容易完成,
但修改整个 Ports Collection 所需要进行的工作, 至少也是令人生畏的。
在发表您的观点之前, 请阅读在邮件列表存档中历史上所进行过的提议;
此外, 您也会被要求提供一个可用的原形。源码包文件在 Makefile 中的第二部分是描述用于构建 port
所必需下载的文件, 以及到什么地方去下载它们。DISTVERSION/DISTNAME (源码包版本号/名称)DISTNAME 是作者称呼您所 port 软件的名字。
DISTNAME 的默认值是
${PORTNAME}-${PORTVERSION},
因此只有在需要时才应手工指定。
DISTNAME 只在两个地方用到。 第一处是源码包文件列表
(DISTFILES), 其默认值是
${DISTNAME}${EXTRACT_SUFX}。
第二处是源码包应被展开到的目录名,
即 WRKSRC 所指定的目录,
其默认值是 work/${DISTNAME}。某些软件作者发布源码包的时候并不采取
${PORTNAME}-${PORTVERSION} 这样的模式,
这可以通过设置 DISTVERSION 来自动处理。
PORTVERSION 和 DISTNAME
会自动地展开, 当然, 也可以改掉它。 下表给出了一些例子:DISTVERSIONPORTVERSION0.7.1d0.7.1.d10Alpha310.a33Beta7-pre23.b7.p28:f_178f.17PKGNAMEPREFIX 和
PKGNAMESUFFIX 并不影响
DISTNAME。 此外还应注意
WRKSRC 等于
work/${PORTNAME}-${PORTVERSION},
而源代码的压缩包则可能是
${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}
以外的其它名字。 一般情况下应该保持 DISTNAME
不变 — 更好的方法是定义
DISTFILES 而不是同时设置
DISTNAME 和 WRKSRC
(可能还有 EXTRACT_SUFX)。MASTER_SITES (主流下载站点)记录 FTP/HTTP-URL 指向 MASTER_SITES
中原始压缩档的目录部分。 不要忘了结尾的斜线
(/)!make 宏将尝试使用
FETCH 来抓取所指定的源码包文件,
如果无法在本地系统中找到这些文件的话。建议您指定多个镜像站点, 最好是在不同的大洲上的。
这样将有效地防止由于大范围网络问题所导致无法下载的问题。
我们甚至打算增加自动检测距离最近的站点并从那里下载的功能;
使用多个站点是这样做的重要一步。如果原始的源码包是流行的软件,
例如 X-contrib、 GNU, 或 Perl CPAN 等等之一,
您可能会希望使用
MASTER_SITE_*
(例如 MASTER_SITE_XCONTRIB 和
MASTER_SITE_PERL_GNU) 来简化撰写。 简单地将
MASTER_SITES 设置为这些变量之一, 并使用
MASTER_SITE_SUBDIR 来指定路径就可以达到目的。
下面是一个例子:MASTER_SITES= ${MASTER_SITE_XCONTRIB}
MASTER_SITE_SUBDIR= applications这些变量是在
/usr/ports/Mk/bsd.sites.mk 中定义的。
新项目会随时增加, 因此在您提交 port 之前,
应先看一看这个文件的最新版本。用户也可以在他们的 /etc/make.conf
文件中自行设置 MASTER_SITE_* 变量,
以便让系统使用他们的选择, 从他们喜欢的镜像站点进行下载。EXTRACT_SUFX (压缩包所用的扩展名)如果您有一个源码包文件,
而它使用了某种怪异的扩展名来表达压缩方法, 应设置
EXTRACT_SUFX。例如, 如果源码包文件的名字是
foo.tgz 而非更为一般的
foo.tar.gz, 您应写上:DISTNAME= foo
EXTRACT_SUFX= .tgzUSE_BZIP2 和 USE_ZIP
变量会自动根据需要将 EXTRACT_SUFX 设置为
.tar.bz2 或 .zip。
如果这两个都没设置, 则 EXTRACT_SUFX 的
默认值将是 .tar.gz。任何时候都不需要同时设置 EXTRACT_SUFX 和
DISTFILES.DISTFILES (全部源代码包)有些时候所下载的文件名字和 port 的名字没有任何联系。
例如, 可能是 source.tar.gz,
或者与此类似的其它名字。 也有一些其它的应用软件,
它们的源代码可能被存放到了不同的压缩包中, 而且全都需要下载。如果遇到这种情况, 可以将 DISTFILES
设置为以空格分隔的一组需要下载的文件列表。DISTFILES= source1.tar.gz source2.tar.gz如果没有予以明确的设置, DISTFILES 的默认值将是
${DISTNAME}${EXTRACT_SUFX}。EXTRACT_ONLY (只解压缩部分源文件)如果只有一部分 DISTFILES 需要解压缩
— 例如, 其中的一个是源代码, 而其它则是未压缩的文档 —
此时应把那些需要解压缩的文件加到
EXTRACT_ONLY 中。DISTFILES= source.tar.gz manual.html
EXTRACT_ONLY= source.tar.gz如果 DISTFILES 中 没有
需要解压缩的文件, 则应将 EXTRACT_ONLY 设为空串。EXTRACT_ONLY=PATCHFILES (通过下载得到的补丁文件)如果您的 port 需要来自 FTP 或 HTTP 的一些额外的补丁,
应将 PATCHFILES 设置为这些文件的名字,
并将 PATCH_SITES 指向包含这些文件的目录的 URL
(格式与 MASTER_SITES 相同)。如果这些补丁, 由于包含了其它的目录名,
而导致它们不是相对于源代码目录的顶级目录
(也就是 WRKSRC) 的话,
就需要相应地设置 PATCH_DIST_STRIP 了。
例如, 如果补丁中所有的目录名前面都有一个多余的
foozolix-1.0/, 就应设置
PATCH_DIST_STRIP=-p1。不需要担心补丁文件本身是否是压缩的; 如果文件名以
.gz or .Z
结尾, 系统会自动解压缩。如果补丁是同某些其它文件, 例如文档, 一同以 gzip 压缩的 tar
格式发布的, 就不能简单地使用
PATCHFILES 了。 这种情况下,
您应将这些补丁包的文件和位置加入到
DISTFILES 和 MASTER_SITES
中。 然后, 用 EXTRA_PATCHES 变量来指出这些文件,
这样 bsd.port.mk 就会自动地为您应用这些补丁了。
需要特别注意的是, 不要 将补丁文件复制到
PATCHDIR 目录中 — 这个目录可能是不可写的。压缩包会以同源代码一样的方式解压缩, 因此不需要自行完成解压缩操作,
并复制补丁文件。 如果您一定要这样做, 就要注意,
不要让解压缩出来的文件覆盖先前已经存在的文件。
此外, 这么做还需要手工增加命令,
以便在 pre-clean target
中删除这些复制出来的文件。来自不同站点的多个源代码包或补丁文件
(MASTER_SITES:n)(这一节在某种程度上应被视作 进阶话题;
刚开始阅读这份文档的读者可能会希望先跳过这一部分)。这一节提供了被称作 MASTER_SITES:n 和
MASTER_SITES_NN 的下载控制机制。
这里我们把它们称为 MASTER_SITES:n。首先给出一些背景。 OpenBSD 在其 DISTFILES 和
PATCHFILES 变量中提供了一个很棒的功能,
即, 允许这些文件和补丁拥有 :n
后缀, 其中 n 可以使用
[0-9], 来表达组。 例如:DISTFILES= alpha:0 beta:1在 OpenBSD 中, 源码包文件 alpha
应被关联到变量
MASTER_SITES0 而不是公共的
MASTER_SITES 变量上; 而
beta 则应关联到
MASTER_SITES1 上。这是一个很有意思的功能,
它可以避免无休止地搜索正确的下载站点的过程。想象 DISTFILES 中指定了 2 个文件,
而 MASTER_SITES 包含了 20 个站点的情形,
这其中许多站点慢如蜗牛, 而 beta 可以在
MASTER_SITES 的所有站点找到, 而
alpha 只能在第 20 个上面找到。
如果监护人了解这一点, 那么检查所有的站点无疑是在浪费时间,
不是吗? 这显然不是开始一个愉快周末的好办法!现在您有了一个感性的认识了, 想象一下
DISTFILES 和更多的
MASTER_SITES。 显然, 我们的
distfiles 调查员先生
会感谢您减少他浪费在等待下载上所耗费的时间。下一节中, 将按照 FreeBSD 对上述想法的实现来加以阐释。
我们对 OpenBSD 所提出的概念进行了一些改进。简化信息这一节将介绍如何迅速地对从不同的站点以及子目录下载多个源码包和补丁进行精确的控制。
这里, 我们将描述 MASTER_SITES:n 的一种简化用法。
对于多数情况而言这样做是足够的。 然而, 如果您需要更多信息,
还需要参考下面的几节。一些应用程序需要从多个站点下载不同的源码包。 例如,
Ghostscript 包括了程序核心本身,
以及大量的驱动文件, 以及则取决于用户的打印机品牌和型号的驱动程序。
某些驱动文件已经随程序核心附带, 但也有很多需要从其他站点下载。为了适应这种需要, 每一个
DISTFILES 项应跟随一个冒号,
以及一个 标签名。 在
MASTER_SITES 的每个站点也应跟随冒号和标签名,
以便指定从哪个网站下载源码包文件。例如, 考虑一个将源代码包分为两部分,
即 source1.tar.gz
和 source2.tar.gz 的软件,
它必须从两个不同的站点下载。 port 的
Makefile 应包括类似
的配置。简化的 MASTER_SITES:n
用法, 每个文件来自一个站点MASTER_SITES= ftp://ftp.example1.com/:source1 \
ftp://ftp.example2.com/:source2
DISTFILES= source1.tar.gz:source1 \
source2.tar.gz:source2多个源码包可以使用同一个标签。 继续前面的例子,
假定增加了第三个源码包, source3.tar.gz,
应从 ftp.example2.com 下载。
Makefile 的这部分应写成
的样子。简化的 MASTER_SITES:n 用法,
其中同一个站点上提供了不止一个文件MASTER_SITES= ftp://ftp.example1.com/:source1 \
ftp://ftp.example2.com/:source2
DISTFILES= source1.tar.gz:source1 \
source2.tar.gz:source2 \
source3.tar.gz:source2深入介绍前面的例子无法满足您的需求? 这一节,
我们将详细介绍 MASTER_SITES:n
的精细控制是如何工作的, 以及如何修改您的 port
来使用它们。元素可以包含
:n 这样的后缀, 其中
n 是
[^:,]+, 概念上即
n 可以取任意数字或字母,
但我们目前将其限定为
[a-zA-Z_][0-9a-zA-Z_]+。此外, 字符串匹配时对大小写是敏感的;
换言之, n 与
N 不同。但是, 由于表达特殊的意义, 下列单词不能用于后缀:
default、 all 和
ALL (它们会在
中介绍的部分用到)。 此外, DEFAULT
是一个有特殊用途的词 (请参见 )。后缀为 :n
的项目属于 n 组, 而
:m 属于
m 组, 依此类推。没有后缀的元素是无组的, 也就是它们都属于那个特殊的
DEFAULT 组。 给元素加入
DEFAULT 后缀通常是多余的,
除非您有同时属于 DEFAULT 和其他组的元素
(参见 )。下面的例子是等价的, 但通常应适用第一个:MASTER_SITES= alpha
MASTER_SITES= alpha:DEFAULT组之间不是互斥的, 同一元素可以同时隶属于多个组,
而组则可以为空或者有任意多个元素。 同一组中的重复元素,
并不会被自动消去。如果希望同一元素同时属于多个组, 可以用逗号
(,) 分开。这种办法可以避免仅为指定不同的组而多次重复同一元素。 例如
:m,n,o 表示这个元素同时属于
m、 n 和 o
这三组。下面这些写法都是等价的, 但只推荐使用最后一种:MASTER_SITES= alpha alpha:SOME_SITE
MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE
MASTER_SITES= alpha:SOME_SITE,DEFAULT
MASTER_SITES= alpha:DEFAULT,SOME_SITE同一组中的所有站点, 会根据
MASTER_SORT_AWK 排序。
在 MASTER_SITES 和
PATCH_SITES 中的组也会进行排序。在 MASTER_SITES、
PATCH_SITES、
MASTER_SITE_SUBDIR、
PATCH_SITE_SUBDIR、
DISTFILES, 以及
PATCHFILES 中, 都可以使用组,
其语法为:所有 MASTER_SITES、
PATCH_SITES、
MASTER_SITE_SUBDIR 以及
PATCH_SITE_SUBDIR 的元素, 都必须以
/ 字符结尾。 如果有元素属于某些组,
则组后缀
:n
必须出现在终结符
/ 之后。
MASTER_SITES:n 机制依赖于
/ 的存在, 以避免在 :n
是元素一部分, 而 :n 同时又表示组
n 时发生混淆。 为了兼容性的考虑,
因为之前 / 终结符在
MASTER_SITE_SUBDIR 和
PATCH_SITE_SUBDIR 元素中都不是必需的,
如果后缀所紧跟的字符不是 /,
则 :n 将被认为是元素的一部分,
而不被当作组后缀, 即使元素拥有 :n
后缀。 请参见
和
以了解进一步的细节。在 MASTER_SITE_SUBDIR 中
MASTER_SITES:n 的详细用法MASTER_SITE_SUBDIR= old:n new/:NEW组 DEFAULT 中的目录
-> old:n组 NEW 中的目录
-> new用到逗号分隔符、 多个文件, 多个站点和
不同子目录的 MASTER_SITES:n
详细用法MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \
http://site3/:group3 http://site4/:group4 \
http://site5/:group5 http://site6/:group6 \
http://site7/:DEFAULT,group6 \
http://site8/%SUBDIR%/:group6,group7 \
http://site9/:group8
DISTFILES= file1 file2:DEFAULT file3:group3 \
file4:group4,group5,group6 file5:grouping \
file6:group7
MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \
directory-one/:group6,DEFAULT \
directory前述的例子的结果是下述的对于下载行为的精细控制。
站点的列表按照使用的顺序给出。file1 将从MASTER_SITE_OVERRIDEhttp://site1/directory-trial:1/http://site1/directory-one/http://site1/directory/http://site2/http://site7/MASTER_SITE_BACKUP下载。file2 将和
file1 以同样的方式下载,
因为它们属于同一组MASTER_SITE_OVERRIDEhttp://site1/directory-trial:1/http://site1/directory-one/http://site1/directory/http://site2/http://site7/MASTER_SITE_BACKUPfile3 将从MASTER_SITE_OVERRIDEhttp://site3/MASTER_SITE_BACKUP下载。file4 将从MASTER_SITE_OVERRIDEhttp://site4/http://site5/http://site6/http://site7/http://site8/directory-one/MASTER_SITE_BACKUP下载。file5 将从MASTER_SITE_OVERRIDEMASTER_SITE_BACKUP下载。file6 将从MASTER_SITE_OVERRIDEhttp://site8/MASTER_SITE_BACKUP下载。如何对来自
bsd.sites.mk 的特殊变量, 例如
MASTER_SITE_SOURCEFORGE 进行分组?参见 。MASTER_SITE_SOURCEFORGE 中
MASTER_SITES:n 的详细用法MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/}
DISTFILES= something.tar.gz:sourceforgesomething.tar.gz 将从所有
MASTER_SITE_SOURCEFORGE 中的站点下载。如何与 PATCH* 变量连用?前面的例子介绍的都是
MASTER* 变量,
但对于 PATCH* 也是完全一样的,
它们在
有所介绍。简化的 PATCH_SITES 中的
MASTER_SITES:n 用法。PATCH_SITES= http://site1/ http://site2/:test
PATCHFILES= patch1:test会改变 ports 的哪些行为? 哪些不会?所有普通的 ports 的行为都会保持不变。
MASTER_SITES:n 功能的代码,
只有在某些元素包含了前述, 特别是
中所提及语法的
:n 后缀时,
才会启用。不受影响的 port target:
checksum、
makesum、
patch、
configure、
build, 等等。
显然, do-fetch、
fetch-list、
master-sites 和
patch-sites 的行为会发生变化。do-fetch: 会按照新的、
带有组后缀的
DISTFILES 和
PATCHFILES 在
MASTER_SITES 和
PATCH_SITES 所匹配的组元素, 以及
MASTER_SITE_SUBDIR 和
PATCH_SITE_SUBDIR 来进行。
请参见 。fetch-list: 和旧式的
fetch-list 类似, 但以同
do-fetch 相似的方式处理组。master-sites 和
patch-sites:
(与旧版本不兼容) 仅返回组 DEFAULT
的元素; 事实上, 它们会执行
master-sites-default 和
patch-sites-default
这两个 target。更进一步, 使用
master-sites-all 或
patch-sites-all 这两个
target 之一, 要比直接检查
MASTER_SITES 或
PATCH_SITES 更好。
此外, 未来版本可能不再保证直接检查能够正确工作。
请参见
以了解关于这些新 target 的更多技术细节。port 中的新 target一系列
master-sites-n
和
patch-sites-n
target 可以分别用来列出 MASTER_SITES 和
PATCH_SITES 中的 n
组的内容。 例如,
master-sites-DEFAULT 和
patch-sites-DEFAULT 都会返回
DEFAULT 组的内容, 而
master-sites-test 和
patch-sites-test 则返回
test 组的内容, 等等。新增的
master-sites-all 和
patch-sites-all 这两个 target,
会完成先前
master-sites 和
patch-sites 所做的工作。
它们会返回所有组的元素, 就像这些元素都属于同一组一样,
并且会列出与
MASTER_SITE_BACKUP 或
MASTER_SITE_OVERRIDE 中在
DISTFILES 或
PATCHFILES 中指定的同样多个; 分别对于
master-sites-all 和
patch-sites-all。DIST_SUBDIR (独立的源码包子目录)避免让您的 port 使
/usr/ports/distfiles 陷入混乱。
如果您的 port 需要下载很多文件, 或者需要下载可能与其它 port
的源文件名冲突的文件 (例如,
Makefile), 则应将 DIST_SUBDIR
设置为 port 的名字 (通常可以用 ${PORTNAME} 或
${PKGNAMEPREFIX}${PORTNAME})。 这将把
DISTDIR 从默认的
/usr/ports/distfiles 改为
/usr/ports/distfiles/DIST_SUBDIR,
并将与您的 port 有关的文件放到那个目录中。此外, 它也会在备份文件主服务器 ftp.FreeBSD.org
上查找同一子目录下的文件 (直接在您的
Makefile 中设置 DISTDIR
则不会有这样的效果, 因此您应使用
DIST_SUBDIR。)这一设置并不影响您在 Makefile
中定义的 MASTER_SITES。MAINTAINER (监护人)请在此处写上您的电子邮件地址。 :-)需要注意的是, MAINTAINER 的值只允许一个电子邮件地址,
其格式是 user@hostname.domain。
此处不要写任何说明性的文字, 例如您的真实姓名 — 这会使
bsd.port.mk 感到困惑。 此类文字,
应放在 pkg-descr 中。监护人的职责说明,
可以在 Makefiles
中的 MAINTAINER 找到。如果某一 port 的监护人没有在两周 (重要的公共假日除外)
之内响应用户的更新请求, 则视为监护人超时,
从而允许在没有监护人明确同意的情形下进行更新。
如果监护人没有在三个月之内予以响应, 且属于不辞而别的情形,
则可以变更相应 port 的监护人。 此规定对于监护人为 &a.portmgr; 或
&a.security-officer; 的 port 不适用。 未经许可,
不允许 commit 这些小组所监护的 port。&a.portmgr; 保留以任何原因收回或绕过监护权的权力,
而 &a.security-officer; 则保留以安全原因收回或绕过监护权的权力。COMMENT (一句话说明)这一变量用于指定 port 的一句话说明。
请 勿将 package 的名字 (或软件的版本)
放在说明中。 这一说明的第一个字母应大写, 结尾不用句点。
下面是一个例子:COMMENT= A cat chasing a mouse all over the screenMakefile 中的 COMMENT 变量应该紧接着 MAINTAINER
变量出现。请务必将 COMMENT 这行限制在 70 个字符之内,
因为它的主要目的是向用户展示 port 的一句话简介。依赖关系许多 port 会依赖其他 port。
有七个变量用于帮助您确保所需的文件都存在于用户的机器上。
此外, 也提供了用于支持常见情形的依赖关系变量,
以及对依赖关系行为的更多控制。LIB_DEPENDS (依赖的函数库/共享库)这个变量用于指定 port 所依赖的共享库。 其内容是由一系列
lib:dir:target
元组构成的表, 其中 lib 是共享库的名字,
而 dir 则是在找不到时应该从哪里构建和安装,
最后, target 用于指定在那个目录中调用的
target。 例如,
LIB_DEPENDS= jpeg.9:${PORTSDIR}/graphics/jpeg:install
会检测主版本号为 9 的 jpeg 共享库, 如果它不存在,
则会进入到您的 ports 目录中的 graphics/jpeg
子目录, 并构建和安装它。 如果您指定的 target
就是 DEPENDS_TARGET (默认是
install), 则可以略去不写。lib 部分是一个正则表达式, 用于在
ldconfig -r 的输出中进行查找。 可以使用类似
intl.[5-7] 和 intl 这样的值。
后者表示任意主版本号的 intl 库。依赖关系会被检测两次, 一次是在
extract target 中, 而另一次则是在
install target。 另外,
依赖关系的名字会放到 package 中, 以便让
&man.pkg.add.1; 能够自动地在用户系统上安装所需的未安装的其他
package。RUN_DEPENDS (依赖的运行环境)这个变量可以用来指定 port 在运行时所需要的可执行文件,
以及资源文件。 它是一系列
path:dir:target
元组的列表, 这里, path 时所需的可执行,
或者资源文件的名字, dir 是在无法找到这些文件或目录时,
去什么地方完成构建和安装以便获得这些文件; 而
target 则用来指定在这个目录中所调用的
target 的名字。 假如 path 以斜线
(/) 开始, 则会当作普通文件,
使用 test -e 来测试; 反之,
则系统会假定这是一个可执行文件, 并且用 which -s
来检测程序是否存在于搜索路径中。例如,RUN_DEPENDS= ${LOCALBASE}/etc/innd:${PORTSDIR}/news/inn \
wish8.0:${PORTSDIR}/x11-toolkits/tk80将检查文件, 或者目录
/usr/local/etc/innd 是否存在,
如果找不到, 则将从 port 目录的
news/inn 子目录加以安装。
系统也会检查是否能够在搜索路径中找到名为 wish8.0
的文件, 如果找不到的话, 则会进入 ports 目录中的
x11-toolkits/tk80 子目录,
并进行构建和安装的操作。这种情况下, innd 实际上是一个可执行文件;
如果可执行文件不会出现在搜索路径中, 您就需要指定完整路径了。ports 构建集群上官方的搜索 PATH 是/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/X11R6/bin这个依赖关系会在
install target 的过程中进行检查。
此外, 依赖关系的名字会被放到 package 中, 以便
&man.pkg.add.1; 能够在用户的系统中尚未安装相关软件时自动地安装那些 package。
如果您希望指定一个的 target
和默认的 DEPENDS_TARGET 相同,
则可以略去不写。BUILD_DEPENDS (依赖的构建环境)此变量用于指定用来构建 port 的可执行文件或资源文件。
与 RUN_DEPENDS 类似, 它是一个
path:dir:target
元组的列表。 例如, BUILD_DEPENDS=
unzip:${PORTSDIR}/archivers/unzip 将检测名为
unzip 的可执行文件是否存在, 如果不存在,
则会进入到您的 ports 目录中的 archivers/unzip
并完成构建和安装工作。这里的 build 表示从解压缩到编译的全部过程。
依赖关系是在 extract target 的过程中检测的。
假如您要指定的 target 和
DEPENDS_TARGET 相同, 则可以略去不写。FETCH_DEPENDS (依赖的下载环境)这一变量用于指定 port 在下载时所需的可执行文件或资源文件。
和前两个类似, 它是一组
path:dir:target
元组。 例如, FETCH_DEPENDS=
ncftp2:${PORTSDIR}/net/ncftp2
将检测名为 ncftp2 的可执行文件是否存在,
如果找不到, 则将进入到您 ports 目录中的
net/ncftp2 子目录并加以构建和安装。这个依赖关系是在
fetch target 过程中检查的。
如果与 DEPENDS_TARGET 相同,
则可以省略 target 部分。EXTRACT_DEPENDS (依赖的解压缩环境)此变量用于指定 port 在解压缩时所需的可执行文件或其他资源文件。
和前一个变量类似, 它是一系列
path:dir:target
元组的列表。 例如, EXTRACT_DEPENDS=
unzip:${PORTSDIR}/archivers/unzip 将检查名为
unzip 的可执行文件是否存在, 如果不存在,
则会进入到您的 ports 目录中的 archivers/unzip
子目录, 予以构建和安装。这个依赖关系是在
extract target 的过程中检查的。 如果与
DEPENDS_TARGET 相同,
则可以略去 target 部分。只有在其他方式都不可用 (默认是 gzip)
而且无法通过 所介绍的 USE_ZIP 或
USE_BZIP2 都不能达到需要时,
才应使用这个变量。PATCH_DEPENDS (依赖的打补丁环境)这个变量用于指定 port 在进行 patch
操作时所需的可执行文件或其他资源文件。 和前一个变量类似, 它是一组
path:dir:target
元组的表。 例如, PATCH_DEPENDS=
${NONEXISTENT}:${PORTSDIR}/java/jfc:extract
表示进入到您的 ports 目录中的
java/jfc 子目录, 并将其解压缩,
而无论它是否之前安装过。这个依赖关系是在
patch target 的过程中检查的。
target 部分如果和
DEPENDS_TARGET 相同, 就可略去不写。DEPENDS (一般依赖)如果有无法归类于上述类别的依赖关系, 或者您的 port
需要解压缩其他 port 的源代码才能够完成构建或安装,
则应使用它来表达。 这个变量是一组格式为
dir:target
的元组表, 与前四个不同, 它并不实施检查。 这里的
target 部分,
如果与 DEPENDS_TARGET 相同, 就可以略去不写。USE_*提供了一系列变量, 用以封装大量 port 都用到的依赖关系。
虽然使用这些变量是可选的, 但它们能显著减少 port 的
Makefile 复杂性。 这些变量的共同特征在于,
它们的名字都是 USE_*
这样的形式。 这些变量的使用, 应严格限制于 port 的
Makefile 以及
ports/Mk/bsd.*.mk,
而绝不应用于表达用户能够设置的选项 — 这种情况下应采用
WITH_* 和
WITHOUT_*
这样的变量。任何 情况下, 都不应在
/etc/make.conf 中配置
USE_*。
例如, 设置 USE_GCC=3.2
将导致每一个 port 都依赖于 gcc32, 甚至包括
gcc32 本身!
常用的 USE_*
变量变量含义USE_BZIP2此 port 的源码包是使用
bzip2 压缩的。USE_ZIP此 port 的源码包是用
zip 压缩的。USE_GMAKE此 port 需要使用gmake 来进行构建。USE_PERL5此 port 的构建和安装需要使用 perl 5。 参见
以了解与 perl
有关的其他变量。USE_X_PREFIX此 port 将安装到 X11BASE
而非默认的 PREFIX。 请参见
以了解其他与 X11 有关的变量。USE_AUTOMAKE_VER此 port 的构建过程中用到了 GNU automake。
请参见 以了解与
automake 有关的其他变量。USE_AUTOCONF_VER此 port 的构建过程中用到了 GNU autoconf。
请参见 以了解与
autoconf 有关的其他变量。USE_LIBTOOL_VER此 port 构建过程用到了 GNU libtool。
请参见 以了解与
libtool 有关的其他变量。GMAKEgmake 的完整路径, 如果它不在
PATH 中的话。USE_BISON此 port 在构建时使用 bison。USE_SDL此 port 使用 SDL 来完成构建和支持运行。
参见 以了解如何使用
USE_SDL。USE_GCC此 port 需要使用某一特定版本的
gcc 才能完成编译。
可以使用类似 3.2 这样的值来精确指定版本。
如果希望使用不低于某一版本的编译器, 则可以用
3.2+ 这样的形式。 如果与所希望的版本吻合,
则将使用基本系统中所提供的 gcc, 反之,
系统会从 ports 中安装所希望版本的 gcc,
并调整 CC 以及
CXX 变量的设置。 需要注意的是,
USE_GCC 不能与
USE_LIBTOOL_VER 联用。NO_INSTALL_MANPAGES不要使用 install.man
target。
如果您的 port 需要使用 X Window 系统,
则应定义 USE_XLIB=yes。 (如果定义了
USE_IMAKE 则会作隐含定义)。 如果您的 port
使用了 GNU make 而不是 BSD
make, 还应定义
USE_GMAKE=yes。 如果需要运行 GNU autoconf,
还需要定义 USE_AUTOCONF_VER=213。
定义 USE_QT_VER=3 表示您的 port 需要使用最新的
Qt toolkit。 此外, 还可以用
USE_PERL5=yes 来表示 port 需要
perl 语言的第 5 版。 (最后一个变量很重要,
因为某些版本的 FreeBSD 的基本系统中包含了 perl5,
而新版本则没有。)关于依赖关系的补充说明如前面所提到的那样, 在需要某一依赖的 port 时,
将调用 DEPENDS_TARGET 所指定的 target。
这一变量的默认值是 install。 这不是一个用户变量,
它不应在 port 的
Makefile 中予以定义。 如果您的 port 需要使用特殊的
target 来处理依赖关系, 应使用 *_DEPENDS 的
:target 部分, 而不是重定义
DEPENDS_TARGET 来完成。当您输入 make clean 时, 其依赖的 port
也会自动进行清理。 如果您不希望如此, 应定义环境变量
NOCLEANDEPENDS。 如果 port
依赖一些重新构建需要花费很长时间的 port 时, 例如 KDE, GNOME
或 Mozilla 时, 这一方法会非常有用。要无条件地依赖某个 port, 可以使用 ${NONEXISTENT}
作为 BUILD_DEPENDS 或
RUN_DEPENDS 的第一部分。 只有在您需要使用其他
port 提供的源代码时才应这样做。 通常也可以通过这样指定来缩短编译所需的时间。
例如
BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract
表示依赖 jpeg port 并将其解压缩。除非其他方式都不适合, 否则不要使用 DEPENDS。
这样指定将在任何情况下都构建 (默认情况下还会安装) 其他 port,
而且这依赖关系还会进入 package。 如果真的需要这样, 写成
BUILD_DEPENDS 和
RUN_DEPENDS 可能更合适一些 —
至少它的表达更为明确。循环的依赖关系是致命的不要在 ports tree 中引入任何循环依赖关系!ports 构建技术不能够容忍循环依赖关系。 如果您引入了这样的关系,
就一定会有人安装的 FreeBSD 会因此而损坏, 而且这种现象会越来越多。
这些情形很难检测; 如果有疑虑, 在进行这样的修改之前, 务必执行:
cd /usr/ports; make index。 这个过程在旧的机器上会很慢,
但能够让大量的用户 — 也包括您自己 —
拯救于由这种问题所造成的困惑之中。Makefile 选项某些大型应用程序可以在构建时使用一系列配置选项,
用以在系统中已经安装了某些库或应用程序时增加一些功能。
例如, 选择某种自然 (人类的) 语言, GUI 或命令行界面,
由于并不是所有的用户都希望使用这些库或者应用程序, port
系统提供了一组方便的机制, 来让 port 的作者控制构建时的配置。
支持这些特性可以让用户体验更好, 并达到事半功倍的效果。WITH_* 和
WITHOUT_*这些变量是为系统管理员准备的。 许多这样的变量被标准化并置于
ports/Mk/bsd.*.mk; 也有一些没有,
这可能会比较令人困惑。 如果您需要增加类似的配置变量,
请考虑使用下表中的变量。您不应假定每一个
WITH_*
都会有对应的
WITHOUT_*
变量, 反之亦然。 一般而言, 会使用默认值。除非另有说明, 这些变量都是测试是否定义,
而不是它们设置了 YES 或
NO。
用到 X 的 port 可以使用的变量USE_X_PREFIX此 port 将文件安装到 X11BASE 而非通常的
PREFIX。USE_XLIB此 port 用到了 X 库。USE_MOTIF此 port 使用 Motif 工具包。 这一变量暗含
USE_XPM 设置。USE_IMAKE此 port 用到了 imake。 这一变量也会自动设置
USE_X_PREFIX。XMKMF设置为 xmkmf 的完整路径名, 如果它不在
PATH 中的话。 默认值是 xmkmf
-a。
您可以使用 java-debug make target
以获取用于调试 port 的信息。 大多数前述变量的值皆会予以呈现。此外, 还会定义下述常量, 以确保所有的
Java port 均以一致之方式安装:
为使用 Java 的 port 定义的常量常量值JAVASHAREDIR所有 Java 相关资料的安装根目录。
默认值: ${PREFIX}/share/java.
JAVAJARDIR用以安装 JAR 文件的目录。 默认值:
${JAVASHAREDIR}/classes。JAVALIBDIR其他 port 安装的 JAR 文件所在的目录。 默认值:
${LOCALBASE}/share/java/classes。
相关的项也在
PLIST_SUB (在
中进行介绍) 和
SUB_LIST 提供了对应的定义。采用 Ant 进行构建如果 port 采用 Apache Ant 进行构建,
则需要定义 USE_ANT。 如是, 则 Ant
将作为 子-make 命令来使用。 如果 port 未予定义
do-build target, 则默认将依 MAKE_ENV、
MAKE_ARGS 和 ALL_TARGETS
的设置执行 Ant。 这类似于 USE_GMAKE 的机制,
后者在 有所介绍。若 jikes 被作为
javac 使用 (参见
中的 USE_JIKES), 则 Ant 将自动地用它来构建 port。最佳实践如果您正移植某个 Java 库, 您的 port 应把
JAR 文件安装到 ${JAVAJARDIR}, 而其他文件则应放在
${JAVASHAREDIR}/${PORTNAME} 下
(除了文档, 参见下文)。 要减少打包文件的尺寸,
您可以直接在 Makefile 中引用这些 JAR 文件,
具体做法是使用下面的语句 (此处的 myport.jar
是作为 port 一部分安装的 JAR 文件的名字):PLIST_FILES+= %%JAVAJARDIR%%/myport.jar移植 Java 应用程序时, port 通常会希望将所有文件安装到同一目录
(包括其依赖的 JAR)。 这时强烈建议使用
${JAVASHAREDIR}/${PORTNAME}。
移植软件的开发人员, 可以自行决定是否将所依赖的其他 JAR 安装到此目录,
或直接使用已经装好的那些
(来自 ${JAVAJARDIR})。无论您正制作哪一类的 port (库或者应用程序),
附加的文档都应安装到和其他 port
同样的位置。
已经知道, JavaDoc 会根据 JDK 版本的不同而产生不同的文件。
对于那些不打算强制使用某一特定版本 JDK 的 port 而言,
这无疑提高了制作装箱单
(pkg-plist) 的难度。 这是为什么强烈建议使用
PORTDOCS 宏的原因。 更进一步, 即使您能够预测
javadoc 将要生成的文件, 所需的
pkg-plist 的尺寸, 也是鼓吹使用
PORTDOCS 的一大理由。DATADIR 的默认值是
${PREFIX}/share/${PORTNAME}。
对 Java port 而言将 DATADIR 改为
${JAVASHAREDIR}/${PORTNAME} 是一个好主意。
当然, DATADIR 会自动加到
PLIST_SUB 中 (在 有所介绍) 因此您可以在
pkg-plist 中直接使用
%%DATADIR%%。撰写本文时, 对是应该从源代码构建, 还是直接安装预编译的
Java ports 安装包并没有明确的规定。 尽管如此, &os; Java Project
的开发人员仍鼓励移植软件的开发者在不麻烦的情况下尽可能从源代码完成构建。本节中所介绍的全部特性, 均是在 bsd.java.mk
中实现的。 如果您感觉自己的 port 需要更为复杂的 Java 支持,
请首先参阅
bsd.java.mk CVS 日志, 因为通常撰文介绍最新特性需要一些时间。
此外, 如果您认为所缺少的支持对许多其他 Java port 亦属有益,
请在 &a.java; 对其进行讨论。在 PR 中的 java 类别,
主要是用于 &os; Java project 移植 JDK 本身之用。
因而, 提交您的 Java port 时, 应归入
ports 类别, 除非您正尝试解决的问题是 JDK
实现本身或 bsd.java.mk 的。类似地, 您应参考 中所详述的关于
CATEGORIES 在 Java port 中的使用规则。使用 Apache 和 PHPApache
用到 Apache 的 port 可以使用的变量USE_APACHE此 port 需要 Apache。WITH_APACHE2此 port 需要 Apache 2.0。 如果没有这个变量,
则 port 将依赖 Apache 1.3。APXS到 apxs 程序的完整路径
(这是一个只读的变量)。
使用 Ruby 的 port 可以使用的变量变量说明USE_RUBY此 port 需要 Ruby。USE_RUBY_EXTCONF此 port 使用 extconf.rb
来完成配置。USE_RUBY_SETUP此 port 使用 setup.rb
来完成配置。RUBY_SETUP将此变量名设置为所用的
setup.rb 的文件名。 通常会是
install.rb。
下表展示了 ports 系统提供给 port 作者的一些变量。
您应使用这些变量, 以便把文件装到合适的位置。 请尽可能多地在
pkg-plist 中使用它们。 这些变量不应在 port
中重新定义。