From owner-svn-doc-head@FreeBSD.ORG Sun Feb 16 03:32:26 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 AA33CD10; Sun, 16 Feb 2014 03:32:26 +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 9428B17A9; Sun, 16 Feb 2014 03:32:26 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1G3WQ9G079423; Sun, 16 Feb 2014 03:32:26 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1G3WQ9I079422; Sun, 16 Feb 2014 03:32:26 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201402160332.s1G3WQ9I079422@svn.freebsd.org> From: Warren Block Date: Sun, 16 Feb 2014 03:32:26 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43957 - head/en_US.ISO8859-1/books/porters-handbook/testing 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, 16 Feb 2014 03:32:26 -0000 Author: wblock Date: Sun Feb 16 03:32:26 2014 New Revision: 43957 URL: http://svnweb.freebsd.org/changeset/doc/43957 Log: Whitespace-only fixes, translators please ignore. Modified: head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml Sun Feb 16 03:25:22 2014 (r43956) +++ head/en_US.ISO8859-1/books/porters-handbook/testing/chapter.xml Sun Feb 16 03:32:26 2014 (r43957) @@ -4,198 +4,192 @@ $FreeBSD$ --> - - - Testing the Port - - - Running <command>make describe</command> - - Several of the &os; port maintenance tools, such as - &man.portupgrade.1;, rely on a database called - /usr/ports/INDEX which keeps track of - such items as port dependencies. INDEX - is created by the top-level - ports/Makefile via - make index, which descends into each port - subdirectory and executes make describe - there. Thus, if make describe fails in any - port, no one can generate INDEX, and many - people will quickly become unhappy. - - - It is important to be able to generate this file no - matter what options are present in - make.conf, so please avoid doing things - such as using .error statements when (for - instance) a dependency is not satisfied. (See - .) - - - If make describe produces a string - rather than an error message, you are probably safe. See - bsd.port.mk for the meaning of the - string produced. - - Also note that running a recent version of - portlint (as specified in the next section) - will cause make describe to be run - automatically. - - - - Portlint - - Do check your work with portlint - before you submit or commit it. portlint - warns you about many common errors, both functional and - stylistic. For a new (or repocopied) port, - portlint -A is the most thorough; for an - existing port, portlint -C is - sufficient. - - Since portlint uses heuristics to - try to figure out errors, it can produce false positive - warnings. In addition, occasionally something that is - flagged as a problem really cannot be done in any other - way due to limitations in the ports framework. When in - doubt, the best thing to do is ask on &a.ports;. - - - - Port Tools - - The - ports-mgmt/porttools - program is part of the Ports Collection. - - port is the front-end script, which can - help you simplify the testing job. Whenever you want to test - a new port or update an existing one, you can use - port test to test your port, including the - portlint - checking. This command also detects and lists any files that - are not listed in pkg-plist. See the - following example: - - &prompt.root; port test /usr/ports/net/csup - - - - <varname>PREFIX</varname> and - <varname>DESTDIR</varname> - - PREFIX determines where the port will - be installed. It defaults to /usr/local, - but can be set by the user to a custom path like - /opt. Your port must respect the value - of this variable. - - DESTDIR, if set by the user, determines - the complete alternative environment, usually a jail or an - installed system mounted somewhere other than - /. A port will actually install into - DESTDIR/PREFIX, - and register with the package database in - DESTDIR/var/db/pkg. - As DESTDIR is handled automatically by the - ports infrastructure with &man.chroot.8;, you do not need any - modifications or any extra care to write - DESTDIR-compliant ports. - - The value of PREFIX will be set to - LOCALBASE (defaulting to - /usr/local). If - USE_LINUX_PREFIX is set, - PREFIX will be LINUXBASE - (defaulting to /compat/linux). - - Avoiding hard-coded /usr/local paths - in the source makes the port much more flexible and able to - cater to the needs of other sites. Often, this can be - accomplished by simply replacing occurrences of - /usr/local in the port's various - Makefiles with - ${PREFIX}. This variable is - automatically passed down to every stage of the build and - install processes. - - Make sure your application is not installing things in - /usr/local instead of - PREFIX. A quick test for such hard-coded - paths is: - - &prompt.root; make clean; make package PREFIX=/var/tmp/`make -V PORTNAME` - - If anything is installed outside of - PREFIX, the package creation process will - complain that it cannot find the files. - - In addition, it is worth checking the same with the - stage directory support (see - ): - - &prompt.root; make stage && make check-orphans && make package - - These tests will not find hard-coded paths inside the - port's files, nor will it verify that - LOCALBASE is being used to correctly refer - to files from other ports. The temporarily-installed port in - /var/tmp/`make -V PORTNAME` should be - tested for proper operation to make sure there - are no problems with paths. - - PREFIX should not be set explicitly - in a port's Makefile. Users installing - the port may have set PREFIX to a custom - location, and the port should respect that setting. - - Refer to programs and files from other ports with the - variables mentioned above, not explicit pathnames. For - instance, if your port requires a macro - PAGER to have the full pathname of - less, do not use a literal path of - /usr/local/bin/less. Instead, use - ${LOCALBASE}: - - -DPAGER=\"${LOCALBASE}/bin/less\" - - The path with LOCALBASE is more likely - to still work if the system administrator has moved the whole - /usr/local tree somewhere else. - - - - Tinderbox - - If you are an avid ports contributor, you might want to - take a look at Tinderbox. It is a - powerful system for building and testing ports. - You can - install Tinderbox using - ports-mgmt/tinderbox port. - Be sure to read supplied documentation since the configuration - is not trivial. - - Visit the - Tinderbox - website for more details. - - - - Poudriere - - As a ports contributor, consider installing - poudriere. It is a powerful - system for building and testing ports. - Poudriere can be installed with - ports-mgmt/poudriere. - - Visit the Poudriere - website for more details. - - - + + + Testing the Port + + + Running <command>make describe</command> + + Several of the &os; port maintenance tools, such as + &man.portupgrade.1;, rely on a database called + /usr/ports/INDEX which keeps track of such + items as port dependencies. INDEX is + created by the top-level ports/Makefile via + make index, which descends into each port + subdirectory and executes make describe + there. Thus, if make describe fails in any + port, no one can generate INDEX, and many + people will quickly become unhappy. + + + It is important to be able to generate this file no matter + what options are present in make.conf, so + please avoid doing things such as using + .error statements when (for instance) a + dependency is not satisfied. (See + .) + + + If make describe produces a string rather + than an error message, you are probably safe. See + bsd.port.mk for the meaning of the string + produced. + + Also note that running a recent version of + portlint (as specified in the next section) + will cause make describe to be run + automatically. + + + + Portlint + + Do check your work with portlint + before you submit or commit it. portlint + warns you about many common errors, both functional and + stylistic. For a new (or repocopied) port, + portlint -A is the most thorough; for an + existing port, portlint -C is + sufficient. + + Since portlint uses heuristics to try to + figure out errors, it can produce false positive warnings. In + addition, occasionally something that is flagged as a problem + really cannot be done in any other way due to limitations in the + ports framework. When in doubt, the best thing to do is ask on + &a.ports;. + + + + Port Tools + + The ports-mgmt/porttools + program is part of the Ports Collection. + + port is the front-end script, which can + help you simplify the testing job. Whenever you want to test a + new port or update an existing one, you can use + port test to test your port, including the + portlint + checking. This command also detects and lists any files that + are not listed in pkg-plist. See the + following example: + + &prompt.root; port test /usr/ports/net/csup + + + + <varname>PREFIX</varname> and + <varname>DESTDIR</varname> + + PREFIX determines where the port will be + installed. It defaults to /usr/local, but + can be set by the user to a custom path like + /opt. Your port must respect the value of + this variable. + + DESTDIR, if set by the user, determines + the complete alternative environment, usually a jail or an + installed system mounted somewhere other than + /. A port will actually install into + DESTDIR/PREFIX, and register with the + package database in DESTDIR/var/db/pkg. As + DESTDIR is handled automatically by the ports + infrastructure with &man.chroot.8;, you do not need any + modifications or any extra care to write + DESTDIR-compliant ports. + + The value of PREFIX will be set to + LOCALBASE (defaulting to + /usr/local). If + USE_LINUX_PREFIX is set, + PREFIX will be LINUXBASE + (defaulting to /compat/linux). + + Avoiding hard-coded /usr/local paths in + the source makes the port much more flexible and able to cater + to the needs of other sites. Often, this can be accomplished by + simply replacing occurrences of /usr/local + in the port's various Makefiles with + ${PREFIX}. This variable is + automatically passed down to every stage of the build and + install processes. + + Make sure your application is not installing things in + /usr/local instead of + PREFIX. A quick test for such hard-coded + paths is: + + &prompt.root; make clean; make package PREFIX=/var/tmp/`make -V PORTNAME` + + If anything is installed outside of + PREFIX, the package creation process will + complain that it cannot find the files. + + In addition, it is worth checking the same with the stage + directory support (see ): + + &prompt.root; make stage && make check-orphans && make package + + These tests will not find hard-coded paths inside the port's + files, nor will it verify that LOCALBASE is + being used to correctly refer to files from other ports. The + temporarily-installed port in + /var/tmp/`make -V PORTNAME` should be + tested for proper operation to make sure there are no problems + with paths. + + PREFIX should not be set explicitly in a + port's Makefile. Users installing the port + may have set PREFIX to a custom location, and + the port should respect that setting. + + Refer to programs and files from other ports with the + variables mentioned above, not explicit pathnames. For + instance, if your port requires a macro PAGER + to have the full pathname of less, do not use + a literal path of /usr/local/bin/less. + Instead, use ${LOCALBASE}: + + -DPAGER=\"${LOCALBASE}/bin/less\" + + The path with LOCALBASE is more likely to + still work if the system administrator has moved the whole + /usr/local tree somewhere else. + + + + Tinderbox + + If you are an avid ports contributor, you might want to take + a look at Tinderbox. It is a + powerful system for building and testing ports. You can install + Tinderbox using + ports-mgmt/tinderbox port. Be + sure to read supplied documentation since the configuration is + not trivial. + + Visit the + Tinderbox + website for more details. + + + + Poudriere + + As a ports contributor, consider installing + poudriere. It is a powerful + system for building and testing ports. + Poudriere can be installed with + ports-mgmt/poudriere. + + Visit the Poudriere + website for more details. + +