From 3a7d867dca72a04958f2368e33f8418e8b8ca7f5 Mon Sep 17 00:00:00 2001 From: rillig Date: Mon, 24 Jul 2006 10:32:36 +0000 Subject: Moved the explanation of the various variables in the "fetch" phase from components.xml to build.xml. Added a list of variable names and a link to the old place. Rewrote and extended the existing documentation to cover most common cases. --- doc/guide/files/build.xml | 143 ++++++++++++++++++++++++++++++++++++----- doc/guide/files/components.xml | 89 ++++--------------------- 2 files changed, 137 insertions(+), 95 deletions(-) (limited to 'doc/guide') diff --git a/doc/guide/files/build.xml b/doc/guide/files/build.xml index 52004c732a1..4c05b5d329a 100644 --- a/doc/guide/files/build.xml +++ b/doc/guide/files/build.xml @@ -1,4 +1,4 @@ - + The build process @@ -207,27 +207,136 @@ the package will be built, but not installed. The <emphasis>fetch</emphasis> 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: + The first step in building a package is to fetch the + distribution files (distfiles) from the sites that are providing + them. This is the task of the fetch + phase. + + +What to fetch and where to get it from + + In simple cases, MASTER_SITES defines + all URLs from where the distfile, whose name is derived from the + DISTNAME variable, is fetched. The more + complicated cases are described below. + + The variable DISTFILES specifies the + list of distfiles that have to be fetched. Its value defaults to + ${DISTNAME}${EXTRACT_SUFX}, so that most + packages don't need to define it at all. + EXTRACT_SUFX is .tar.gz by + default, but can be changed freely. Note that if your package + requires additional distfiles to the default one, you cannot + just append the additional filenames using the + += operator, but you have write for + example: - ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS} + DISTFILES= ${DISTNAME}${EXTRACT_SUFX} additional-files.tar.gz + + + Each of the distfiles is fetched from a list of sites, + usually MASTER_SITES. If the package has + multiple DISTFILES or multiple + PATCHFILES from different sites, you can set + SITES.distfile to + the list of URLs where the file + distfile + (including the suffix) can be found. + + + DISTFILES= ${DISTNAME}${EXTRACT_SUFX} + DISTFILES+= foo-file.tar.gz + SITES.foo-file.tar.gz= \ + http://www.somewhere.com/somehow/ \ + http://www.somewhereelse.com/mirror/somehow/ + + + When actually fetching the distfiles, each item from + MASTER_SITES or SITES.* + gets the name of each distfile appended to it, without an + intermediate slash. Therefore, all site values have to end with + a slash or other separator character. This allows for example to + set MASTER_SITES to a URL of a CGI script + that gets the name of the distfile as a parameter. In this case, + the definition would look like: + + + MASTER_SITES= http://www.example.com/download.cgi?file= - 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. + There are some predefined values for + MASTER_SITES, which can be used in packages. + The names of the variables should speak for themselves. + + + + ${MASTER_SITE_APACHE} + ${MASTER_SITE_BACKUP} + ${MASTER_SITE_CYGWIN} + ${MASTER_SITE_DEBIAN} + ${MASTER_SITE_FREEBSD} + ${MASTER_SITE_FREEBSD_LOCAL} + ${MASTER_SITE_GNOME} + ${MASTER_SITE_GNU} + ${MASTER_SITE_GNUSTEP} + ${MASTER_SITE_IFARCHIVE} + ${MASTER_SITE_KDE} + ${MASTER_SITE_MOZILLA} + ${MASTER_SITE_MYSQL} + ${MASTER_SITE_OPENOFFICE} + ${MASTER_SITE_PERL_CPAN} + ${MASTER_SITE_PGSQL} + ${MASTER_SITE_R_CRAN} + ${MASTER_SITE_SOURCEFORGE} + ${MASTER_SITE_SOURCEFORGE_JP} + ${MASTER_SITE_SUNSITE} + ${MASTER_SITE_SUSE} + ${MASTER_SITE_TEX_CTAN} + ${MASTER_SITE_XCONTRIB} + ${MASTER_SITE_XEMACS} + + + If you choose one of these predefined sites, you may want + to specify a subdirectory of that site. Since these macros may + expand to more than one actual site, you + must use the following construct to specify + a subdirectory: + + + MASTER_SITES= ${MASTER_SITE_GNU:=subdirectory/name/} + MASTER_SITES= ${MASTER_SITE_SOURCEFORGE:=project_name/} + + + Note the trailing slash after the subdirectory + name. + + + +How are the files fetched? + + The fetch phase makes sure that all + the distfiles exist in a local directory + (DISTDIR), which can be set by the pkgsrc + user). If the files do not exist, they are fetched 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. + + diff --git a/doc/guide/files/components.xml b/doc/guide/files/components.xml index 713331af9a3..52814689bbd 100644 --- a/doc/guide/files/components.xml +++ b/doc/guide/files/components.xml @@ -1,4 +1,4 @@ - + Package components - files, directories and contents @@ -21,7 +21,10 @@ sections that describe the package. In the first section there are the following variables, which - should appear exactly in the order given here. + should appear exactly in the order given here. The ordering and + grouping of variables is mostly historical and has no further + meaning. + DISTNAME is the basename of the @@ -56,83 +59,13 @@ - MASTER_SITES is a list of URLs where - the distribution files can be downloaded. Each URL must end with a - slash. - The MASTER_SITES may make use of - the following predefined sites: - - - - ${MASTER_SITE_APACHE} - ${MASTER_SITE_BACKUP} - ${MASTER_SITE_CYGWIN} - ${MASTER_SITE_DEBIAN} - ${MASTER_SITE_FREEBSD} - ${MASTER_SITE_FREEBSD_LOCAL} - ${MASTER_SITE_GNOME} - ${MASTER_SITE_GNU} - ${MASTER_SITE_GNUSTEP} - ${MASTER_SITE_IFARCHIVE} - ${MASTER_SITE_MOZILLA} - ${MASTER_SITE_OPENOFFICE} - ${MASTER_SITE_PERL_CPAN} - ${MASTER_SITE_R_CRAN} - ${MASTER_SITE_SOURCEFORGE} - ${MASTER_SITE_SUNSITE} - ${MASTER_SITE_SUSE} - ${MASTER_SITE_TEX_CTAN} - ${MASTER_SITE_XCONTRIB} - ${MASTER_SITE_XEMACS} - - - If one of these predefined sites is chosen, you may - want to specify a subdirectory of that - site. Since these macros may expand to more than one - actual site, you must use the - following construct to specify a subdirectory: - - - ${MASTER_SITE_GNU:=subdirectory/name/} - ${MASTER_SITE_SOURCEFORGE:=project_name/} - - - Note the trailing slash after the subdirectory name. - - If the package has multiple - DISTFILES or multiple - PATCHFILES from different - sites, set SITES.foo to a list of URIs - where file foo may be - found. foo includes the suffix, e.g.: + MASTER_SITES, + DYNAMIC_MASTER_SITES, + DIST_SUBDIR, EXTRACT_SUFX + and DISTFILES are discussed in detail in + . - - DISTFILES= ${DISTNAME}${EXTRACT_SUFX} - DISTFILES+= foo-file.tar.gz - SITES.foo-file.tar.gz= \ - http://www.somewhere.com/somehow/ \ - http://www.somewhereelse.com/mirror/somehow/ - - - - DISTFILES: Name(s) - of archive file(s) containing distribution. The default is - ${DISTNAME}${EXTRACT_SUFX}. Should only - be set if you have more than one distfile. - Note that the normal default setting of - DISTFILES must be made explicit if you - want to add to it (rather than replace it), as you usually - would. - - - EXTRACT_SUFX: Suffix of the - distribution file, will be appended to - DISTNAME. Defaults to - .tar.gz. - - - - + The second section contains information about separately downloaded patches, if any. -- cgit v1.2.3