Special Considerations
- There are some more things you have to take into account
- when you create a port. This section explains the most common
- of those.
+ This section explains the most common things to consider when
+ creating a port.Stagingbsd.port.mk expects ports to work
with a stage directory. This means that a port
- should not install files directly to the regular destination
+ must not install files directly to the regular destination
directories (that is, under PREFIX, for
example) but instead into a separate directory from which the
package is then built. In many cases, this does not require
@@ -42,7 +41,7 @@
The vast majority of ports do not really
- need to be root. You can mostly avoid it by
+ need to be root. It can mostly be avoided by
using USES=uidfix,
and from time to time by slightly patching the port's
@@ -50,7 +49,7 @@
Meta ports, or ports that do not install files themselves
- but only depend on other ports, should avoid needlessly
+ but only depend on other ports, must avoid needlessly
extracting the &man.mtree.8; to the stage directory. This is
the basic directory layout of the package, and these empty
directories will be seen as orphans. To prevent
@@ -58,8 +57,8 @@
NO_MTREE= yes
- Staging is enabled by prepending the
- STAGEDIR variable to paths used in the
+ Staging is enabled by prepending
+ STAGEDIR to paths used in the
pre-install,
do-install, and
post-install targets (see the
@@ -72,21 +71,21 @@
absolute paths whenever possible.When creating a symlink, STAGEDIR
- should be prepended to the target path only. For
+ is prepended to the target path only. For
example:
- ${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so
+ ${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.soThe source path
- ${PREFIX}/lib/libfoo.so.42 looks fine but
+ ${PREFIX}/lib/libfoo.so.42 looks fine but
could, in fact, be incorrect. Absolute paths can point to a
wrong location, like when a remote file system has been
mounted with NFS under a non-root mount
point. Relative paths are less fragile, and often much
shorter.
- Ports that install kernel modules must prepend the
- STAGEDIR variable to
+ Ports that install kernel modules must prepend
+ STAGEDIR to
their destination, by default
/boot/modules.
@@ -106,7 +105,7 @@
distribution file. The second approach seems easier at
first, but there are some serious drawbacks:
- The following list is loosely based on the This list is loosely based on the Fedora
and Gentoo
@@ -220,7 +219,7 @@
port. If such a port does not exist yet, consider creating
it.
- Bundled libraries should only be used if upstream has a
+ Only use bundled libraries if the upstream has a
good track record on security and using unbundled versions
leads to overly complex patches.
@@ -229,7 +228,7 @@
Shared Libraries
- If your port installs one or more shared libraries, define
+ If the port installs one or more shared libraries, define
a USE_LDCONFIG make variable, which will
instruct a bsd.port.mk to run
${LDCONFIG} -m on the directory
@@ -239,21 +238,21 @@
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
+ @unexec /sbin/ldconfig -R pair into
+ pkg-plist, 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.USE_LDCONFIG= yes
- If you need, you can override the default directory by
- setting the USE_LDCONFIG value to a list of
+ The default directory can be overridden by
+ setting USE_LDCONFIG to a list of
directories into which shared libraries are to be installed.
- For example if your port installs shared libraries into
+ For example, if the port installs shared libraries into
PREFIX/lib/foo and
PREFIX/lib/bar
- directories you could use the following in your
+ use this in
Makefile:USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar
@@ -270,14 +269,14 @@
When installing 32-bit libraries on 64-bit system, use
USE_LDCONFIG32 instead.
- If the software you are porting uses If the software uses autotools, and specifically
- libtool, you should add libtool, add USES=libtool.When the major library version number increments in the
update to the new port version, all other ports that link to
- the affected library should have their
+ the affected library must have their
PORTREVISION incremented, to force
recompilation with the new library version.
@@ -291,7 +290,7 @@
profit, and so on.
- It is your responsibility as a porter to read the
+ It is the responsibility of a porter to read the
licensing terms of the software and make sure that the
&os; project will not be held accountable for violating
them by redistributing the source or compiled binaries
@@ -300,7 +299,7 @@
In situations like this, the variables described in the
- following sections can be set.
+ next sections can be set.
NO_PACKAGE
@@ -316,15 +315,16 @@
on a CD-ROM (or similar media) unless
NO_CDROM is set as well.
- NO_PACKAGE should also be used if the
+ If the
binary package is not generally useful, and the application
- should always be compiled from the source code. For
+ must always be compiled from the source code, use
+ NO_PACKAGE. For
example, if the application has configuration information
- that is site specific hard coded in to it at compile time,
+ that is site specific hard coded into it at compile time,
set NO_PACKAGE.
- NO_PACKAGE should be set to a string
- describing the reason why the package should not be
+ Set NO_PACKAGE to a string
+ describing the reason why the package cannot be
generated.
@@ -343,9 +343,9 @@
DISTFILES will be available, and only via
FTP/HTTP.
- NO_CDROM should be set to a string
+ Set NO_CDROM 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
+ on CD-ROM. For instance, use this if the port's
license is for non-commercial use
only.
@@ -353,13 +353,13 @@
NOFETCHFILES
- Files defined in the NOFETCHFILES
- variable are not fetchable from any of the
+ Files defined in NOFETCHFILES
+ are not fetchable from any of
MASTER_SITES. An example of such a file
is when the file is supplied on CD-ROM by the vendor.Tools which check for the availability of these files
- on the MASTER_SITES should ignore these
+ on MASTER_SITES have to ignore these
files and not report about them.
@@ -371,12 +371,12 @@
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
+ Do not set NO_CDROM or
+ NO_PACKAGE along with
+ RESTRICTED, since the latter variable
implies the former ones.
- RESTRICTED should be set to a string
+ Set RESTRICTED 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
@@ -400,10 +400,10 @@
LEGAL_TEXTIf the port has legal concerns not addressed by the
- above variables, the variable LEGAL_TEXT
- should be set to a string explaining the concern. For
+ above variables, set LEGAL_TEXT
+ to a string explaining the concern. For
example, if special permission was obtained for &os; to
- redistribute the binary, this variable should indicate
+ redistribute the binary, this variable must indicate
so.
@@ -482,8 +482,8 @@
implementation is listed in USES, the
variables GMAKE (for the
GNU version) or FMAKE
- (for the legacy &os; version) are available. Most ports
- should only use MAKE_CMD within the
+ (for the legacy &os; version) are available.
+ Only use MAKE_CMD within the
application Makefiles in
WRKSRC to call the
make implementation expected by the
@@ -497,10 +497,10 @@
linkend="uses-imake">USES=imake
section of for more details.
- If your port's source Makefile has
- something else than all as the
+ If the port's source Makefile has
+ something other than all as the
main build target, set ALL_TARGET
- accordingly. Same goes for
+ accordingly. The same goes for
install and
INSTALL_TARGET.
@@ -508,10 +508,10 @@
configure Script
- If your port uses the configure
- script to generate Makefile files from
- Makefile.in files, set
- GNU_CONFIGURE=yes. If you want to give
+ If the port uses the configure
+ script to generate Makefile from
+ Makefile.in, set
+ GNU_CONFIGURE=yes. To give
extra arguments to the configure script
(the default argument is --prefix=${PREFIX}
--infodir=${PREFIX}/${INFO_PATH}
@@ -519,7 +519,7 @@
--build=${CONFIGURE_TARGET}), set those
extra arguments in CONFIGURE_ARGS. Extra
environment variables can be passed using
- CONFIGURE_ENV variable.
+ CONFIGURE_ENV.
Variables for Ports That Use
@@ -624,8 +624,8 @@
- Variables the Users can define for
- cmake builds
+ Variables the Users Can Define for
+ cmake Builds
@@ -653,7 +653,7 @@
- CMake supports the following
+ CMake supports these
build profiles: Debug,
Release,
RelWithDebInfo and
@@ -664,14 +664,14 @@
CFLAGS to -O2 -g and
-Os -DNDEBUG correspondingly. The
lower-cased value of CMAKE_BUILD_TYPE is
- exported to the PLIST_SUB and should be
- used if port installs *.cmake files
+ exported to PLIST_SUB and must be
+ used if the port installs *.cmake
depending on the build type (see
deskutils/strigi for an
example). Please note that some projects may define their
own build profiles and/or force particular build type by
setting CMAKE_BUILD_TYPE in
- CMakeLists.txt files. In order to
+ CMakeLists.txt. To
make a port for such a project respect
CFLAGS and WITH_DEBUG,
the CMAKE_BUILD_TYPE definitions must be
@@ -692,7 +692,7 @@
USES= cmake Example
- The following snippet demonstrates the use of
+ This snippet demonstrates the use of
CMake for a port.
CMAKE_SOURCE_PATH is not usually
required, but can be set when the sources are not located
@@ -707,7 +707,7 @@
Using scons
- If your port uses SCons,
+ If the port uses SCons,
define USE_SCONS=yes.
@@ -753,7 +753,7 @@
To make third party SConstruct
respect everything that is passed to SCons in
SCONS_ENV (that is, most importantly,
- CC/CXX/CFLAGS/CXXFLAGS), patch the
+ CC/CXX/CFLAGS/CXXFLAGS), patch
SConstruct so build
Environment is constructed like
this:
@@ -842,9 +842,9 @@
autoheaderSome ports do not contain a configure script, but do
- contain an autoconf template in the
- configure.ac file. You can use the
- following assignments to let autoconf
+ contain an autoconf template in
+ configure.ac. Use these
+ assignments to let autoconf
create the configure script, and also have
autoheader create template headers for
use by the configure script.
@@ -872,14 +872,14 @@
aclocalSome packages only contain
- Makefile.am files. These have to be
- converted into Makefile.in files using
+ Makefile.am. These have to be
+ converted into Makefile.in using
automake, and the further processed by
configure to generate an actual
Makefile.Similarly, packages occasionally do not ship with
- included aclocal.m4 files, again
+ an included aclocal.m4, again
required to build the software. This can be achieved with
aclocal, which scans
configure.ac or
@@ -914,8 +914,8 @@
Basic Usage
- If your port requires gettext, set
- USES= gettext, and your port will inherit
+ If the port requires gettext, set
+ USES= gettext, and the port will inherit
a dependency on libintl.so from
devel/gettext. Other
values for gettext usage are listed in
@@ -945,13 +945,13 @@
Optional Usage
- Some software products allow for disabling NLS, e.g.,
+ Some software products allow for disabling NLS. For example,
through passing to
- configure. In that case, your port
- should use gettext conditionally,
- depending on the status of the NLS
- option. For ports of low to medium complexity, you can rely
- on the following idiom:
+ configure. In that case, the port
+ must use gettext conditionally,
+ depending on the status of the NLS
+ option. For ports of low to medium complexity, use
+ this idiom:GNU_CONFIGURE= yes
@@ -981,7 +981,7 @@
.include <bsd.port.mk>
- The next item on your to-do list is to arrange so that
+ The next item on the to-do list is to arrange so that
the message catalog files are included in the packing list
conditionally. The Makefile part of
this task is already provided by the idiom. It is explained
@@ -994,7 +994,7 @@
Consequently, the lines prefixed by
%%NLS%% will become mere comments in the
final packing list if NLS is off; otherwise the prefix will
- be just left out. All you need to do now is insert
+ be just left out. Then insert
%%NLS%% before each path to a message
catalog file in pkg-plist. For
example:
@@ -1002,8 +1002,8 @@
%%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo
%%NLS%%share/locale/no/LC_MESSAGES/foobar.mo
- In high complexity cases, you may need to use more
- advanced techniques than the recipe given here, such as
+ In high complexity cases, more advanced techniques
+ may be needed, such as
dynamic packing list
generation.
@@ -1015,7 +1015,7 @@
catalog files. The target directories for them, which
reside under
LOCALBASE/share/locale,
- should rarely be created and removed by a port. The most
+ must not be created and removed by a port. The most
popular languages have their respective directories listed
in
PORTSDIR/Templates/BSD.local.dist.
@@ -1031,7 +1031,7 @@
Using PerlIf MASTER_SITES is set to
- CPAN, the correct subdirectory should be
+ CPAN, the correct subdirectory is usually
selected automatically. If the default subdirectory is wrong,
CPAN/Module can be used to change it.
MASTER_SITES can also be set to the old
@@ -1050,13 +1050,13 @@
directory. In such case, using author's id as
MASTER_SITE_SUBDIR is allowed.
The CPAN:AUTHOR macro can be used, which will
- be translated to the hashed author directory. (e.g.,
+ be translated to the hashed author directory. For example,
CPAN:AUTHOR will be converted to
- authors/id/A/AU/AUTHOR.)
+ authors/id/A/AU/AUTHOR.When a port needs Perl support,
- it should use USES=perl5 with the optional
- USE_PERL5 like described in USES=perl5 with the optional
+ USE_PERL5 described in the perl5 USES description.
@@ -1076,22 +1076,25 @@
PERLThe full path of the Perl 5 interpreter,
either in the system or installed from a port, but
- without the version number. Use this if you need to
- replace #!lines in
- scripts.
+ without the version number. Use this when the software
+ needs the path to the Perl
+ interpreter. To replace
+ #!lines in scripts,
+ use USES=shebangfix.
PERL_VERSIONThe full version of Perl
- installed (e.g., 5.8.9).
+ installed (for example, 5.8.9).
PERL_LEVELThe installed Perl version as
an integer of the form MNNNPP
- (e.g., 500809).
+ (for example, 500809).
@@ -1104,7 +1107,7 @@
PERL_PORTName of the Perl port that is
- installed (e.g., perl5).
+ installed (for example, perl5).
@@ -1119,7 +1122,7 @@
Ports of Perl modules which do not have an official
- website should link to cpan.org in
+ website must link to cpan.org in
the WWW line of pkg-descr. The
preferred URL form is
http://search.cpan.org/dist/Module-Name/
@@ -1168,7 +1171,7 @@
X.Org ComponentsThe X11 implementation available in The Ports Collection
- is X.Org. If your application depends on X components, set
+ is X.Org. If the application depends on X components, set
USE_XORG to the list of required
components. Available components, at the time of writing,
are:
@@ -1192,9 +1195,9 @@
/usr/ports/Mk/bsd.xorg.mk.The Mesa Project is an effort to provide free OpenGL
- implementation. You can specify a dependency on various
- components of this project with USE_GL
- variable. Valid options are:
+ implementation. To specify a dependency on various
+ components of this project, use USE_GL.
+ Valid options are:
egl, gl, glesv2, glew, glu, glut, glw and
linux. For backwards compatibility, the
value of yes maps to
@@ -1238,7 +1241,7 @@
Ports That Require Motif
- If your port requires a Motif library, define
+ If the port requires a Motif library, define
USES= motif in the
Makefile. Default Motif implementation
is
@@ -1246,11 +1249,11 @@
Users can choose
x11-toolkits/lesstif
instead by setting WANT_LESSTIF
- variable in their make.conf.
+ in their make.conf.
- The MOTIFLIB variable will be set by
+ MOTIFLIB will be set by
motif.mk to reference the
- appropriate Motif library. Please patch the source of your
+ appropriate Motif library. Please patch the source of the
port to use ${MOTIFLIB} wherever
the Motif library is referenced in the original
Makefile or
@@ -1263,7 +1266,7 @@
If the port refers to the Motif library as
-lXm in its
Makefile or
- Imakefile, simply substitute
+ Imakefile, substitute
${MOTIFLIB} for it.
@@ -1285,7 +1288,7 @@
X11 Fonts
- If your port installs fonts for the X Window System, put
+ If the port installs fonts for the X Window System, put
them in
LOCALBASE/lib/X11/fonts/local.
@@ -1295,7 +1298,7 @@
Some applications require a working X11 display for
compilation to succeed. This pose a problem for machines
- that operate headless. When the following variable is used,
+ that operate headless. When this variable is used,
the build infrastructure will start the virtual framebuffer
X server. The working DISPLAY is then passed
to the build. See
Ports that include predefined
- *.desktop files should
+ *.desktop must
include those files in pkg-plist
and install them in the
$LOCALBASE/share/applications
@@ -1350,14 +1353,14 @@
- Creating Desktop Entries with the
- DESKTOP_ENTRIES Macro
+ Creating Desktop Entries with
+ DESKTOP_ENTRIESDesktop entries can be easily created for applications
- by using the DESKTOP_ENTRIES variable. A
+ by using DESKTOP_ENTRIES. A
file named
name.desktop
- will be created, installed, and added to the
+ will be created, installed, and added to
pkg-plist automatically. Syntax
is:
@@ -1376,7 +1379,7 @@
after it has started. Programs that are not compatible
with startup notifications would never clear the indicator
(potentially confusing and infuriating the user), and
- should have StartupNotify set to
+ must have StartupNotify set to
false so the indicator is not shown at
all.
@@ -1407,12 +1410,12 @@
Ports That Require QtThe Ports Collection provides support for Qt 4 and Qt 5
- frameworks with the
- USE_QTx
- variable, where x is
+ frameworks with
+ USE_QTx,
+ where x is
4 or 5.
- USE_QTx should
- be set to the list of required Qt components (libraries,
+ Set USE_QTx
+ to the list of required Qt components (libraries,
tools, plugins). The Qt 4 and Qt 5 frameworks are quite
similar. The main difference is the set of supported
components.
@@ -1494,29 +1497,29 @@
Some configure scripts do not support the arguments above.
To suppress modification ofCONFIGURE_ENV
- and CONFIGURE_ARGS, set the
- QT_NONSTANDARD variable.
+ and CONFIGURE_ARGS, set
+ QT_NONSTANDARD.Component SelectionIndividual Qt tool and library dependencies must be
- specified in the
- USE_QTx
- variable. Every component can be suffixed with
+ specified in
+ USE_QTx.
+ Every component can be suffixed with
_build or _run, the
- suffix indicating whether the component should be depended on
+ suffix indicating whether the dependency on the component is
at buildtime or runtime. If unsuffixed, the component will be
depended on at both build- and runtime. Usually, library
- components should be specified unsuffixed, tool components
- should be specified with the _build suffix
- and plugin components should be specified with the
+ components are specified unsuffixed, tool components
+ are mostly specified with the _build suffix
+ and plugin components are specified with the
_run suffix. The most commonly used
components are listed below (all available components are
listed in _USE_QT_ALL,
_USE_QT4_ONLY, and
- _USE_QT5_ONLY variables in
+ _USE_QT5_ONLY in
/usr/ports/Mk/bsd.qt.mk):
@@ -1784,10 +1787,10 @@
Missing additional include
paths. Many applications come with
system tray icon support, but neglect to look for
- includes and/or libraries in the X11 directories. You
- can tell qmake to add directories to
- the include and library search paths via the command
- line, for example:
+ includes and/or libraries in the X11 directories. To add
+ directories to qmake's
+ include and library search paths via the command
+ line, use:
QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \
LIBS+=-L${LOCALBASE}/lib
@@ -1819,11 +1822,11 @@
USE_KDE4 to the list of required
components. _build and
_run suffixes can be used to force
- components dependency type (e.g.,
+ components dependency type (for example,
baseapps_run). If no suffix is set, a
- default dependency type will be used. If you want to force
+ default dependency type will be used. To force
both types, add the component twice with both suffixes
- (e.g., automoc4_build automoc4_run). The
+ (for example, automoc4_build automoc4_run). The
most commonly used components are listed below (up-to-date
components are documented at the top of
/usr/ports/Mk/bsd.kde4.mk):
@@ -1995,7 +1998,7 @@
determined through configure log.
USE_KDE4 does not imply
USE_QT4. If a port requires some
- Qt 4 components, they should be specified in
+ Qt 4 components, specify them in
USE_QT4.
USES= cmake:outsource
@@ -2011,14 +2014,14 @@
Variable Definitions
- If your port needs a Java™ Development Kit
- (JDK™) to either build, run or even extract the
- distfile, then it should define
+ If the port needs a Java™ Development Kit
+ (JDK™) to either build, run or even extract the
+ distfile, then 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
+ There are several JDKs in the ports collection, from
+ various vendors, and in several versions. If the port must
+ use one of these versions, define which one. The
most current version, and &os; default is
java/openjdk6.
@@ -2037,7 +2040,7 @@
USE_JAVA
- Should be defined for the remaining variables
+ Define for the remaining variables
to have any effect.
@@ -2045,21 +2048,21 @@
JAVA_VERSIONList of space-separated suitable Java versions
for the port. An optional "+"
- allows you to specify a range of versions (allowed
+ allows specifying a range of versions (allowed
values:
1.5[+] 1.6[+] 1.7[+]).JAVA_OS
- List of space-separated suitable JDK port
+ List of space-separated suitable JDK port
operating systems for the port (allowed values:
native linux).JAVA_VENDOR
- List of space-separated suitable JDK port
+ List of space-separated suitable JDK port
vendors for the port (allowed values:
freebsd bsdjava sun
openjdk).
@@ -2067,23 +2070,20 @@
JAVA_BUILD
- When set, it means that the selected JDK port
- should be added to the build dependencies of the
- port.
+ When set, add the selected JDK port to the build
+ dependencies.JAVA_RUN
- When set, it means that the selected JDK port
- should be added to the run dependencies of the
- port.
+ When set, add the selected JDK port to the run
+ dependencies.JAVA_EXTRACT
- When set, it means that the selected JDK port
- should be added to the extract dependencies of the
- port.
+ When set, add the selected JDK port to the
+ extract dependencies.
@@ -2106,61 +2106,61 @@
JAVA_PORT
- The name of the JDK port (e.g.,
- 'java/openjdk6').
+ The name of the JDK port (for example,
+ java/openjdk6).JAVA_PORT_VERSION
- The full version of the JDK port (e.g.,
- '1.6.0'). If you only need the
- first two digits of this version number, use
+ The full version of the JDK port (for example,
+ 1.6.0). Only the first two
+ digits of this version number are needed, use
${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}.JAVA_PORT_OS
- The operating system used by the JDK port
- (e.g., 'native').
+ The operating system used by the JDK port
+ (for example, 'native').JAVA_PORT_VENDOR
- The vendor of the JDK port (e.g.,
+ The vendor of the JDK port (for example,
'openjdk').JAVA_PORT_OS_DESCRIPTIONDescription of the operating system used by the
- JDK port (e.g.,
+ JDK port (for example,
'Native').JAVA_PORT_VENDOR_DESCRIPTION
- Description of the vendor of the JDK port
- (e.g., 'OpenJDK BSD Porting
+ Description of the vendor of the JDK port
+ (for example, 'OpenJDK BSD Porting
Team').JAVA_HOME
- Path to the installation directory of the JDK
- (e.g.,
+ Path to the installation directory of the JDK
+ (for example,
'/usr/local/openjdk6').JAVAC
- Path to the Java compiler to use (e.g.,
+ Path to the Java compiler to use (for example,
'/usr/local/openjdk6/bin/javac').JARPath to the jar tool to use
- (e.g.,
+ (for example,
'/usr/local/openjdk6/bin/jar'
or
'/usr/local/bin/fastjar').
@@ -2169,14 +2169,14 @@
APPLETVIEWERPath to the appletviewer
- utility (e.g.,
+ utility (for example,
'/usr/local/openjdk6/bin/appletviewer').JAVAPath to the java executable.
- Use this for executing Java programs (e.g.,
+ Use this for executing Java programs (for example,
'/usr/local/openjdk6/bin/java').
@@ -2242,7 +2242,7 @@
JAVA_CLASSES
- Path to the archive that contains the JDK class
+ Path to the archive that contains the JDK class
files,
${JAVA_HOME}/jre/lib/rt.jar.
@@ -2250,11 +2250,11 @@
- 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.
+ Use the java-debug make
+ target to get information for debugging the port. It will
+ display the value of many of the previously listed variables.
- Additionally, the following constants are defined so all
+ Additionally, these constants are defined so all
Java ports may be installed in a consistent way:
@@ -2278,7 +2278,7 @@
JAVAJARDIR
- The directory where JAR files should be
+ The directory where JAR files is
installed. Default:
${JAVASHAREDIR}/classes.
@@ -2305,37 +2305,37 @@
When 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
+ do-build target is defined by the port, a
+ default one will be set that runs Ant according to
MAKE_ENV, MAKE_ARGS
and ALL_TARGET. This is similar to the
- USES= gmake mechanism, which is
+ USES= gmake mechanism, which is
documented in .Best Practices
- When porting a Java library, your port should install
+ When porting a Java library, the port has to 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
+ the documentation, see below). To reduce the
+ packing file size, reference the JAR file(s)
+ directly in the Makefile. Use this
+ statement (where myport.jar
is the name of the JAR file installed as part of the
port):
- PLIST_FILES+= %%JAVAJARDIR%%/myport.jar
+ 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
+ whether the port installs the additional JAR
+ dependencies under this directory or uses the
already installed ones (from
${JAVAJARDIR}).
@@ -2343,13 +2343,13 @@
application server such as
www/tomcat7 to run the
service, it is quite common for a vendor to distribute a
- .war file. A .war
- file is a Web application ARchive and is extracted when
+ .war. A .war
+ is a Web application ARchive and is extracted when
called by the application. Avoid adding a
.war
- file to the pkg-plist.
+ to pkg-plist.
It is not considered best practice. An application server
- will expand the war archive, but not
+ will expand war archive, but not
clean it up properly if the port is removed. A more
desirable way of working with this file is to extract the
archive, then install the files, and lastly add these files
@@ -2367,19 +2367,19 @@
${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME}
@cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME}
- Regardless of the type of your port (library or
- application), the additional documentation should be
+ Regardless of the type of port (library or
+ application), the additional documentation is
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
+ 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
+ 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
+ one reason why porters are strongly encouraged to use
+ PORTDOCS. Moreover, even if the
+ set of files that will be generated by
+ javadoc can be predicted, the size of the resulting
pkg-plist advocates for the use of
PORTDOCS.
@@ -2389,7 +2389,7 @@
${JAVASHAREDIR}/${PORTNAME} for Java
ports. Indeed, DATADIR is automatically
added to PLIST_SUB (documented in
- ) so you may use
+ ) so use
%%DATADIR%% directly in
pkg-plist.
@@ -2403,21 +2403,21 @@
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
+ If the port needs more sophisticated
Java support, please first have a look at the bsd.java.mk
+ xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=log">bsd.java.mk
Subversion log as it
usually takes some time to document the latest features.
- Then, if you think the support you are lacking would be
+ Then, if the needed support that is 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
+ PRs, it refers to the JDK porting effort from the &os; Java
+ project. Therefore, submit the 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
+ unless the issue is related to
+ either a JDK implementation or
bsd.java.mk.Similarly, there is a defined policy regarding the
@@ -2454,13 +2454,13 @@
APXSFull path to the apxs
- binary. Can be overridden in your port.
+ binary. Can be overridden in the port.
HTTPDFull path to the httpd
- binary. Can be overridden in your port.
+ binary. Can be overridden in the port.
@@ -2555,9 +2555,9 @@
Web Applications
- Web applications should be installed into
+ Web applications must be installed into
PREFIX/www/appname.
- For your convenience, this path is available both in
+ This path is available both in
Makefile and in
pkg-plist as WWWDIR,
and the path relative to PREFIX is
@@ -2566,14 +2566,14 @@
The user and group of web server process are available
as WWWOWN and WWWGRP,
- in case you need to change the ownership of some files. The
- default values of both are www. If you
- want different values for your port, use
- WWWOWN?= myuser notation, to allow user
- to override it easily.
+ in case the ownership of some files needs to be changed. The
+ default values of both are www. Use
+ WWWOWN?= myuser and WWWGRP?=
+ mygroup if the port needs different values. This
+ allows the user to override them easily.Do not depend on Apache unless the web app explicitly
- needs Apache. Respect that users may wish to run your web
+ needs Apache. Respect that users may wish to run a web
app on different web server than Apache.
@@ -2668,7 +2668,7 @@
TESTS, DATA,
SQLS, SCRIPTFILES,
DOCS and EXAMPLES to
- list the files you want to install. All listed files will
+ list the files to install. All listed files will
be automatically installed into the appropriate locations
and added to pkg-plist.
@@ -2712,15 +2712,15 @@
Using PythonThe Ports Collection supports parallel installation of
- multiple Python versions. Ports should make sure to use a
+ multiple Python versions. Ports must use a
correct python interpreter, according to
- the user-settable PYTHON_VERSION variable.
+ the user-settable PYTHON_VERSION.
Most prominently, this means replacing the path to
python executable in scripts with the value
- of PYTHON_CMD variable.
+ of PYTHON_CMD.Ports that install files under
- PYTHON_SITELIBDIR should use the
+ PYTHON_SITELIBDIR must use the
pyXY- package name prefix, so their package
name embeds the version of Python they are installed
into.
@@ -2738,7 +2738,7 @@
can be specified with values such as
2.6+. Version ranges can also be
specified, by separating two version numbers with a
- dash, e.g.: 2.6-2.7
+ dash, for example, 2.6-2.7
@@ -2764,8 +2764,8 @@
PYTHON_SITELIBDIRLocation of the site-packages tree, that contains
installation path of Python (usually
- LOCALBASE). The
- PYTHON_SITELIBDIR variable can be
+ LOCALBASE).
+ PYTHON_SITELIBDIR can be
very useful when installing Python modules.
@@ -2830,8 +2830,8 @@
byte-compiled output file by -d.
-f is required to force recompilation, and
the :S;${PREFIX}/;; strips prefixes from
- the value of the PYTHONPREFIX_SITELIBDIR
- variable to make it relative to
+ the value of PYTHONPREFIX_SITELIBDIR
+ to make it relative to
PREFIX.
@@ -2844,7 +2844,7 @@
Tcl/Tk version and higher with
USES=tcl. It is possible to specify the
desired version of tcl by appending
- :xx, e.g.:
+ :xx, for example,
USES=tcl:85.
@@ -2959,12 +2959,11 @@
- The following table shows the selected variables available
+ This 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.
+ are 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.
+ possible. Do not redefine these variables in the port.
Selected Read-Only Variables for Ports That Use
@@ -3031,13 +3030,12 @@
Using SDL
- The USE_SDL variable is used to
+ USE_SDL is used to
autoconfigure the dependencies for ports which use an SDL
based library like devel/sdl12
and graphics/sdl_image.
- The following SDL libraries for version 1.2 are recognized
- at the moment:
+ These SDL libraries for version 1.2 are recognized:
@@ -3088,8 +3086,7 @@
- The following SDL libraries for version 2.0 are recognized
- at the moment:
+ These SDL libraries for version 2.0 are recognized:
@@ -3135,7 +3132,7 @@
and audio/sdl_mixer, is
automatically added as well.
- If you use USE_SDL with entries using
+ Using USE_SDL with entries for
SDL 1.2, it will automatically:
@@ -3151,12 +3148,12 @@
- Add the dependencies of the selected libraries to the
+ Add the dependencies of the selected libraries to
LIB_DEPENDS
- If you use USE_SDL with entries using
+ Using USE_SDL with entries for
SDL 2.0, it will automatically:
@@ -3172,13 +3169,13 @@
- Add the dependencies of the selected libraries to the
+ Add the dependencies of the selected libraries to
LIB_DEPENDS
- To check whether an SDL library is available, you can do
- it with the WANT_SDL variable:
+ To check whether an SDL library is available, use
+ WANT_SDL:WANT_SDL= yes
@@ -3223,7 +3220,7 @@
Version Selection
- To make your port use a specific version of
+ To make the port use a specific version of
wxWidgets there are two variables
available for defining (if only one is defined the other
will be set to a default value):
@@ -3250,16 +3247,16 @@
USE_WX_NOT
- List of versions the port can not use
+ List of versions the port cannot useNone
- The following is a list of available
+ The available
wxWidgets versions and the
- corresponding ports in the tree:
+ corresponding ports in the tree are:
Available wxWidgets
@@ -3305,7 +3302,7 @@
The variables in can
- be set to one or more of the following combinations
+ be set to one or more of these combinations
separated by spaces:
@@ -3381,8 +3378,8 @@
There are other applications that, while not being
wxWidgets libraries, are related
- to them. These applications can be specified in the
- WX_COMPS variable. The following
+ to them. These applications can be specified in
+ WX_COMPS. These
components are available:
@@ -3436,7 +3433,7 @@
The dependency type can be selected for each component
by adding a suffix separated by a semicolon. If not present
then a default type will be used (see
- ). The following types
+ ). These types
are available:
@@ -3474,7 +3471,7 @@
The default values for the components are detailed in
- the following table:
+ this table:
Default wxWidgets
@@ -3521,7 +3518,7 @@
Selecting wxWidgets
Components
- The following fragment corresponds to a port which
+ This fragment corresponds to a port which
uses wxWidgets version
2.4 and its contributed
libraries.
@@ -3537,7 +3534,7 @@
The wxWidgets library
supports Unicode since version 2.5. In
the ports tree both versions are available and can be
- selected with the following variables:
+ selected with these variables:
Variables to Select Unicode in
@@ -3587,8 +3584,8 @@
Do not use WX_UNICODE for ports
- that can use both Unicode and normal versions. If you
- want the port to use Unicode by default define
+ that can use both Unicode and normal versions. If
+ the port needs to use Unicode by default, define
WANT_UNICODE instead.
@@ -3596,10 +3593,10 @@
Detecting Installed Versions
- To detect an installed version you have to define
- WANT_WX. If you do not set it to a
+ To detect an installed version, define
+ WANT_WX. If it is not set to a
specific version then the components will have a version
- suffix. The HAVE_WX variable will be
+ suffix. HAVE_WX will be
filled after detection.
@@ -3607,7 +3604,7 @@
wxWidgets Versions and
Components
- The following fragment can be used in a port that uses
+ This fragment can be used in a port that uses
wxWidgets if it is installed,
or an option is selected.
@@ -3620,7 +3617,7 @@
CONFIGURE_ARGS+= --enable-wx
.endif
- The following fragment can be used in a port that
+ This fragment can be used in a port that
enables wxPython support if it
is installed or if an option is selected, in addition to
wxWidgets, both version
@@ -3642,7 +3639,7 @@
Defined Variables
- The following variables are available in the port (after
+ These variables are available in the port (after
defining one from
).
@@ -3678,7 +3675,7 @@
WX_VERSIONThe wxWidgets
- version that is going to be used (e.g.,
+ version that is going to be used (for example,
2.6)
@@ -3696,14 +3693,14 @@
Processing in
bsd.port.pre.mk
- If you need to use the variables for running commands
- right after including bsd.port.pre.mk
- you need to define WX_PREMK.
+ Define WX_PREMK to be able to use the
+ variables right after including
+ bsd.port.pre.mk.
- If you define WX_PREMK, then the
+ When defining WX_PREMK, then the
version, dependencies, components and defined variables
- will not change if you modify the
+ will not change if modifying the
wxWidgets port variables
after including
bsd.port.pre.mk.
@@ -3713,7 +3710,7 @@
Using wxWidgets Variables
in Commands
- The following fragment illustrates the use of
+ This fragment illustrates the use of
WX_PREMK by running the
wx-config script to obtain the full
version string, assign it to a variable and pass it to the
@@ -3742,11 +3739,11 @@
Additional configure
Arguments
- Some GNU configure scripts can not
+ Some GNU configure scripts cannot
find wxWidgets with just the
WX_CONFIG environment variable set,
- requiring additional arguments. The
- WX_CONF_ARGS variable can be used for
+ requiring additional arguments.
+ WX_CONF_ARGS can be used for
provide them.
@@ -3805,7 +3802,7 @@
Version SelectionA port using Lua only needs to
- have the following line:
+ have this line:
USES= lua
@@ -3818,7 +3815,7 @@
Defined Variables
- The following variables are available in the port.
+ These variables are available in the port.
Variables Defined for Ports That Use
@@ -3836,14 +3833,14 @@
LUA_VERThe Lua version that
- is going to be used (e.g.,
+ is going to be used (for example,
5.1)LUA_VER_STRThe Lua version
- without the dots (e.g.,
+ without the dots (for example,
51)
@@ -4059,14 +4056,14 @@
Using Xfce
- The USE_XFCE variable is used to
+ USE_XFCE is used to
autoconfigure the dependencies for ports which use an Xfce
based library or application like
x11-toolkits/libxfce4gui
and x11-wm/xfce4-panel.
- The following Xfce libraries and applications are
- recognized at the moment:
+ These Xfce libraries and applications are
+ recognized:
@@ -4115,11 +4112,11 @@
- The following additional parameters are recognized:
+ These additional parameters are recognized:
- configenv: Use this if your port requires a special
+ configenv: Use this if the port requires a special
modified CONFIGURE_ENV to find its
required libraries.
@@ -4154,7 +4151,7 @@
(libxul.so),
seamonkey
(libgtkembedmoz.so, deprecated,
- should not be used any more).
+ must not be used any more).
@@ -4180,7 +4177,7 @@
The port requires SeaMonkey as a runtime
dependency. Possible values: yes
(get default version), 20,
- 11 (deprecated, should not be used
+ 11 (deprecated, must not be used
any more). Default dependency is on version
20.
@@ -4198,7 +4195,7 @@
The port requires Thunderbird as a runtime
dependency. Possible values: yes
(get default version), 31,
- 30 (deprecated, should not be used
+ 30 (deprecated, must not be used
any more). Default dependency is on version
31.
@@ -4239,7 +4236,7 @@
add dependency on
databases/db41
port. The variable may also be set to values: 40, 41,
- 42, 43, 44, 46, 47, 48, or 51. You can declare a
+ 42, 43, 44, 46, 47, 48, or 51. It is possible to declare a
range of acceptable values,
USE_BDB=42+ will find the highest
installed version, and fall back to 42 if nothing else
@@ -4264,7 +4261,7 @@
role="port">databases/postgresql90-client
port. An associated variable,
WANT_PGSQL_VER, may be set to
- values such as 83, 84, 90, 91 or 92. You can declare
+ values such as 83, 84, 90, 91 or 92. It is possible to declare
a minimum or maximum value;
WANT_PGSQL_VER=
90+ will cause the port to depend on a
@@ -4334,7 +4331,7 @@
# REQUIRE: LOGIN
# KEYWORD: shutdown
#
-# Add the following lines to /etc/rc.conf.local or /etc/rc.conf
+# Add these lines to /etc/rc.conf.local or /etc/rc.conf
# to enable this service:
#
# doormand_enable (bool): Set to NO by default.
@@ -4360,7 +4357,7 @@
run_rc_command "$1"
Unless there is a good reason to start the service
- earlier all ports scripts should use
+ earlier, all ports scripts should useREQUIRE: LOGIN
@@ -4370,7 +4367,7 @@
KEYWORD: shutdownis included in the script above because the mythical port
- we are using as an example starts a service, and should be
+ we are using as an example starts a service, and it must be
shut down cleanly when the system shuts down. If the script
is not starting a persistent service this is not
necessary.
@@ -4384,18 +4381,18 @@
doormand_flags=""
- in their rc.conf.local file, and a
+ in their rc.conf.local, and a
variable substitution using ":=" would
inappropriately override the user's intention. The
_enable variable is not optional,
- and should use the ":" for the default.
+ and must use the ":" for the default.Pre-Commit ChecklistBefore contributing a port with an
rc.d script, and more importantly,
- before committing one, please consult the following
+ before committing one, please consult this
checklist to be sure that it is ready.The devel/rclint
@@ -4404,9 +4401,9 @@
- If this is a new file, does it have
- .sh in the file name? If so that
- should be changed to just file.in
+ If this is a new file, does it have a
+ .sh extension? If so, that
+ must be changed to just file.in
since rc.d files may not end
with that extension.
@@ -4427,8 +4424,8 @@
file name and
$name
makes it easier to figure out which variables are
- relevant in rc.conf[.local]. The
- latter is also what you might call “policy”
+ relevant in rc.conf[.local]. It is
+ also a policy
for all new scripts, including those in the base
system.
@@ -4438,15 +4435,15 @@
LOGIN? This is mandatory for scripts
that run as a non-root user. If it runs as root, is
there a good reason for it to run prior to
- LOGIN? If not, it should run there
- so that we can loosely group local scripts to a point in
+ LOGIN? If not, it must run after
+ so that local scrips can be loosely grouped to a point in
&man.rcorder.8; after most everything in the base is
already running.Does the script start a persistent service? If so,
- it should have KEYWORD:
+ it must have KEYWORD:
shutdown.
@@ -4455,7 +4452,7 @@
KEYWORD: &os; present. This has
not been necessary or desirable for years. It is also
an indication that the new script was copy/pasted from
- an old script, so extra caution should be given to the
+ an old script, so extra caution must be given to the
review.
@@ -4464,7 +4461,7 @@
perl, python, or
ruby, make certain that
command_interpreter is set
- appropriately, e.g., for Perl,
+ appropriately, for example, for Perl,
by adding PERL=${PERL} to
SUB_LIST and using
%%PERL%%. Otherwise,
@@ -4501,7 +4498,7 @@
Are options listed in the default
name_flags
- things that are actually mandatory? If so, they should
+ things that are actually mandatory? If so, they must
be in command_args. The
option is a red flag (pardon the
pun) here, since it is usually the option to
@@ -4510,22 +4507,21 @@
- The
- name_flags
- variable should never be included in
+ name_flags
+ must never be included in
command_args (and vice versa,
although that error is less common).Does the script execute any code unconditionally?
- This is frowned on. Usually these things can/should be
+ This is frowned on. Usually these things must be
dealt with through a
start_precmd.
- All boolean tests should utilize the
+ All boolean tests must use the
checkyesno function. No
hand-rolled tests for [Yy][Ee][Ss],
etc.
@@ -4541,7 +4537,7 @@
Does the script create files or directories that
need specific permissions, for example, a
- pid file that needs to be owned by
+ pid that needs to be owned by
the user that runs the process? Rather than the
traditional &man.touch.1;/&man.chown.8;/&man.chmod.1;
routine, consider using &man.install.1; with the proper
@@ -4558,16 +4554,16 @@
Some ports require a certain user to be on the installed
system. Choose a free UID from 50 to 999 and register it
either in ports/UIDs (for users) or in
- ports/GIDs (for groups). Make sure you
- do not use a UID already used by the system or other
+ ports/GIDs (for groups). Make sure
+ not to use a UID already used by the system or other
ports.
- Please include a patch against these two files when you
- require a new user or group to be created for your
+ Please include a patch against these two files when
+ requiring a new user or group to be created for the
port.
- Then you can use USERS and
- GROUPS variables in your
+ Then use USERS and
+ GROUPS in
Makefile, and the user will be
automatically created when installing the port.