From 5259e3fddad2abba0ea535959f6413183049bc48 Mon Sep 17 00:00:00 2001 From: jmcneill Date: Sun, 27 Jul 2008 19:30:15 +0000 Subject: [PATCH] regen --- doc/pkgsrc.html | 123 +++++++++++++++++++++++++++++------------------- doc/pkgsrc.txt | 65 ++++++++++++++++--------- 2 files changed, 117 insertions(+), 71 deletions(-) diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html index 7b6dc9d18607..f181469e14f1 100644 --- a/doc/pkgsrc.html +++ b/doc/pkgsrc.html @@ -562,14 +562,14 @@ pkgsrc provides the following key features:

The following principles are basic to pkgsrc:

@@ -1281,8 +1281,8 @@ rdiff -u pkgsrc and other gcc-compiled binaries reliably, a hotfix containing POSIX.EXE, PSXDLL.DLL, PSXRUN.EXE, and PSXSS.EXE (899522 or newer) must be installed. Hotfixes are available from Microsoft through a - support contract; however, a NetBSD developer has made most Interix - hotfixes available for personal use from http://www.duh.org/interix/hotfixes.php.

+ support contract; however, Debian Interix Port has made most Interix + hotfixes available for personal use from http://www.debian-interix.net/hotfixes/.

In addition to the hotfix noted above, it may be necessary to disable Data Execution Prevention entirely to make Interix functional. This may happen only with certain types of CPUs; the cause is not fully @@ -1751,9 +1751,9 @@ and you can still use binary packages from someone else.

other packages depend on it. Instead, they are moved to the vulnerable subdirectory. So you may need to add this directory to the PKG_PATH variable. - However, you should run security/audit-packages regularly, especially - after installing new packages, and verify that the vulnerabilities - are acceptable for your configuration.

+ However, you should run audit-packages + regularly, especially after installing new packages, and verify + that the vulnerabilities are acceptable for your configuration.

After you've installed packages, be sure to have /usr/pkg/bin and /usr/pkg/sbin in your PATH so you can actually start the just @@ -2177,7 +2177,7 @@ works.

can be NFS-mounted while ${WRKOBJDIR} is local to every architecture. (It should be noted that PKGSRCDIR should not be set by the user - — it is an internal definition which refers to the + — it is an internal definition which refers to the root of the pkgsrc tree. It is possible to have many pkgsrc tree instances.)

  • LOCALPATCHES: @@ -2798,7 +2798,7 @@ fi

  • /usr/src (system sources, - e. g. for sysutils/aperture):

    + e. g. for sysutils/aperture):

    # ln -s ../disk1/cvs .
 	  # ln -s cvs/src-2.0 src
    • @@ -2944,8 +2944,7 @@ nbftp% chmod 755 .

    7.4.1. Configuration

    -

    TODO; see the wiki for -more information.

    +

    TODO; see pkgsrc/doc/HOWTO-pbulk for more information.

    @@ -3483,8 +3482,8 @@ attackers. In an effort to lessen the exposure, the NetBSD packages team maintains a database of known-exploits to packages which have at one time been included in pkgsrc. The database can be downloaded automatically, and a security audit of all packages installed on a system can take place. To -do this, install the security/audit-packages package. It has two -components:

    +do this, refer to the following two tools (installed as part of the +pkgtools/pkg_install package):

    1. download-vulnerability-list, an easy way to @@ -3499,11 +3498,10 @@ components:

      including a description of the type of vulnerability, and a URL containing more information.

    -

    Use of the security/audit-packages -package is strongly recommended! After -“audit-packages” is installed, please read +

    Use of these tools is strongly recommended! After +“pkg_install” is installed, please read the package's message, which you can get by running pkg_info -D -audit-packages.

    +pkg_install.

    If this package is installed, pkgsrc builds will use it to perform a security check before building any package. See Section 5.2, “Variables affecting the build process” for ways to control this check.

    @@ -4241,15 +4239,22 @@ converters games mbone print x11

    The third section contains the following variables.

      -

    • MAINTAINER is the email address - of the person who feels responsible for this package, and who is - most likely to look at problems or questions regarding this - package which have been reported with send-pr(1). Other - developers should contact the MAINTAINER before - making major changes to the package. When packaging a new program, - set MAINTAINER to yourself. If you really can't - maintain the package for future updates, set it to +

    • MAINTAINER is the email + address of the person who feels responsible for this package, + and who is most likely to look at problems or questions regarding + this package which have been reported with send-pr(1). + Other developers may contact the MAINTAINER + before making changes to the package, but are not required to + do so. When packaging a new program, set MAINTAINER + to yourself. If you really can't maintain the package for future + updates, set it to .

      • +

    • OWNER should be used instead + of MAINTAINER when you do not want other + developers to update or change the package without contacting + you first. A package Makefile should contain one of + MAINTAINER or OWNER, but + not both.

    • HOMEPAGE is a URL where users can find more information about the package.

    • COMMENT is a one-line @@ -4437,7 +4442,7 @@ PATCHDIR= ${.CURDIR}/../xemacs/patches specific features you need. For example, instead of assuming that kqueue is available under NetBSD and using the __NetBSD__ macro to conditionalize - kqueue support, add a check that detects kqueue itself — + kqueue support, add a check that detects kqueue itself — yes, this generally involves patching the configure script. There is absolutely nothing that prevents some OSes from adopting interfaces from other OSes @@ -4808,7 +4813,7 @@ correct: operate on the words, others operate on the string as a whole. When a string is split into words, it is split as you would expect it from sh(1).

      -

      No rule without exception—the .for +

      No rule without exception—the .for loop does not follow the shell quoting rules but splits at sequences of whitespace.

      There are several types of variables that should be handled @@ -6517,7 +6522,7 @@ GTKDIR_DEFAULT= ${LOCALBASE}

      17.3. Directories used during the build process

      -

      When building a package, a number of directories is used to store +

      When building a package, various directories are used to store source files, temporary files, pkgsrc-internal files, and so on. These directories are explained here.

      Some of the directory variables contain relative pathnames. There @@ -6550,6 +6555,14 @@ GTKDIR_DEFAULT= ${LOCALBASE} that isn't hidden. This variable may be changed by a package Makefile.

      +

      The CREATE_WRKDIR_SYMLINK definition takes either + the value yes or no and defaults + to yes. It indicates whether a symbolic link to the + WRKDIR is to be created in the pkgsrc entry's directory. + If users would like to have their pkgsrc trees behave in a + read-only manner, then the value of + CREATE_WRKDIR_SYMLINK should be set to + no.

    @@ -6728,11 +6741,11 @@ ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS} mk/extract/extract.

    EXTRACT_USING

    This variable can be set to - gtar, nbtar (which is the - default value), pax, or an + bsdtar, gtar, nbtar + (which is the default value), pax, or an absolute pathname pointing to the command with which tar - archives should be - extracted.

    + archives should be extracted. It is preferred to choose bsdtar over gtar + if NetBSD's pax-as-tar is not good enough.

    If the extract program doesn't serve your needs, you can also override the @@ -7473,7 +7486,7 @@ TOOLS_PLATFORM.true?= true # shell builtin -

    18.4.1.

    +

    18.4.1.

    How do I add a new tool?

    @@ -7483,7 +7496,7 @@ TOOLS_PLATFORM.true?= true # shell builtin -

    18.4.2.

    +

    18.4.2.

    How do I get a list of all available tools?

    @@ -7494,7 +7507,7 @@ TOOLS_PLATFORM.true?= true # shell builtin -

    18.4.3.

    +

    18.4.3.

    How can I get a list of all the tools that a package is using while being built? I want to know whether it @@ -8059,7 +8072,8 @@ DISTNAME= foo-17.43 changes that do not merit increasing PKGREVISION are:

      -

    • Changing HOMEPAGE, MAINTAINER, +

    • Changing HOMEPAGE, + MAINTAINER, OWNER, or comments in Makefile.

    • Changing build variables if the resulting binary package is the same.

      • @@ -8733,7 +8747,7 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2

      Note that per default, setgid installation of games is disabled; setting SETGIDGAME=YES will set all the other variables accordingly.

      -

      A package should therefor never hard code file ownership or +

      A package should therefore never hard code file ownership or access permissions but rely on INSTALL_GAME and INSTALL_GAME_DATA to set these correctly.

      @@ -8741,7 +8755,18 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2

      19.6.4. Adding DESTDIR support to packages

      +

      DESTDIR support means that a package + installs into a staging directory, not the final location of the + files. Then a binary package is created which can be used for + installation as usual. There are two ways: Either the package must + install as root (“destdir”) or the package can + install as non-root user (“user-destdir”).

        +

      • PKG_DESTDIR_SUPPORT has to be + set to “destdir” or “user-destdir”. If + bsd.prefs.mk is included in the Makefile, + PKG_DESTDIR_SUPPORT needs to be set before + the inclusion.

      • All installation operations have to be prefixed with ${DESTDIR}.

      • automake gets this DESTDIR mostly right @@ -9496,7 +9521,7 @@ do? -

        22.1.

        +

        22.1.

        What is the difference between MAKEFLAGS, .MAKEFLAGS and @@ -9512,7 +9537,7 @@ do? -

        22.2.

        +

        22.2.

        What is the difference between MAKE, GMAKE and @@ -9530,7 +9555,7 @@ do? -

        22.3.

        +

        22.3.

        What is the difference between CC, PKG_CC and @@ -9548,7 +9573,7 @@ do? -

        22.4.

        +

        22.4.

        What is the difference between BUILDLINK_LDFLAGS, @@ -9561,7 +9586,7 @@ do? -

        22.5.

        +

        22.5.

        Why does make show-var VARNAME=BUILDLINK_PREFIX.foo @@ -9577,7 +9602,7 @@ do? -

        22.6.

        +

        22.6.

        What does ${MASTER_SITE_SOURCEFORGE:=package/} mean? I @@ -9601,7 +9626,7 @@ do? -

        22.7.

        +

        22.7.

        Which mailing lists are there for package developers?

        @@ -9626,7 +9651,7 @@ do? -

        22.8.

        +

        22.8.

        Where is the pkgsrc documentation?

        @@ -9674,7 +9699,7 @@ do? -

        22.9.

        +

        22.9.

        I have a little time to kill. What shall I do?

        @@ -9690,7 +9715,7 @@ anyway.

        will tell you about newer versions of installed packages that are available, but not yet updated in pkgsrc.

      • Browse pkgsrc/doc/TODO - — it contains a list of suggested new packages and a list of + — it contains a list of suggested new packages and a list of cleanups and enhancements for pkgsrc that would be nice to have.

      • Review packages for which review was requested on @@ -10208,8 +10233,8 @@ CFLAGS+= -Wall 24.5.1. Procedures with parameters

    In a traditional imperative programming language some of the .mk files could be described as - procedures. They take some input parameters and—after - inclusion—provide a result in output parameters. Since all + procedures. They take some input parameters and—after + inclusion—provide a result in output parameters. Since all variables in Makefiles have global scope care must be taken not to use parameter names that have already another meaning. For example, PKGNAME is a diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt index e8c7e08ac449..78f47b6576e8 100644 --- a/doc/pkgsrc.txt +++ b/doc/pkgsrc.txt @@ -1168,9 +1168,9 @@ NOTE: Newer Windows service packs change the way binary execution works (via the Data Execution Prevention feature). In order to use pkgsrc and other gcc-compiled binaries reliably, a hotfix containing POSIX.EXE, PSXDLL.DLL, PSXRUN.EXE, and PSXSS.EXE (899522 or newer) must be installed. Hotfixes are -available from Microsoft through a support contract; however, a NetBSD -developer has made most Interix hotfixes available for personal use from http:/ -/www.duh.org/interix/hotfixes.php. +available from Microsoft through a support contract; however, Debian Interix +Port has made most Interix hotfixes available for personal use from http:// +www.debian-interix.net/hotfixes/. In addition to the hotfix noted above, it may be necessary to disable Data Execution Prevention entirely to make Interix functional. This may happen only @@ -1594,9 +1594,9 @@ As mentioned above, packages for which vulnerabilities get known are not stored in the All subdirectory. They don't get deleted since that could be very frustrating if many other packages depend on it. Instead, they are moved to the vulnerable subdirectory. So you may need to add this directory to the PKG_PATH -variable. However, you should run security/audit-packages regularly, especially -after installing new packages, and verify that the vulnerabilities are -acceptable for your configuration. +variable. However, you should run audit-packages regularly, especially after +installing new packages, and verify that the vulnerabilities are acceptable for +your configuration. After you've installed packages, be sure to have /usr/pkg/bin and /usr/pkg/sbin in your PATH so you can actually start the just installed program. @@ -2576,7 +2576,7 @@ nbftp% chmod 755 . 7.4.1. Configuration -TODO; see the wiki for more information. +TODO; see pkgsrc/doc/HOWTO-pbulk for more information. 7.5. Creating a multiple CD-ROM packages collection @@ -3057,8 +3057,8 @@ of these bugs can leave a machine vulnerable to exploitation by attackers. In an effort to lessen the exposure, the NetBSD packages team maintains a database of known-exploits to packages which have at one time been included in pkgsrc. The database can be downloaded automatically, and a security audit of all -packages installed on a system can take place. To do this, install the security -/audit-packages package. It has two components: +packages installed on a system can take place. To do this, refer to the +following two tools (installed as part of the pkgtools/pkg_install package): 1. download-vulnerability-list, an easy way to download a list of the security vulnerabilities information. This list is kept up to date by the NetBSD @@ -3072,9 +3072,9 @@ packages installed on a system can take place. To do this, install the security be shown by output to stdout, including a description of the type of vulnerability, and a URL containing more information. -Use of the security/audit-packages package is strongly recommended! After -"audit-packages" is installed, please read the package's message, which you can -get by running pkg_info -D audit-packages. +Use of these tools is strongly recommended! After "pkg_install" is installed, +please read the package's message, which you can get by running pkg_info -D +pkg_install. If this package is installed, pkgsrc builds will use it to perform a security check before building any package. See Section 5.2, "Variables affecting the @@ -3736,10 +3736,14 @@ The third section contains the following variables. * MAINTAINER is the email address of the person who feels responsible for this package, and who is most likely to look at problems or questions regarding this package which have been reported with send-pr(1). Other - developers should contact the MAINTAINER before making major changes to the - package. When packaging a new program, set MAINTAINER to yourself. If you - really can't maintain the package for future updates, set it to < - pkgsrc-users@NetBSD.org>. + developers may contact the MAINTAINER before making changes to the package, + but are not required to do so. When packaging a new program, set MAINTAINER + to yourself. If you really can't maintain the package for future updates, + set it to . + + * OWNER should be used instead of MAINTAINER when you do not want other + developers to update or change the package without contacting you first. A + package Makefile should contain one of MAINTAINER or OWNER, but not both. * HOMEPAGE is a URL where users can find more information about the package. @@ -5554,7 +5558,7 @@ When choosing which of these variables to use, follow the following rules: 17.3. Directories used during the build process -When building a package, a number of directories is used to store source files, +When building a package, various directories are used to store source files, temporary files, pkgsrc-internal files, and so on. These directories are explained here. @@ -5591,6 +5595,12 @@ WRKSRC it's the only directory entry that isn't hidden. This variable may be changed by a package Makefile. +The CREATE_WRKDIR_SYMLINK definition takes either the value yes or no and +defaults to yes. It indicates whether a symbolic link to the WRKDIR is to be +created in the pkgsrc entry's directory. If users would like to have their +pkgsrc trees behave in a read-only manner, then the value of +CREATE_WRKDIR_SYMLINK should be set to no. + 17.4. Running a phase You can run a particular phase by typing make phase, where phase is the name of @@ -5732,9 +5742,10 @@ EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO} EXTRACT_USING - This variable can be set to gtar, nbtar (which is the default value), pax, - or an absolute pathname pointing to the command with which tar archives - should be extracted. + This variable can be set to bsdtar, gtar, nbtar (which is the default + value), pax, or an absolute pathname pointing to the command with which tar + archives should be extracted. It is preferred to choose bsdtar over gtar if + NetBSD's pax-as-tar is not good enough. If the extract program doesn't serve your needs, you can also override the EXTRACT_CMD variable, which holds the command used for extracting the files. @@ -6817,7 +6828,7 @@ trivial that no reasonable person would want to upgrade", and this is the rough test for when increasing PKGREVISION is appropriate. Examples of changes that do not merit increasing PKGREVISION are: - * Changing HOMEPAGE, MAINTAINER, or comments in Makefile. + * Changing HOMEPAGE, MAINTAINER, OWNER, or comments in Makefile. * Changing build variables if the resulting binary package is the same. @@ -7335,11 +7346,21 @@ this behaviour: SETGIDGAME, GAMEDATAMODE, GAMEGRP, GAMEMODE, GAMEOWN. Note that per default, setgid installation of games is disabled; setting SETGIDGAME=YES will set all the other variables accordingly. -A package should therefor never hard code file ownership or access permissions +A package should therefore never hard code file ownership or access permissions but rely on INSTALL_GAME and INSTALL_GAME_DATA to set these correctly. 19.6.4. Adding DESTDIR support to packages +DESTDIR support means that a package installs into a staging directory, not the +final location of the files. Then a binary package is created which can be used +for installation as usual. There are two ways: Either the package must install +as root ("destdir") or the package can install as non-root user +("user-destdir"). + + * PKG_DESTDIR_SUPPORT has to be set to "destdir" or "user-destdir". If + bsd.prefs.mk is included in the Makefile, PKG_DESTDIR_SUPPORT needs to be + set before the inclusion. + * All installation operations have to be prefixed with ${DESTDIR}. * automake gets this DESTDIR mostly right automatically. Many manual rules