diff --git a/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml index 14cc8be8fc..46a8effb3f 100644 --- a/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml +++ b/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml @@ -5,720 +5,715 @@ $FreeBSD$ --> - + - Dos and Don'ts + Dos and Don'ts - - Introduction + + Introduction - Here is a list of common dos and don'ts that are - encountered during the porting process. Check the port - against this list, but also check ports in the PR - database that others have submitted. Submit any - comments on ports you check as described in Bug - Reports and General Commentary. Checking ports in - the PR database will both make it faster for us to commit - them, and prove that you know what you are doing. - + Here is a list of common dos and don'ts that are encountered + during the porting process. Check the port against this list, + but also check ports in the PR + database that others have submitted. Submit any + comments on ports you check as described in Bug + Reports and General Commentary. Checking ports in the + PR database will both make it faster for us to commit them, and + prove that you know what you are doing. + - - <varname>WRKDIR</varname> + + <varname>WRKDIR</varname> - Do not write anything to files outside - WRKDIR. WRKDIR is the - only place that is guaranteed to be writable during the port - build (see - installing ports from a CDROM for an example of - building ports from a read-only tree). If you need to modify - one of the pkg-* files, do so by - redefining a variable, - not by writing over it. - + Do not write anything to files outside + WRKDIR. WRKDIR is the + only place that is guaranteed to be writable during the port + build (see + installing ports from a CDROM for an example of + building ports from a read-only tree). If you need to modify + one of the pkg-* files, do so by + redefining a variable, + not by writing over it. + - - <varname>WRKDIRPREFIX</varname> + + <varname>WRKDIRPREFIX</varname> - Make sure your port honors - WRKDIRPREFIX. Most ports do not have to - worry about this. In particular, if you are referring to a - WRKDIR of another port, note that the - correct location is - WRKDIRPREFIXPORTSDIR/subdir/name/work - not - PORTSDIR/subdir/name/work - or - .CURDIR/../../subdir/name/work - or some such. + Make sure your port honors WRKDIRPREFIX. + Most ports do not have to worry about this. In particular, if + you are referring to a WRKDIR of another + port, note that the correct location is + WRKDIRPREFIXPORTSDIR/subdir/name/work not + PORTSDIR/subdir/name/work or + .CURDIR/../../subdir/name/work or some + such. - Also, if you are defining WRKDIR - yourself, make sure you prepend - ${WRKDIRPREFIX}${.CURDIR} in - the front. - + Also, if you are defining WRKDIR + yourself, make sure you prepend + ${WRKDIRPREFIX}${.CURDIR} in + the front. + - - Differentiating Operating Systems and OS Versions + + Differentiating Operating Systems and OS Versions - You may come across code that needs modifications or - conditional compilation based upon what version of &os; Unix - it is running under. The preferred way to tell &os; versions - apart are the __FreeBSD_version and - __FreeBSD__ macros defined in sys/param.h. - If this file is not included add the code, + You may come across code that needs modifications or + conditional compilation based upon what version of &os; Unix it + is running under. The preferred way to tell &os; versions apart + are the __FreeBSD_version and + __FreeBSD__ macros defined in sys/param.h. + If this file is not included add the code, - #include <sys/param.h> + #include <sys/param.h> - to the proper place in the .c - file. + to the proper place in the .c + file. - __FreeBSD__ is defined in all - versions of &os; as their major version number. For - example, in &os; 9.x, __FreeBSD__ is - defined to be 9. + __FreeBSD__ is defined in all versions + of &os; as their major version number. For example, in &os; + 9.x, __FreeBSD__ is defined to be + 9. - #if __FreeBSD__ >= 9 + #if __FreeBSD__ >= 9 # if __FreeBSD_version >= 901000 /* 9.1+ release specific code here */ # endif #endif - + - - Writing Something After - <filename>bsd.port.mk</filename> + + Writing Something After + <filename>bsd.port.mk</filename> - Do not write anything after the .include - <bsd.port.mk> line. It usually can be - avoided by including bsd.port.pre.mk - somewhere in the middle of your Makefile - and bsd.port.post.mk at the end. + Do not write anything after the + .include <bsd.port.mk> line. It + usually can be avoided by including + bsd.port.pre.mk somewhere in the middle of + your Makefile and + bsd.port.post.mk at the end. - - Include either the - bsd.port.pre.mk/bsd.port.post.mk - pair or bsd.port.mk only; do not mix - these two usages. - + + Include either the + bsd.port.pre.mk/bsd.port.post.mk + pair or bsd.port.mk only; do not mix + these two usages. + - bsd.port.pre.mk only defines a few - variables, which can be used in tests in the - Makefile, - bsd.port.post.mk defines the rest. + bsd.port.pre.mk only defines a few + variables, which can be used in tests in the + Makefile, + bsd.port.post.mk defines the rest. - Here are some important variables defined in - bsd.port.pre.mk (this is not the complete - list, please read bsd.port.mk for the - complete list). + Here are some important variables defined in + bsd.port.pre.mk (this is not the complete + list, please read bsd.port.mk for the + complete list). - - - - - Variable - Description - - + + + + + Variable + Description + + - - - ARCH - The architecture as returned by uname - -m (e.g., i386) - + + + ARCH + The architecture as returned by uname + -m (e.g., i386) + - - OPSYS - The operating system type, as returned by - uname -s (e.g., - FreeBSD) - + + OPSYS + The operating system type, as returned by + uname -s (e.g., + FreeBSD) + - - OSREL - The release version of the operating system - (e.g., 2.1.5 or - 2.2.7) - + + OSREL + The release version of the operating system + (e.g., 2.1.5 or + 2.2.7) + - - OSVERSION - The numeric version of the operating system; the - same as __FreeBSD_version. - + + OSVERSION + The numeric version of the operating system; the + same as __FreeBSD_version. + - - LOCALBASE - The base of the local tree (e.g., - /usr/local) - + + LOCALBASE + The base of the local tree (e.g., + /usr/local) + - - PREFIX + + PREFIX - Where the port installs itself (see - more on - PREFIX). - - - - + Where the port installs itself (see + more on + PREFIX). + + + + - - If you have to define the variable - MASTERDIR, do so before including - bsd.port.pre.mk. - + + If you have to define the variable + MASTERDIR, do so before including + bsd.port.pre.mk. + - Here are some examples of things you can write after - bsd.port.pre.mk: + Here are some examples of things you can write after + bsd.port.pre.mk: - # no need to compile lang/perl5 if perl5 is already in system + # no need to compile lang/perl5 if perl5 is already in system .if ${OSVERSION} > 300003 BROKEN= perl is in system .endif - You did remember to use tab instead of spaces after - BROKEN= and - :-). - + You did remember to use tab instead of spaces after + BROKEN= and + :-). + - - Use the <function>exec</function> Statement in Wrapper - Scripts + + Use the <function>exec</function> Statement in Wrapper + Scripts - If the port installs a shell script whose purpose is to - launch another program, and if launching that program is the - last action performed by the script, make sure to launch the - program using the exec statement, for - instance: + If the port installs a shell script whose purpose is to + launch another program, and if launching that program is the + last action performed by the script, make sure to launch the + program using the exec statement, for + instance: - #!/bin/sh + #!/bin/sh exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@" - The exec statement replaces the shell - process with the specified program. If - exec is omitted, the shell process - remains in memory while the program is executing, and - needlessly consumes system resources. - - - - Do Things Rationally - - The Makefile should do things simply - and reasonably. If you can make it a couple of lines shorter - or more readable, then do so. Examples include using a make - .if construct instead of a shell - if construct, not redefining - do-extract if you can redefine - EXTRACT* instead, and using - GNU_CONFIGURE instead of - CONFIGURE_ARGS - += --prefix=${PREFIX}. - - If you find yourself having to write a lot of new code to - try to do something, please go back and review - bsd.port.mk to see if it contains an - existing implementation of what you are trying to do. While - hard to read, there are a great many seemingly-hard problems - for which bsd.port.mk already provides a - shorthand solution. - - - - Respect Both <varname>CC</varname> and - <varname>CXX</varname> - - The port must respect both CC and - CXX variables. What we mean by this is - that the port must not set the values of these variables - absolutely, overriding existing values; instead, it may - append whatever values it needs to the existing values. This - is so that build options that affect all ports can be set - globally. - - If the port does not respect these variables, - please add - NO_PACKAGE=ignores either cc or cxx to the - Makefile. - - An example of a Makefile respecting - both CC and CXX - variables follows. Note the ?=: - - CC?= gcc - - CXX?= g++ - - Here is an example which respects neither - CC nor CXX - variables: - - CC= gcc - - CXX= g++ - - Both CC and CXX - variables can be defined on &os; systems in - /etc/make.conf. The first example - defines a value if it was not previously set in - /etc/make.conf, preserving any - system-wide definitions. The second example clobbers - anything previously defined. - - - - Respect <varname>CFLAGS</varname> - - The port must respect the CFLAGS - variable. What we mean by this is that the port must not - set the value of this variable absolutely, overriding the - existing value; instead, it may append whatever values it - needs to the existing value. This is so that build options - that affect all ports can be set globally. - - If it does not, please add - NO_PACKAGE=ignores cflags to the - Makefile. - - An example of a Makefile respecting - the CFLAGS variable follows. Note the - +=: - - CFLAGS+= -Wall -Werror - - Here is an example which does not respect the - CFLAGS variable: - - CFLAGS= -Wall -Werror - - The CFLAGS variable is defined on - &os; systems in /etc/make.conf. The - first example appends additional flags to the - CFLAGS variable, preserving any system-wide - definitions. The second example clobbers anything previously - defined. - - You should remove optimization flags from the third party - Makefiles. System - CFLAGS contains system-wide optimization - flags. An example from an unmodified - Makefile: - - CFLAGS= -O3 -funroll-loops -DHAVE_SOUND - - Using system optimization flags, the - Makefile would look similar to the - following example: - - CFLAGS+= -DHAVE_SOUND - - - - Threading Libraries - - The threading library must be linked to the binaries using - a special flag -pthread on &os;. If - a port insists on linking -lpthread - directly, patch it to use -pthread. - - - If building the port errors out with - unrecognized option '-pthread', it may be - desirable to use cc as linker by setting - CONFIGURE_ENV to - LD=${CC}. The - -pthread option is not supported by - ld directly. - - - - - Feedback - - Do send applicable changes/patches to the original - author/maintainer for inclusion in next release of the code. - This will only make your job that much easier for the next - release. - - - - <filename>README.html</filename> - - README.html is not part of the port, - but generated by make readme. Do not - include this file in patches or commits. - - - If make readme fails, make sure that - the default value of ECHO_MSG has not - been modified by the port. - - - - - Marking a Port Not Installable with - <varname>BROKEN</varname>, <varname>FORBIDDEN</varname>, or - <varname>IGNORE</varname> - - In certain cases users should be prevented from installing - a port. To tell a user that a port should not be installed, - there are several make variables that can - be used in a port's Makefile. The value - of the following make variables will be the - reason that is given back to users for why the port refuses to - install itself. Please use the correct - make variable as each make variable conveys - radically different meanings to both users, and to automated - systems that depend on the Makefiles, - such as the ports build - cluster, FreshPorts, - and portsmon. - - - Variables - - - - BROKEN is reserved for ports that - currently do not compile, install, or deinstall - correctly. It should be used for ports where the - problem is believed to be temporary. - - If instructed, the build cluster will still attempt - to try to build them to see if the underlying problem - has been resolved. (However, in general, the cluster is - run without this.) - - For instance, use BROKEN when a - port: - - - - does not compile - - - - fails its configuration or installation - process - - - - installs files outside of - ${LOCALBASE} - - - - does not remove all its files cleanly upon - deinstall (however, it may be acceptable, and - desirable, for the port to leave user-modified files - behind) - - - - - - FORBIDDEN is used for ports that - contain a security vulnerability or induce grave concern - regarding the security of a &os; system with a given - port installed (e.g., a reputably insecure program or a - program that provides easily exploitable services). - Ports should be marked as FORBIDDEN - as soon as a particular piece of software has a - vulnerability and there is no released upgrade. Ideally - ports should be upgraded as soon as possible when a - security vulnerability is discovered so as to reduce the - number of vulnerable &os; hosts (we like being known - for being secure), however sometimes there is a - noticeable time gap between disclosure of a - vulnerability and an updated release of the vulnerable - software. Do not mark a port - FORBIDDEN for any reason other than - security. - - - - IGNORE is reserved for ports that - should not be built for some other reason. It should be - used for ports where the problem is believed to be - structural. The build cluster will not, under any - circumstances, build ports marked as - IGNORE. For instance, use - IGNORE when a port: - - - - compiles but does not run properly - - - - does not work on the installed version of - &os; - - - - has a distfile which may not be automatically - fetched due to licensing restrictions - - - - does not work with some other currently - installed port (for instance, the port depends on - www/apache20 but - www/apache22 is - installed) - - - - - If a port would conflict with a currently - installed port (for example, if they install a file in - the same place that performs a different function), - use - CONFLICTS instead. - CONFLICTS will set - IGNORE by itself. - - - - - If a port should be marked IGNORE - only on certain architectures, there are two other - convenience variables that will automatically set - IGNORE for you: - ONLY_FOR_ARCHS and - NOT_FOR_ARCHS. Examples: - - ONLY_FOR_ARCHS= i386 amd64 - - NOT_FOR_ARCHS= ia64 sparc64 - - A custom IGNORE message can be - set using ONLY_FOR_ARCHS_REASON and - NOT_FOR_ARCHS_REASON. Per - architecture entries are possible with - ONLY_FOR_ARCHS_REASON_ARCH - and - NOT_FOR_ARCHS_REASON_ARCH. - - - - If a port fetches i386 binaries and installs them, - IA32_BINARY_PORT should be set. If - this variable is set, it will be checked whether the - /usr/lib32 directory is available - for IA32 versions of libraries and whether the kernel - has IA32 compatibility compiled in. If one of these two - dependencies is not satisfied, IGNORE - will be set automatically. - - - - - - Implementation Notes - - The strings should not be quoted. - Also, the wording of the string should be somewhat - different due to the way the information is shown to the - user. Examples: - - BROKEN= fails to link with base -lcrypto - - IGNORE= unsupported on recent versions - - resulting in the following output from - make describe: - - ===> foobar-0.1 is marked as broken: fails to link with base -lcrypto. - - ===> foobar-0.1 is unsupported on recent versions. - - - - - Marking a Port for Removal with - <varname>DEPRECATED</varname> or - <varname>EXPIRATION_DATE</varname> - - Do remember that BROKEN and - FORBIDDEN are to be used as a temporary - resort if a port is not working. Permanently broken ports - should be removed from the tree entirely. - - When it makes sense to do so, users can be warned about - a pending port removal with DEPRECATED - and EXPIRATION_DATE. The former is - simply a string stating why the port is scheduled for removal; - the latter is a string in ISO 8601 format (YYYY-MM-DD). Both - will be shown to the user. - - It is possible to set DEPRECATED - without an EXPIRATION_DATE (for instance, - recommending a newer version of the port), but the converse - does not make any sense. - - There is no set policy on how much notice to give. - Current practice seems to be one month for security-related - issues and two months for build issues. This also gives any - interested committers a little time to fix the - problems. - - - - Avoid Use of the <literal>.error</literal> - Construct - - The correct way for a Makefile to - signal that the port can not be installed due to some external - factor (for instance, the user has specified an illegal - combination of build options) is to set a non-blank value to - IGNORE. This value will be formatted and - shown to the user by make install. - - It is a common mistake to use .error - for this purpose. The problem with this is that many - automated tools that work with the ports tree will fail in - this situation. The most common occurrence of this is seen - when trying to build /usr/ports/INDEX - (see ). However, even more - trivial commands such as make maintainer - also fail in this scenario. This is not acceptable. - - - How to Avoid Using <literal>.error</literal> - - The first of the - next two Makefile snippets will cause - make index to fail, while the second one - will not: - - .error "option is not supported" - - IGNORE=option is not supported - - - - - Usage of <filename>sysctl</filename> - - The usage of sysctl is discouraged - except in targets. This is because the evaluation of any - makevars, such as used during - make index, then has to run the command, - further slowing down that process. - - Usage of &man.sysctl.8; should always be done with the - SYSCTL variable, as it contains the fully - qualified path and can be overridden, if one has such a - special need. - - - - Rerolling Distfiles - - Sometimes the authors of software change the content of - released distfiles without changing the file's name. You have - to verify that the changes are official and have been - performed by the author. It has happened in the past that the - distfile was silently altered on the download servers with the - intent to cause harm or compromise end user security. - - Put the old distfile aside, download the new one, unpack - them and compare the content with &man.diff.1;. If you see - nothing suspicious, you can update - distinfo. Be sure to summarize the - differences in your PR or commit log, so that other people - know that you have taken care to ensure that nothing bad has - happened. - - You might also want to contact the authors of the software - and confirm the changes with them. - - - - Avoiding Linuxisms - - Do not use /proc if there are any - other ways of getting the information, e.g., - setprogname(argv[0]) in - main() and then &man.getprogname.3; if - you want to know your name. - - Do not rely on behaviour that is undocumented by - POSIX. - - Do not record timestamps in the critical path of the - application if it also works without. Getting timestamps may - be slow, depending on the accuracy of timestamps in the - OS. If timestamps are really needed, - determine how precise they have to be and use an - API which is documented to just deliver the - needed precision. - - A number of simple syscalls (for example - &man.gettimeofday.2;, &man.getpid.2;) are much faster on - &linux; than on any other operating system due to caching and - the vsyscall performance optimizations. Do not rely on them - being cheap in performance-critical applications. In general, - try hard to avoid syscalls if possible. - - Do not rely on &linux;-specific socket behaviour. In - particular, default socket buffer sizes are different (call - &man.setsockopt.2; with SO_SNDBUF and - SO_RCVBUF, and while &linux;'s &man.send.2; - blocks when the socket buffer is full, &os;'s will fail and - set ENOBUFS in errno. - - If relying on non-standard behaviour is required, - encapsulate it properly into a generic API, - do a check for the behaviour in the configure stage, and stop - if it is missing. - - Check the - man - pages to see if the function used is a - POSIX interface (in the - STANDARDS section of the man page). - - Do not assume that /bin/sh is - bash. Ensure that a command line - passed to &man.system.3; will work with a - POSIX compliant shell. - - A list of common bashisms is - available here. - - Check that headers are included in the - POSIX or man page recommended way, e.g., - sys/types.h is often forgotten, which is - not as much of a problem for &linux; as it is for &os;. - - Compile threaded applications with - -pthread, not -lpthread or - variations thereof. - - - - Miscellanea - - The files pkg-descr and - pkg-plist should each be double-checked. - If you are reviewing a port and feel they can be worded - better, do so. - - Do not copy more copies of the GNU General Public License - into our system, please. - - Please be careful to note any legal issues! Do not let us - illegally distribute software! - - - + The exec statement replaces the shell + process with the specified program. If + exec is omitted, the shell process remains + in memory while the program is executing, and needlessly + consumes system resources. + + + + Do Things Rationally + + The Makefile should do things simply + and reasonably. If you can make it a couple of lines shorter or + more readable, then do so. Examples include using a make + .if construct instead of a shell + if construct, not redefining + do-extract if you can redefine + EXTRACT* instead, and using + GNU_CONFIGURE instead of + CONFIGURE_ARGS + += --prefix=${PREFIX}. + + If you find yourself having to write a lot of new code to + try to do something, please go back and review + bsd.port.mk to see if it contains an + existing implementation of what you are trying to do. While + hard to read, there are a great many seemingly-hard problems for + which bsd.port.mk already provides a + shorthand solution. + + + + Respect Both <varname>CC</varname> and + <varname>CXX</varname> + + The port must respect both CC and + CXX variables. What we mean by this is that + the port must not set the values of these variables absolutely, + overriding existing values; instead, it may append whatever + values it needs to the existing values. This is so that build + options that affect all ports can be set globally. + + If the port does not respect these variables, + please add + NO_PACKAGE=ignores either cc or cxx to the + Makefile. + + An example of a Makefile respecting + both CC and CXX + variables follows. Note the ?=: + + CC?= gcc + + CXX?= g++ + + Here is an example which respects neither + CC nor CXX + variables: + + CC= gcc + + CXX= g++ + + Both CC and CXX + variables can be defined on &os; systems in + /etc/make.conf. The first example defines + a value if it was not previously set in + /etc/make.conf, preserving any system-wide + definitions. The second example clobbers anything previously + defined. + + + + Respect <varname>CFLAGS</varname> + + The port must respect the CFLAGS + variable. What we mean by this is that the port must not set + the value of this variable absolutely, overriding the existing + value; instead, it may append whatever values it needs to the + existing value. This is so that build options that affect all + ports can be set globally. + + If it does not, please add + NO_PACKAGE=ignores cflags to the + Makefile. + + An example of a Makefile respecting + the CFLAGS variable follows. Note the + +=: + + CFLAGS+= -Wall -Werror + + Here is an example which does not respect the + CFLAGS variable: + + CFLAGS= -Wall -Werror + + The CFLAGS variable is defined on + &os; systems in /etc/make.conf. The first + example appends additional flags to the + CFLAGS variable, preserving any system-wide + definitions. The second example clobbers anything previously + defined. + + You should remove optimization flags from the third party + Makefiles. System + CFLAGS contains system-wide optimization + flags. An example from an unmodified + Makefile: + + CFLAGS= -O3 -funroll-loops -DHAVE_SOUND + + Using system optimization flags, the + Makefile would look similar to the + following example: + + CFLAGS+= -DHAVE_SOUND + + + + Threading Libraries + + The threading library must be linked to the binaries using + a special flag -pthread on &os;. If a port + insists on linking -lpthread directly, patch + it to use -pthread. + + + If building the port errors out with + unrecognized option '-pthread', it may be + desirable to use cc as linker by setting + CONFIGURE_ENV to + LD=${CC}. The -pthread + option is not supported by ld + directly. + + + + + Feedback + + Do send applicable changes/patches to the original + author/maintainer for inclusion in next release of the code. + This will only make your job that much easier for the next + release. + + + + <filename>README.html</filename> + + README.html is not part of the port, + but generated by make readme. Do not + include this file in patches or commits. + + + If make readme fails, make sure that + the default value of ECHO_MSG has not + been modified by the port. + + + + + Marking a Port Not Installable with + <varname>BROKEN</varname>, <varname>FORBIDDEN</varname>, or + <varname>IGNORE</varname> + + In certain cases users should be prevented from installing + a port. To tell a user that a port should not be installed, + there are several make variables that can be + used in a port's Makefile. The value of + the following make variables will be the + reason that is given back to users for why the port refuses to + install itself. Please use the correct make + variable as each make variable conveys radically different + meanings to both users, and to automated systems that depend on + the Makefiles, such as + the ports build cluster, + FreshPorts, and + portsmon. + + + Variables + + + + BROKEN is reserved for ports that + currently do not compile, install, or deinstall correctly. + It should be used for ports where the problem is believed + to be temporary. + + If instructed, the build cluster will still attempt + to try to build them to see if the underlying problem has + been resolved. (However, in general, the cluster is run + without this.) + + For instance, use BROKEN when a + port: + + + + does not compile + + + + fails its configuration or installation + process + + + + installs files outside of + ${LOCALBASE} + + + + does not remove all its files cleanly upon + deinstall (however, it may be acceptable, and + desirable, for the port to leave user-modified files + behind) + + + + + + FORBIDDEN is used for ports that + contain a security vulnerability or induce grave concern + regarding the security of a &os; system with a given port + installed (e.g., a reputably insecure program or a program + that provides easily exploitable services). Ports should + be marked as FORBIDDEN as soon as a + particular piece of software has a vulnerability and there + is no released upgrade. Ideally ports should be upgraded + as soon as possible when a security vulnerability is + discovered so as to reduce the number of vulnerable &os; + hosts (we like being known for being secure), however + sometimes there is a noticeable time gap between + disclosure of a vulnerability and an updated release of + the vulnerable software. Do not mark a port + FORBIDDEN for any reason other than + security. + + + + IGNORE is reserved for ports that + should not be built for some other reason. It should be + used for ports where the problem is believed to be + structural. The build cluster will not, under any + circumstances, build ports marked as + IGNORE. For instance, use + IGNORE when a port: + + + + compiles but does not run properly + + + + does not work on the installed version of + &os; + + + + has a distfile which may not be automatically + fetched due to licensing restrictions + + + + does not work with some other currently + installed port (for instance, the port depends on + www/apache20 but + www/apache22 is + installed) + + + + + If a port would conflict with a currently + installed port (for example, if they install a file in + the same place that performs a different function), + use + CONFLICTS instead. + CONFLICTS will set + IGNORE by itself. + + + + + If a port should be marked IGNORE + only on certain architectures, there are two other + convenience variables that will automatically set + IGNORE for you: + ONLY_FOR_ARCHS and + NOT_FOR_ARCHS. Examples: + + ONLY_FOR_ARCHS= i386 amd64 + + NOT_FOR_ARCHS= ia64 sparc64 + + A custom IGNORE message can be + set using ONLY_FOR_ARCHS_REASON and + NOT_FOR_ARCHS_REASON. Per + architecture entries are possible with + ONLY_FOR_ARCHS_REASON_ARCH + and + NOT_FOR_ARCHS_REASON_ARCH. + + + + If a port fetches i386 binaries and installs them, + IA32_BINARY_PORT should be set. If + this variable is set, it will be checked whether the + /usr/lib32 directory is available for + IA32 versions of libraries and whether the kernel has IA32 + compatibility compiled in. If one of these two + dependencies is not satisfied, IGNORE + will be set automatically. + + + + + + Implementation Notes + + The strings should not be quoted. Also, the wording of + the string should be somewhat different due to the way the + information is shown to the user. Examples: + + BROKEN= fails to link with base -lcrypto + + IGNORE= unsupported on recent versions + + resulting in the following output from + make describe: + + ===> foobar-0.1 is marked as broken: fails to link with base -lcrypto. + + ===> foobar-0.1 is unsupported on recent versions. + + + + + Marking a Port for Removal with + <varname>DEPRECATED</varname> or + <varname>EXPIRATION_DATE</varname> + + Do remember that BROKEN and + FORBIDDEN are to be used as a temporary + resort if a port is not working. Permanently broken ports + should be removed from the tree entirely. + + When it makes sense to do so, users can be warned about + a pending port removal with DEPRECATED and + EXPIRATION_DATE. The former is simply a + string stating why the port is scheduled for removal; the latter + is a string in ISO 8601 format (YYYY-MM-DD). Both will be shown + to the user. + + It is possible to set DEPRECATED + without an EXPIRATION_DATE (for instance, + recommending a newer version of the port), but the converse + does not make any sense. + + There is no set policy on how much notice to give. + Current practice seems to be one month for security-related + issues and two months for build issues. This also gives any + interested committers a little time to fix the problems. + + + + Avoid Use of the <literal>.error</literal> + Construct + + The correct way for a Makefile to + signal that the port can not be installed due to some external + factor (for instance, the user has specified an illegal + combination of build options) is to set a non-blank value to + IGNORE. This value will be formatted and + shown to the user by make install. + + It is a common mistake to use .error + for this purpose. The problem with this is that many automated + tools that work with the ports tree will fail in this situation. + The most common occurrence of this is seen when trying to build + /usr/ports/INDEX (see + ). However, even more trivial + commands such as make maintainer also fail in + this scenario. This is not acceptable. + + + How to Avoid Using <literal>.error</literal> + + The first of the + next two Makefile snippets will cause + make index to fail, while the second one + will not: + + .error "option is not supported" + + IGNORE=option is not supported + + + + + Usage of <filename>sysctl</filename> + + The usage of sysctl is discouraged + except in targets. This is because the evaluation of any + makevars, such as used during + make index, then has to run the command, + further slowing down that process. + + Usage of &man.sysctl.8; should always be done with the + SYSCTL variable, as it contains the fully + qualified path and can be overridden, if one has such a + special need. + + + + Rerolling Distfiles + + Sometimes the authors of software change the content of + released distfiles without changing the file's name. You have + to verify that the changes are official and have been performed + by the author. It has happened in the past that the distfile + was silently altered on the download servers with the intent to + cause harm or compromise end user security. + + Put the old distfile aside, download the new one, unpack + them and compare the content with &man.diff.1;. If you see + nothing suspicious, you can update + distinfo. Be sure to summarize the + differences in your PR or commit log, so that other people know + that you have taken care to ensure that nothing bad has + happened. + + You might also want to contact the authors of the software + and confirm the changes with them. + + + + Avoiding Linuxisms + + Do not use /proc if there are any + other ways of getting the information, e.g., + setprogname(argv[0]) in + main() and then &man.getprogname.3; if + you want to know your name. + + Do not rely on behaviour that is undocumented by + POSIX. + + Do not record timestamps in the critical path of the + application if it also works without. Getting timestamps may be + slow, depending on the accuracy of timestamps in the + OS. If timestamps are really needed, + determine how precise they have to be and use an + API which is documented to just deliver the + needed precision. + + A number of simple syscalls (for example + &man.gettimeofday.2;, &man.getpid.2;) are much faster on &linux; + than on any other operating system due to caching and the + vsyscall performance optimizations. Do not rely on them being + cheap in performance-critical applications. In general, try + hard to avoid syscalls if possible. + + Do not rely on &linux;-specific socket behaviour. In + particular, default socket buffer sizes are different (call + &man.setsockopt.2; with SO_SNDBUF and + SO_RCVBUF, and while &linux;'s &man.send.2; + blocks when the socket buffer is full, &os;'s will fail and + set ENOBUFS in errno. + + If relying on non-standard behaviour is required, + encapsulate it properly into a generic API, + do a check for the behaviour in the configure stage, and stop + if it is missing. + + Check the + man + pages to see if the function used is a + POSIX interface (in the + STANDARDS section of the man page). + + Do not assume that /bin/sh is + bash. Ensure that a command line + passed to &man.system.3; will work with a + POSIX compliant shell. + + A list of common bashisms is + available here. + + Check that headers are included in the + POSIX or man page recommended way, e.g., + sys/types.h is often forgotten, which is + not as much of a problem for &linux; as it is for &os;. + + Compile threaded applications with + -pthread, not -lpthread or + variations thereof. + + + + Miscellanea + + The files pkg-descr and + pkg-plist should each be double-checked. + If you are reviewing a port and feel they can be worded better, + do so. + + Do not copy more copies of the GNU General Public License + into our system, please. + + Please be careful to note any legal issues! Do not let us + illegally distribute software! + +