Index: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml +++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml @@ -10,16 +10,15 @@ 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. Staging bsd.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.so The 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. <varname>NO_PACKAGE</varname> @@ -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 @@ <varname>NOFETCHFILES</varname> - 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 @@ <varname>LEGAL_TEXT</varname> If 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 @@ <command>configure</command> 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 @@ </table> <table frame="none" xml:id="using-cmake-user-variables"> - <title>Variables the Users can define for - <command>cmake</command> builds + Variables the Users Can Define for + <command>cmake</command> 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 @@ <literal>USES= cmake</literal> 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 <command>scons</command> - 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 <application>Perl</application> If 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_VERSION The full version of Perl - installed (e.g., 5.8.9). + installed (for example, 5.8.9). PERL_LEVEL The installed Perl version as an integer of the form MNNNPP - (e.g., 500809). + (for example, 500809). @@ -1104,7 +1107,7 @@ PERL_PORT Name 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 Components The 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 - <varname>DESKTOP_ENTRIES</varname> Macro + Creating Desktop Entries with + <varname>DESKTOP_ENTRIES</varname> Desktop 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 Qt The 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 Selection Individual 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_DESCRIPTION Description 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'). JAR Path to the jar tool to use - (e.g., + (for example, '/usr/local/openjdk6/bin/jar' or '/usr/local/bin/fastjar'). @@ -2169,14 +2169,14 @@ APPLETVIEWER Path to the appletviewer - utility (e.g., + utility (for example, '/usr/local/openjdk6/bin/appletviewer'). JAVA Path 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.jar When 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 @@ APXS Full path to the apxs - binary. Can be overridden in your port. + binary. Can be overridden in the port. HTTPD Full 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 Python The 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_SITELIBDIR Location 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 @@ <sect1 xml:id="using-sdl"> <title>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 use None
- 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 <application>wxWidgets</application> @@ -3305,7 +3302,7 @@ </note> <para>The variables in <xref linkend="wx-ver-sel-table"/> can - be set to one or more of the following combinations + be set to one or more of these combinations separated by spaces:</para> <table frame="none" xml:id="wx-widgets-versions-specification"> @@ -3381,8 +3378,8 @@ <para>There are other applications that, while not being <application>wxWidgets</application> libraries, are related - to them. These applications can be specified in the - <varname>WX_COMPS</varname> variable. The following + to them. These applications can be specified in + <varname>WX_COMPS</varname>. These components are available:</para> <table frame="none" xml:id="wx-widgets-components-table"> @@ -3436,7 +3433,7 @@ <para>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 - <xref linkend="wx-def-dep-types"/>). The following types + <xref linkend="wx-def-dep-types"/>). These types are available:</para> <table frame="none" xml:id="wx-widgets-dependency-table"> @@ -3474,7 +3471,7 @@ </table> <para>The default values for the components are detailed in - the following table:</para> + this table:</para> <table xml:id="wx-def-dep-types" frame="none"> <title>Default <application>wxWidgets</application> @@ -3521,7 +3518,7 @@ <title>Selecting <application>wxWidgets</application> 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 @@ <warning> <para>Do not use <varname>WX_UNICODE</varname> 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 <varname>WANT_UNICODE</varname> instead.</para> </warning> </sect2> @@ -3596,10 +3593,10 @@ <sect2 xml:id="wx-version-detection"> <title>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_VERSION The 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 <filename>bsd.port.pre.mk</filename> - 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 <application>wxWidgets</application> 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 <command>configure</command> 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 @@ <row> <entry><varname>LUA_VER</varname></entry> <entry>The <application>Lua</application> version that - is going to be used (e.g., + is going to be used (for example, <literal>5.1</literal>)</entry> </row> <row> <entry><varname>LUA_VER_STR</varname></entry> <entry>The <application>Lua</application> version - without the dots (e.g., + without the dots (for example, <literal>51</literal>)</entry> </row> @@ -4059,14 +4056,14 @@ <sect1 xml:id="using-xfce"> <title>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 use REQUIRE: LOGIN @@ -4370,7 +4367,7 @@ KEYWORD: shutdown is 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 Checklist Before 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.