pkgsrc-Changes-HG archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

[pkgsrc/trunk]: pkgsrc/doc/guide/files Improve markup. Describe MASTER_SITE_B...



details:   https://anonhg.NetBSD.org/pkgsrc/rev/bb4274fd6593
branches:  trunk
changeset: 518581:bb4274fd6593
user:      wiz <wiz%pkgsrc.org@localhost>
date:      Wed Sep 13 23:23:00 2006 +0000

description:
Improve markup. Describe MASTER_SITE_BACKUP and MASTER_SITE_LOCAL.
Document NO_INSTALL_MANPAGES. Describe "The package phase".
Add section about "Cleaning up". Document DEPENDS_TARGET.
Document the bin-install target. Improve UPDATE_TARGET description.
Use &rprompt; and &cprompt; instead of <prompt>.</prompt>.
Document replace and index targets.

Reindent and break lines for 80 characters.

diffstat:

 doc/guide/files/build.xml |  1352 +++++++++++++++++++++++++-------------------
 1 files changed, 775 insertions(+), 577 deletions(-)

diffs (truncated from 1689 to 300 lines):

diff -r 914bb86e2802 -r bb4274fd6593 doc/guide/files/build.xml
--- a/doc/guide/files/build.xml Wed Sep 13 21:09:08 2006 +0000
+++ b/doc/guide/files/build.xml Wed Sep 13 23:23:00 2006 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: build.xml,v 1.34 2006/09/10 19:51:49 wiz Exp $ -->
+<!-- $NetBSD: build.xml,v 1.35 2006/09/13 23:23:00 wiz Exp $ -->
 
 <chapter id="build">
   <title>The build process</title>
@@ -37,7 +37,7 @@
     where all files of the final program shall be installed. It is
     usually set to <varname>LOCALBASE</varname>
     (<filename>/usr/pkg</filename>), or <varname>CROSSBASE</varname>
-    for pkgs in the <quote>cross</quote> category.  The value of
+    for pkgs in the <filename>cross</filename> category.  The value of
     <varname>PREFIX</varname> needs to be put
     into the various places in the program's source where paths to
     these files are encoded.  See <xref
@@ -49,16 +49,17 @@
 
     <itemizedlist>
       <listitem>
-       <para><varname>PREFIX</varname> always points to the location where the current
-       pkg will be installed.  When referring to a pkg's own installation path,
-       use <quote>${PREFIX}</quote>.</para>
+       <para><varname>PREFIX</varname> always points to the location
+       where the current pkg will be installed.  When referring to a
+       pkg's own installation path, use
+       <quote>${PREFIX}</quote>.</para>
       </listitem>
 
       <listitem>
-       <para><varname>LOCALBASE</varname> is where all non-X11 pkgs are installed.
-       If you need to construct a -I or -L argument to the compiler to find
-       includes and libraries installed by another non-X11 pkg, use
-       <quote>${LOCALBASE}</quote>. The name
+       <para><varname>LOCALBASE</varname> is where all non-X11 pkgs
+       are installed.  If you need to construct a -I or -L argument
+       to the compiler to find includes and libraries installed by
+       another non-X11 pkg, use <quote>${LOCALBASE}</quote>. The name
        <varname>LOCALBASE</varname> stems from FreeBSD, which
        installed all packages in <filename>/usr/local</filename>. As
        pkgsrc leaves <filename>/usr/local</filename> for the system
@@ -66,21 +67,23 @@
       </listitem>
 
       <listitem>
-       <para><varname>X11BASE</varname> is where the actual X11 distribution (from
-       xsrc, etc.) is installed. When looking for
-       <emphasis>standard</emphasis> X11 includes (not
-       those installed by a pkg), use <quote>${X11BASE}</quote>.</para>
+       <para><varname>X11BASE</varname> is where the actual X11
+       distribution (from xsrc, etc.) is installed. When looking for
+       <emphasis>standard</emphasis> X11 includes (not those
+       installed by a package), use <quote>${X11BASE}</quote>.</para>
       </listitem>
 
       <listitem>
-       <para>X11-based packages are special in that they may be installed in
-       either <varname>X11BASE</varname> or <varname>LOCALBASE</varname>.</para>
+       <para>X11-based packages are special in that they may be
+       installed in either <varname>X11BASE</varname> or
+       <varname>LOCALBASE</varname>.</para>
 
        <para>Usually, X11 packages should be installed under
-       <varname>LOCALBASE</varname> whenever possible.  Note that you will
-       need to include <filename>../../mk/x11.buildlink3.mk</filename>
-       in them to request the
-       presence of X11 and to get the right compilation flags.</para>
+       <varname>LOCALBASE</varname> whenever possible.  Note that you
+       will need to include
+       <filename>../../mk/x11.buildlink3.mk</filename> in them to
+       request the presence of X11 and to get the right compilation
+       flags.</para>
 
        <para>Even though, there are some packages that cannot be installed
        under <varname>LOCALBASE</varname>: those that come with app-defaults
@@ -101,21 +104,25 @@
       </listitem>
 
       <listitem>
-       <para><varname>X11PREFIX</varname> should be used to refer to the installed
-       location of an X11 package. <varname>X11PREFIX</varname> will be set to
-       <varname>X11BASE</varname> if xpkgwedge is not installed,
-       and to <varname>LOCALBASE</varname> if xpkgwedge is installed.</para>
+       <para><varname>X11PREFIX</varname> should be used to refer to
+       the installed location of an X11
+       package. <varname>X11PREFIX</varname> will be set to
+       <varname>X11BASE</varname> if xpkgwedge is not installed, and
+       to <varname>LOCALBASE</varname> if xpkgwedge is
+       installed.</para>
       </listitem>
 
       <listitem>
-       <para>If xpkgwedge is installed, it is possible to have some packages installed
-       in <varname>X11BASE</varname> and some in <varname>LOCALBASE</varname>.
-       To determine the prefix of an installed package, the
-       <varname>EVAL_PREFIX</varname> definition can be used. It takes pairs in the
-       format <quote>DIRNAME=&lt;package&gt;</quote>, and the &man.make.1; variable
-       <varname>DIRNAME</varname> will be set to the prefix of the installed
-       package &lt;package&gt;, or <quote>${X11PREFIX}</quote> if the package is
-       not installed.</para>
+       <para>If xpkgwedge is installed, it is possible to have some
+       packages installed in <varname>X11BASE</varname> and some in
+       <varname>LOCALBASE</varname>.  To determine the prefix of an
+       installed package, the <varname>EVAL_PREFIX</varname>
+       definition can be used. It takes pairs in the format
+       <quote>DIRNAME=&lt;package&gt;</quote>, and the &man.make.1;
+       variable <varname>DIRNAME</varname> will be set to the prefix
+       of the installed package &lt;package&gt;, or
+       <quote>${X11PREFIX}</quote> if the package is not
+       installed.</para>
 
        <para>This is best illustrated by example.</para>
 
@@ -129,8 +136,9 @@
          CONFIGURE_ARGS+=        --enable-multibyte
        </programlisting>
 
-       <para>Specific defaults can be defined for the packages evaluated using
-       <varname>EVAL_PREFIX</varname>, by using a definition of the form:</para>
+       <para>Specific defaults can be defined for the packages
+       evaluated using <varname>EVAL_PREFIX</varname>, by using a
+       definition of the form:</para>
 
        <programlisting>
          GTKDIR_DEFAULT= ${LOCALBASE}
@@ -207,457 +215,520 @@
   <sect1 id="build.fetch">
     <title>The <emphasis>fetch</emphasis> phase</title>
 
-       <para>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 <emphasis>fetch</emphasis>
-       phase.</para>
+    <para>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 <emphasis>fetch</emphasis>
+    phase.</para>
 
-<sect2 id="build.fetch.what">
-<title>What to fetch and where to get it from</title>
+    <sect2 id="build.fetch.what">
+      <title>What to fetch and where to get it from</title>
+
+      <para>In simple cases, <varname>MASTER_SITES</varname>
+      defines all URLs from where the distfile, whose name is
+      derived from the <varname>DISTNAME</varname> variable, is
+      fetched. The more complicated cases are described
+      below.</para>
 
-       <para>In simple cases, <varname>MASTER_SITES</varname> defines
-       all URLs from where the distfile, whose name is derived from the
-       <varname>DISTNAME</varname> variable, is fetched. The more
-       complicated cases are described below.</para>
+      <para>The variable <varname>DISTFILES</varname> specifies
+      the list of distfiles that have to be fetched. Its value
+      defaults to <literal>${DISTNAME}${EXTRACT_SUFX}</literal>,
+      so that most packages don't need to define it at all.
+      <varname>EXTRACT_SUFX</varname> is
+      <literal>.tar.gz</literal> 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 <literal>+=</literal>
+      operator, but you have write for example:</para>
 
-       <para>The variable <varname>DISTFILES</varname> specifies the
-       list of distfiles that have to be fetched. Its value defaults to
-       <literal>${DISTNAME}${EXTRACT_SUFX}</literal>, so that most
-       packages don't need to define it at all.
-       <varname>EXTRACT_SUFX</varname> is <literal>.tar.gz</literal> 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
-       <literal>+=</literal> operator, but you have write for
-       example:</para>
+      <programlisting>
+       DISTFILES=      ${DISTNAME}${EXTRACT_SUFX} additional-files.tar.gz
+      </programlisting>
 
-<programlisting>
-    DISTFILES=      ${DISTNAME}${EXTRACT_SUFX} additional-files.tar.gz
-</programlisting>
-
-       <para>Each of the distfiles is fetched from a list of sites,
-       usually <varname>MASTER_SITES</varname>. If the package has
-       multiple <varname>DISTFILES</varname> or multiple
-       <varname>PATCHFILES</varname> from different sites, you can set
-       <varname>SITES.<replaceable>distfile</replaceable></varname> to
-       the list of URLs where the file
-       <filename><replaceable>distfile</replaceable></filename>
-       (including the suffix) can be found.</para>
+      <para>Each distfile is fetched from a list of sites, usually
+      <varname>MASTER_SITES</varname>. If the package has multiple
+      <varname>DISTFILES</varname> or multiple
+      <varname>PATCHFILES</varname> from different sites, you can
+      set
+      <varname>SITES.<replaceable>distfile</replaceable></varname>
+      to the list of URLs where the file
+      <filename><replaceable>distfile</replaceable></filename>
+      (including the suffix) can be found.</para>
 
-<programlisting>
-    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/
-</programlisting>
+      <programlisting>
+       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/
+      </programlisting>
+      
+      <para>When actually fetching the distfiles, each item from
+      <varname>MASTER_SITES</varname> or
+      <varname>SITES.*</varname> 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
+      <varname>MASTER_SITES</varname> 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:</para>
 
-       <para>When actually fetching the distfiles, each item from
-       <varname>MASTER_SITES</varname> or <varname>SITES.*</varname>
-       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 <varname>MASTER_SITES</varname> 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:</para>
+      <programlisting>
+       MASTER_SITES=   http://www.example.com/download.cgi?file=
+      </programlisting>
 
-<programlisting>
-    MASTER_SITES=   http://www.example.com/download.cgi?file=
-</programlisting>
+      <para>There are some predefined values for
+      <varname>MASTER_SITES</varname>, which can be used in
+      packages.  The names of the variables should speak for
+      themselves.</para>
 
-       <para>There are some predefined values for
-       <varname>MASTER_SITES</varname>, which can be used in packages.
-       The names of the variables should speak for themselves.</para>
+      <!-- sort mk/fetch/sites.mk | sed -n 's/\(^MA[A-Z_]*\).*/    ${\1}/p' -->
 
-<!-- sort mk/fetch/sites.mk | sed -n 's/\(^MA[A-Z_]*\).*/    ${\1}/p' -->
-<programlisting>
-    ${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}
-</programlisting>
+      <programlisting>
+       ${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}



Home | Main Index | Thread Index | Old Index