diff options
author | rillig <rillig@pkgsrc.org> | 2005-11-03 20:46:21 +0000 |
---|---|---|
committer | rillig <rillig@pkgsrc.org> | 2005-11-03 20:46:21 +0000 |
commit | 898b4b55faa8d56f174f2e69d8ddd3cbd713577a (patch) | |
tree | 69e75666bbecb99246959ff07b09148054512b8b /doc/pkgsrc.txt | |
parent | 3c1d64edcd01cb7156141bbd91c18757f7bf706e (diff) | |
download | pkgsrc-898b4b55faa8d56f174f2e69d8ddd3cbd713577a.tar.gz |
regen.
Diffstat (limited to 'doc/pkgsrc.txt')
-rw-r--r-- | doc/pkgsrc.txt | 365 |
1 files changed, 234 insertions, 131 deletions
diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt index 6da7d985a3e..e4db8ad15fb 100644 --- a/doc/pkgsrc.txt +++ b/doc/pkgsrc.txt @@ -195,9 +195,22 @@ II. The pkgsrc developer's guide 14. The build process - 14.1. Program location - 14.2. Main targets - 14.3. Other helpful targets + 14.1. Introduction + 14.2. Program location + 14.3. Directories used during the build process + 14.4. Running a phase + 14.5. The fetch phase + 14.6. The checksum phase + 14.7. The extract phase + 14.8. The patch phase + 14.9. The tools phase + 14.10. The wrapper phase + 14.11. The configure phase + 14.12. The build phase + 14.13. The test phase + 14.14. The install phase + 14.15. The package phase + 14.16. Other helpful targets 15. Making your package work @@ -1437,7 +1450,7 @@ a binary package. 6.2. Settings for creation of binary packages -See Section 14.3, "Other helpful targets". +See Section 14.16, "Other helpful targets". 6.3. Doing a bulk build of all packages @@ -2188,9 +2201,22 @@ Table of Contents 14. The build process - 14.1. Program location - 14.2. Main targets - 14.3. Other helpful targets + 14.1. Introduction + 14.2. Program location + 14.3. Directories used during the build process + 14.4. Running a phase + 14.5. The fetch phase + 14.6. The checksum phase + 14.7. The extract phase + 14.8. The patch phase + 14.9. The tools phase + 14.10. The wrapper phase + 14.11. The configure phase + 14.12. The build phase + 14.13. The test phase + 14.14. The install phase + 14.15. The package phase + 14.16. Other helpful targets 15. Making your package work @@ -2819,7 +2845,7 @@ Be sure to add a RCS ID line as the first thing in any PLIST file you write: 10.2. Semi-automatic PLIST generation You can use the make print-PLIST command to output a PLIST that matches any new -files since the package was extracted. See Section 14.3, "Other helpful +files since the package was extracted. See Section 14.16, "Other helpful targets" for more information on this target. 10.3. Tweaking output of make print-PLIST @@ -3776,9 +3802,31 @@ Chapter 14. The build process Table of Contents -14.1. Program location -14.2. Main targets -14.3. Other helpful targets +14.1. Introduction +14.2. Program location +14.3. Directories used during the build process +14.4. Running a phase +14.5. The fetch phase +14.6. The checksum phase +14.7. The extract phase +14.8. The patch phase +14.9. The tools phase +14.10. The wrapper phase +14.11. The configure phase +14.12. The build phase +14.13. The test phase +14.14. The install phase +14.15. The package phase +14.16. Other helpful targets + +14.1. Introduction + +This chapter gives a detailed description on how a package is built. Building a +package is separated into different phases (for example fetch, build, install), +all of which are described in the following sections. Each phase is splitted +into so-called stages, which take the name of the containing stage, prefixed by +one of pre-, do- or post-. (Examples are pre-configure, post-build.) Most of +the actual work is done in the do-* stages. The basic steps for building a program are always the same. First the program's source (distfile) must be brought to the local system and then extracted. After @@ -3788,7 +3836,7 @@ binaries, etc. can be put into place on the system. These are exactly the steps performed by the NetBSD package system, which is implemented as a series of targets in a central Makefile, pkgsrc/mk/bsd.pkg.mk. -14.1. Program location +14.2. Program location Before outlining the process performed by the NetBSD package system in the next section, here's a brief discussion on where programs are installed, and which @@ -3863,126 +3911,180 @@ When choosing which of these variables to use, follow the following rules: the exception that manual pages go into ${PREFIX}/man, not ${PREFIX}/share/ man. -14.2. Main targets +14.3. Directories used during the build process -The main targets used during the build process defined in bsd.pkg.mk are: - -fetch - - This will check if the file(s) given in the variables DISTFILES and - PATCHFILES (as defined in the package's Makefile) are present on the local - system in /usr/pkgsrc/distfiles. If they are not present, an attempt will - be made to fetch them using commands of the form: - - ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS} - - where ${site} varies through several possibilities in turn: first, - MASTER_SITE_OVERRIDE is tried, then the sites specified in either - SITES_file if defined, else MASTER_SITES or PATCH_SITES, as applies, then - finally the value of MASTER_SITE_BACKUP. The order of all except the first - can be optionally sorted by the user, via setting either MASTER_SORT_AWK or - MASTER_SORT_REGEX. - -checksum - - After the distfile(s) are fetched, their checksum is generated and compared - with the checksums stored in the distinfo file. If the checksums don't - match, the build is aborted. This is to ensure the same distfile is used - for building, and that the distfile wasn't changed, e.g. by some malign - force, deliberately changed distfiles on the master distribution site or - network lossage. - -extract - - When the distfiles are present on the local system, they need to be - extracted, as they are usually in the form of some compressed archive - format, most commonly .tar.gz. - - If only some of the distfiles need to be uncompressed, the files to be - uncompressed should be put into EXTRACT_ONLY. - - If the distfiles are not in .tar.gz format, they can be extracted by - setting either EXTRACT_SUFX, or EXTRACT_CMD, EXTRACT_BEFORE_ARGS and - EXTRACT_AFTER_ARGS. In the former case, pkgsrc knows how to extract a - number of suffixes (.tar.gz, .tgz, .tar.gz2, .tbz, .tar.Z, .tar, .shar.gz, - .shar.bz2, .shar.Z, .shar, .Z, .bz2 and .gz; see the definition of the - various DECOMPRESS_CMD variables in bsd.pkg.extract.mk for a complete - list). Here's an example on how to use the other variables for a program - that comes with a compressed shell archive whose name ends in .msg.gz: - - EXTRACT_SUFX= .msg.gz - EXTRACT_CMD= zcat - EXTRACT_BEFORE_ARGS= - EXTRACT_AFTER_ARGS= |sh - -patch - - After extraction, all the patches named by the PATCHFILES, those present in - the patches subdirectory of the package as well as in $LOCALPATCHES/ - $PKGPATH (e.g. /usr/local/patches/graphics/png) are applied. Patchfiles - ending in .Z or .gz are uncompressed before they are applied, files ending - in .orig or .rej are ignored. Any special options to patch(1) can be handed - in PATCH_DIST_ARGS. See Section 8.3, "patches/*" for more details. - - By default patch(1) is given special args to make it fail if the patches - apply with some lines of fuzz. Please fix (regen) the patches so that they - apply cleanly. The rationale behind this is that patches that don't apply - cleanly may end up being applied in the wrong place, and cause severe harm - there. - -configure - - Most pieces of software need information on the header files, system calls, - and library routines which are available in NetBSD. This is the process - known as configuration, and is usually automated. In most cases, a script - is supplied with the source, and its invocation results in generation of - header files, Makefiles, etc. - - If the program's distfile contains its own configure script, this can be - invoked by setting HAS_CONFIGURE. If the configure script is a GNU autoconf - script, GNU_CONFIGURE should be specified instead. In either case, any - arguments to the configure script can be specified in the CONFIGURE_ARGS - variable, and the configure script's name can be set in CONFIGURE_SCRIPT if - it differs from the default "configure". Here's an example from the - sysutils/top package: - - HAS_CONFIGURE= yes - CONFIGURE_SCRIPT= Configure - CONFIGURE_ARGS+= netbsd13 - - If the program uses an Imakefile for configuration, the appropriate steps - can be invoked by setting USE_IMAKE to "YES". (If you only want the package - installed in $X11PREFIX but xmkmf not being run, set USE_X11BASE instead!) - -build - - Once configuration has taken place, the software will be built by invoking - $MAKE_PROGRAM on $MAKEFILE with $BUILD_TARGET as the target to build. The - default MAKE_PROGRAM is "gmake" if USE_TOOLS contains "gmake", "make" - otherwise. MAKEFILE is set to "Makefile" by default, and BUILD_TARGET - defaults to "all". Any of these variables can be set in the package's - Makefile to change the default build process. - -install - - Once the build stage has completed, the final step is to install the - software in public directories, so users can access the programs and files. - As in the build-target, $MAKE_PROGRAM is invoked on $MAKEFILE here, but - with the $INSTALL_TARGET instead, the latter defaulting to "install" (plus - "install.man", if USE_IMAKE is set). - -If no target is specified, the default is "build". If a subsequent stage is -requested, all prior stages are made: e.g. make build will also perform the -equivalent of: - - make fetch - make checksum - make extract - make patch - make configure - make build - -14.3. Other helpful targets +When building a package, a number of directories is 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 are two +common base directories for these relative directories: PKGSRCDIR/PKGPATH is +used for directories that are pkgsrc-specific. WRKSRC is used for directories +inside the package itself. The permissions after each variable indicate whether +the variable may be changed by the package Makefile. + +PKGSRCDIR (read-only) + + This is an absolute pathname that points to the pkgsrc root directory. + Generally, you don't need it. + +PKGPATH (read-only) + + This is a pathname relative to PKGSRCDIR that points to the current + package. + +WRKDIR (read-only) + + This is an absolute pathname pointing to the directory where all work takes + place. This directory typically contains temporary directories used by the + various pkgsrc frameworks, like buildlink or the wrappers. + +WRKSRC (read-write) + + This is an absolute pathname pointing to the directory where the distfiles + are extracted. It is usually a direct subdirectory of WRKDIR, and often + it's the only directory entry that isn't hidden. + +14.4. Running a phase + +You can run a particular phase by typing make phase, where phase is the name of +the phase. This will automatically run all phases that are required for this +phase. The default phase is build, that is, when you run make without +parameters in a package directory, the package will be built, but not +installed. + +14.5. The fetch phase + +This will check if the file(s) given in the variables DISTFILES and PATCHFILES +(as defined in the package's Makefile) are present on the local system in /usr/ +pkgsrc/distfiles. If they are not present, an attempt will be made to fetch +them using commands of the form: + + ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS} + +where ${site} varies through several possibilities in turn: first, +MASTER_SITE_OVERRIDE is tried, then the sites specified in either SITES_file if +defined, else MASTER_SITES or PATCH_SITES, as applies, then finally the value +of MASTER_SITE_BACKUP. The order of all except the first can be optionally +sorted by the user, via setting either MASTER_SORT_AWK or MASTER_SORT_REGEX. + +14.6. The checksum phase + +After the distfile(s) are fetched, their checksum is generated and compared +with the checksums stored in the distinfo file. If the checksums don't match, +the build is aborted. This is to ensure the same distfile is used for building, +and that the distfile wasn't changed, e.g. by some malign force, deliberately +changed distfiles on the master distribution site or network lossage. + +14.7. The extract phase + +When the distfiles are present on the local system, they need to be extracted, +as they are usually in the form of some compressed archive format, most +commonly .tar.gz. + +If only some of the distfiles need to be uncompressed, the files to be +uncompressed should be put into EXTRACT_ONLY. + +If the distfiles are not in .tar.gz format, they can be extracted by setting +either EXTRACT_SUFX, or EXTRACT_CMD, EXTRACT_BEFORE_ARGS and +EXTRACT_AFTER_ARGS. In the former case, pkgsrc knows how to extract a number of +suffixes (.tar.gz, .tgz, .tar.gz2, .tbz, .tar.Z, .tar, .shar.gz, .shar.bz2, +.shar.Z, .shar, .Z, .bz2 and .gz; see the definition of the various +DECOMPRESS_CMD variables in bsd.pkg.extract.mk for a complete list). Here's an +example on how to use the other variables for a program that comes with a +compressed shell archive whose name ends in .msg.gz: + + EXTRACT_SUFX= .msg.gz + EXTRACT_CMD= zcat + EXTRACT_BEFORE_ARGS= + EXTRACT_AFTER_ARGS= |sh + +14.8. The patch phase + +After extraction, all the patches named by the PATCHFILES, those present in the +patches subdirectory of the package as well as in $LOCALPATCHES/$PKGPATH (e.g. +/usr/local/patches/graphics/png) are applied. Patchfiles ending in .Z or .gz +are uncompressed before they are applied, files ending in .orig or .rej are +ignored. Any special options to patch(1) can be handed in PATCH_DIST_ARGS. See +Section 8.3, "patches/*" for more details. + +By default patch(1) is given special args to make it fail if the patches apply +with some lines of fuzz. Please fix (regen) the patches so that they apply +cleanly. The rationale behind this is that patches that don't apply cleanly may +end up being applied in the wrong place, and cause severe harm there. + +14.9. The tools phase + +[TODO] + +14.10. The wrapper phase + +[TODO] + +14.11. The configure phase + +Most pieces of software need information on the header files, system calls, and +library routines which are available on the platform they run on. The process +of determining this information is known as configuration, and is usually +automated. In most cases, a script is supplied with the distfiles, and its +invocation results in generation of header files, Makefiles, etc. + +If the package contains a configure script, this can be invoked by setting +HAS_CONFIGURE to "yes". If the configure script is a GNU autoconf script, you +should set GNU_CONFIGURE to "yes" instead. What happens in the configure phase +is roughly: + + .for d in ${CONFIGURE_DIRS} + cd ${WRKSRC} && cd ${d} && env ${CONFIGURE_ENV} \ + ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS} + .endfor + +CONFIGURE_DIRS (default: ".") is a list of pathnames relative to WRKSRC. In +each of these directories, the configure script is run with the environment +CONFIGURE_ENV and arguments CONFIGURE_ARGS. The variables CONFIGURE_ENV, +CONFIGURE_SCRIPT (default: "./configure") and CONFIGURE_ARGS may all be changed +by the package. + +If the program uses an Imakefile for configuration, the appropriate steps can +be invoked by setting USE_IMAKE to "yes". (If you only want the package +installed in ${X11PREFIX} but xmkmf not being run, set USE_X11BASE instead.) + +14.12. The build phase + +For building a package, a rough equivalent of the following code is executed. + + .for d in ${BUILD_DIRS} + cd ${WRKSRC} && cd ${d} && env ${MAKE_ENV} \ + ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \ + -f ${MAKEFILE} ${BUILD_TARGET} + .endfor + +BUILD_DIRS (default: ".") is a list of pathnames relative to WRKSRC. In each of +these directories, MAKE_PROGRAM is run with the environment MAKE_ENV and +arguments BUILD_MAKE_FLAGS. The variables MAKE_ENV, BUILD_MAKE_FLAGS, MAKEFILE +and BUILD_TARGET may all be changed by the package. + +The default value of MAKE_PROGRAM is "gmake" if USE_TOOLS contains "gmake", +"make" otherwise. The default value of MAKEFILE is "Makefile", and BUILD_TARGET +defaults to "all". + +14.13. The test phase + +[TODO] + +14.14. The install phase + +Once the build stage has completed, the final step is to install the software +in public directories, so users can access the programs and files. As in the +build-target, $MAKE_PROGRAM is invoked on $MAKEFILE here, but with the +$INSTALL_TARGET instead, the latter defaulting to "install" (plus +"install.man", if USE_IMAKE is set). + +14.15. The package phase + +[TODO] + +14.16. Other helpful targets pre/post-* @@ -4817,6 +4919,7 @@ should use the following code. If this distinction is not fine enough, you can also use the following defines. FreeBSD __FreeBSD__ + DragonFly __DragonFly__ Linux linux, __linux, __linux__ NetBSD __NetBSD__ OpenBSD __OpenBSD__ |