From owner-svn-doc-head@FreeBSD.ORG Sun Feb 9 23:16:49 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id E38CDF82; Sun, 9 Feb 2014 23:16:49 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id CA95B124F; Sun, 9 Feb 2014 23:16:49 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s19NGnsQ084646; Sun, 9 Feb 2014 23:16:49 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s19NGnNx084645; Sun, 9 Feb 2014 23:16:49 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201402092316.s19NGnNx084645@svn.freebsd.org> From: Warren Block Date: Sun, 9 Feb 2014 23:16:49 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43852 - head/en_US.ISO8859-1/books/porters-handbook/porting-dads X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 09 Feb 2014 23:16:50 -0000 Author: wblock Date: Sun Feb 9 23:16:49 2014 New Revision: 43852 URL: http://svnweb.freebsd.org/changeset/doc/43852 Log: Whitespace-only fixes, translators please ignore. Modified: head/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml Sun Feb 9 08:19:54 2014 (r43851) +++ head/en_US.ISO8859-1/books/porters-handbook/porting-dads/chapter.xml Sun Feb 9 23:16:49 2014 (r43852) @@ -5,720 +5,715 @@ $FreeBSD$ --> - + + + Dos and Don'ts + + + 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. + + + + <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. + + + + <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. + + Also, if you are defining WRKDIR + yourself, make sure you prepend + ${WRKDIRPREFIX}${.CURDIR} in + the front. + + + + 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, + + #include <sys/param.h> + + 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. - Dos and Don'ts - - - 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. - - - - <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. - - - - <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. - - Also, if you are defining WRKDIR - yourself, make sure you prepend - ${WRKDIRPREFIX}${.CURDIR} in - the front. - - - - 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, - - #include <sys/param.h> - - 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. - - #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> - - 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. - - - 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). - - - - - - Variable - Description - - - - - - ARCH - The architecture as returned by uname - -m (e.g., i386) - - - - 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) - - - - OSVERSION - The numeric version of the operating system; the - same as __FreeBSD_version. - - - - LOCALBASE - The base of the local tree (e.g., - /usr/local) - - - - 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. - + + 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. + + + Include either the + bsd.port.pre.mk/bsd.port.post.mk + pair or bsd.port.mk only; do not mix + these two usages. + + + bsd.port.pre.mk only defines a few + variables, which can be used in tests in the + Makefile, + bsd.port.post.mk defines the rest. + + Here are some important variables defined in + bsd.port.pre.mk (this is not the complete + list, please read bsd.port.mk for the + complete list). + + + + + + Variable + Description + + + + + + ARCH + The architecture as returned by uname + -m (e.g., i386) + + + + 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) + + + + OSVERSION + The numeric version of the operating system; the + same as __FreeBSD_version. + + + + LOCALBASE + The base of the local tree (e.g., + /usr/local) + + + + 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. + - 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 - :-). - - - - 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: + You did remember to use tab instead of spaces after + BROKEN= and + :-). + + + + 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: - #!/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 + *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***