[Gsrc-commit] trunk r2728: update documentation

[Brandon Invergo]

------------------------------------------------------------
revno: 2728
revision-id: address@hidden
parent: address@hidden
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Fri 2013-11-15 19:56:36 +0100
message:
  update documentation
modified:
  doc/gsrc.texi                  gsrc.texi-20100621151235-73qm58fnc905qvlr-1

=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi     2013-10-28 20:39:26 +0000
+++ b/doc/gsrc.texi     2013-11-15 18:56:36 +0000
@@ -132,14 +132,14 @@
 
 @c This document uses the term ``GNU package'' to refer to software
 @c written as part of the GNU Project.  The meaning of the term ``GNU
address@hidden package'' is best made clear by understanding its origin.x 
address@hidden package'' is best made clear by understanding its origin.x
 
 @c In the early 1980's Richard Stallman wrote a manifesto calling for the
 @c creation of a computer operating system where all programs could be
 @c freely modified and shared by anyone---a system that would be entirely
 @c ``free software''.  He gave this system the name ``GNU'' and started
 @c an initiative with others to develop it (this initiative was known as
address@hidden the ``GNU Project'').  
address@hidden the ``GNU Project'').
 
 @c The design of the GNU system specified many new programs that needed
 @c to be written, but also included some existing programs developed by
@@ -166,7 +166,7 @@
 doing.
 
 @itemize @bullet
address@hidden Download the package and unpack it 
address@hidden Download the package and unpack it
 @example
 $ wget http://ftpmirror.gnu.org/gnu/hello/hello-2.6.tar.gz
 $ tar xvfz hello-2.6.tar.gz
@@ -397,7 +397,7 @@
 target.
 
 To see some information about a package, use the target
address@hidden 
address@hidden
 
 @example
 $ make -C gnu/hello pkg-info
@@ -406,7 +406,7 @@
 Version:     2.8
 URL:         http://www.gnu.org/software/hello/manual/
 Description:
- GNU Hello prints the message "Hello, world!" and then exits.  It 
+ GNU Hello prints the message "Hello, world!" and then exits.  It
  serves as an example of standard GNU coding practices.  As such, it
  supports command-line arguments, multiple languages, and so on.
 Status:      installed (stowed)
@@ -437,24 +437,28 @@
 Name: hello
 Version: 2.8
 Location: http://ftpmirror.gnu.org/hello/
-Distribution files: 
+Distribution files:
        hello-2.8.tar.gz
-Patch files: 
-Signature files: 
+Patch files:
+Signature files:
        hello-2.8.tar.gz.sig
-Dependencies: 
+Dependencies:
 make: Leaving directory `/home/gnu/gsrc/gnu/hello'
 @end example
 
 Most GNU packages are highly configurable. To see which configuration
 options are available to you, you may invoke the @option{help-config}
-target. 
+target.
 
 Finally, if you choose to remove a package, you may use the
 @option{uninstall} target. This target ``un-stows'' the package; if you
 were to re-install it, the package would not need to be
-re-built. Instead, it would merely be re-stowed. To completely remove
-a package, use the @option{uninstall-pkg} target.
+re-built. Instead, it would merely be re-stowed. To completely remove a
+package, use the @option{uninstall-pkg} target.  When you update a
+package to a new version, the old version is merely un-stowed and the
+new version is installed alongside it @pxref{Package versions}.  In
+order to clean out old package versions, use the
address@hidden target.
 
 
 @node Complex packages, Finding packages, Useful targets, Getting started
@@ -532,7 +536,7 @@
  A source code tag system
 gnu/gnusound 0.7.5
  A multitrack sound editor
-gnu/leg 
+gnu/leg
  Libraries for game engines and game development
 gnu/less 451
  A pager
@@ -553,7 +557,7 @@
 Description:
  GNU Moe is a powerful-but-simple-to-use text editor.  It works in a
  modeless manner, and features an intuitive set of key-bindings that
- assign a degree of "severity" to each key; for example key 
+ assign a degree of "severity" to each key; for example key
  combinations with the Alt key are for harmless commands like cursor
  movements while combinations with the Control key are for commands
  that will modify the text.  Moe features multiple windows, unlimited
@@ -565,7 +569,7 @@
 
 If you view the @file{gsrc} script's code, you will find that it is
 very simple and, indeed, can be used as a template to be expanded to
-include the functionality that you desire. 
+include the functionality that you desire.
 
 More robust searching can be performed with the file
 @file{MANIFEST.rec}. If you have acquired GSRC by downloading it as a
@@ -611,10 +615,17 @@
 @item gar.master.mk
 Defines the list of mirror sites used to download the source
 tarballs. It is recommended to modify this to use local mirrors.
address@hidden gar.site.mk
+An optional file that you can create to load extra recipes to use on
+packages.  This file must be created by the user (however, it is not an
+eroror if the file does not exist).
 @end table
 
-The local file @file{gar.site.mk} is loaded last and can be used to
-override any configuration variables.
+Much of the behavior of GSRC is defined by variables that can be
+customized.  Generally speaking, you should override these variables in
+your @file{config.mk} file rather than in the @file{gar.*.mk} files.
+That way, you do not have to worry about updates to GSRC overwriting
+your changes.
 
 Some of the more important configuration variables are:
 
@@ -630,7 +641,7 @@
 @code{BOOTSTRAP} undefined on the command-line:
 
 @example
-$ make -C gnu/gnupg BOOTSTRAP= 
+$ make -C gnu/gnupg BOOTSTRAP=
 @end example
 
 Set in @file{conf.mk}
@@ -687,13 +698,13 @@
 
 Each package can be customized to your liking. Because GNU packages
 follow a standardized build process, customizing the GSRC build for
-one is straightforward.  
+one is straightforward.
 
 GNU packages take most of their configuration in the form of options
 passed to the @file{configure} script. One may easily customize these
 options in a GSRC Makefile by setting the @code{CONFIGURE_OPTS}
 variable. Any options added to this variable will be appended to the
-options set by default by GSRC. 
+options set by default by GSRC.
 
 @example
 CONFIGURE_OPTS = --disable-gtk --without-png
@@ -704,7 +715,7 @@
 user configuration may be done here. By default, it contains the
 @code{CONFIGURE_OPTS} and @code{BUILD_OPTS} variables. In some special
 cases, package-specific, user-customize-able variables are also
-defined in this file. 
+defined in this file.
 
 Generally speaking, user configuration is done exclusively in
 @file{config.mk} while @file{Makefile} contains the information and
@@ -731,10 +742,10 @@
 
 @code{PATCHFILES} holds a list of all the patch files in the
 @file{files} subdirectory. @code{PATCHOPTS} contains the option switches
-to pass to the @command{patch} program. 
+to pass to the @command{patch} program.
 
 Next, the patch file's checksum is added to the checksums file for the
-package. 
+package.
 
 @example
 $ make makesum
@@ -746,7 +757,7 @@
 skip this key verification step.
 
 Finally, you may build the package as normal. The patch(es) will be
-applied automatically in the process. 
+applied automatically in the process.
 
 @example
 $ make install
@@ -759,7 +770,7 @@
 
 If the package requires a patch to even build properly, then this is a
 bug in GSRC. Please report such build problems to
address@hidden@@gnu.org}. 
address@hidden@@gnu.org}.
 
 
 @node Package versions,  , Patching packages, Advanced configuration
@@ -767,7 +778,7 @@
 
 What is actually happening ``under the hood'' when GSRC installs a
 package is slightly more complicated than what has been described so
-far. 
+far.
 
 When you install a package, it is first actually installed to the
 @file{/gnu/packages} directory in a sub-directory with the name
@@ -818,7 +829,7 @@
 @end example
 
 This would install the newly configured package to
address@hidden/gnu/packages/hello-2.8-no-nls}. 
address@hidden/gnu/packages/hello-2.8-no-nls}.
 
 
 @node Technical information, GNU Free Documentation License, Advanced 
configuration, Top
@@ -900,7 +911,7 @@
 @option{build} or @option{install}, come from @file{gar.mk}. Depending on
 the package's build requirements, as defined in the package's GSRC
 Makefile, these user-level targets will depend on lower-level targets
-that actually perform the required tasks. 
+that actually perform the required tasks.
 
 For example, in a typical GNU package, configuration is done with a
 @file{configure} script while building and installing are done with a
@@ -917,7 +928,7 @@
 The directory @file{gar.lib} contains Makefiles that set common
 variable values for packages that share similar build systems. It has
 a file called @file{auto.mk}, for example, that defines the settings
-for a package that uses the standard Autotools process. 
+for a package that uses the standard Autotools process.
 
 
 @node  Anatomy of a GSRC Makefile,  , The GSRC build system, Technical 
information
@@ -926,7 +937,7 @@
 GSRC Makefiles are the point of entry for the user into the GSRC
 system. Since GSRC supplies GNU software and there are GNU coding
 standards that dictate how package installation is supposed to work,
-the GSRC Makefiles for most GNU software packages are similar. 
+the GSRC Makefiles for most GNU software packages are similar.
 
 In order to facilitate working with the GSRC Makefiles in an automated
 way, such as searching them via a script, they all share a common
@@ -1005,7 +1016,7 @@
 @code{DESCRIPTION}
 @tab
 This variable should have a short, one-line description of the
-package. 
+package.
 
 @item
 @code{BLURB}
@@ -1053,7 +1064,7 @@
 @item
 @code{DISTFILE_SITES}
 @tab
-This variable contains URL(s) from which source distribution archives 
+This variable contains URL(s) from which source distribution archives
 only are to be downloaded.
 
 @item
@@ -1093,7 +1104,7 @@
 default this contains the @file{files} sub-directory of the package's
 GSRC directory and the location specified by the variable
 @code{GARCHIVEDIR}. Note that these URIs should be prefaced with
-``file://''. 
+``file://''.
 
 @item
 @code{DISTFILES}
@@ -1123,7 +1134,7 @@
 archive extracts to a directory with some other name, you should set
 it here. This should always begin with @code{$(WORKDIR)}, which by
 default is the @file{work} subdirectory of the GSRC package's
-sub-directory. 
+sub-directory.
 
 @item
 @code{WORKOBJ}
@@ -1197,7 +1208,7 @@
 Finally, if necessary, the actual recipes are written. Note that if
 @file{gar.lib/auto.mk} was included, no recipes should need to be
 written. In general, there are two kinds of targets for which recipes
-may need to be written. 
+may need to be written.
 
 The first correspond to the files listed under
 @code{CONFIGURE_SCRIPTS}, @code{BUILD_SCRIPTS} and
@@ -1230,7 +1241,7 @@
 HOME_URL = http://www.gnu.org/software/hello/manual/
 DESCRIPTION = A program that produces a familiar, friendly greeting
 define BLURB
-GNU Hello prints the message "Hello, world!" and then exits.  It 
+GNU Hello prints the message "Hello, world!" and then exits.  It
 serves as an example of standard GNU coding practices.  As such, it
 supports command-line arguments, multiple languages, and so on.
 endef
@@ -1242,8 +1253,8 @@
 DISTFILES = $(DISTNAME).tar.gz
 SIGFILES = $(DISTNAME).tar.gz.sig
 
-BUILDDEPS = 
-LIBDEPS = 
+BUILDDEPS =
+LIBDEPS =
 
 ######################################################################
 
@@ -1262,7 +1273,7 @@
 HOME_URL = http://www.fsfla.org/svnwiki/selibre/linux-libre/
 DESCRIPTION = A free version of the Linux kernel
 define BLURB
-Linux Libre is a free (as in freedom) variant of the Linux kernel. 
+Linux Libre is a free (as in freedom) variant of the Linux kernel.
 It has been modified to remove any non-free binary blobs.
 endef
 
@@ -1278,8 +1289,8 @@
 BUILD_SCRIPTS = $(WORKSRC)/Makefile
 INSTALL_SCRIPTS = kernel
 
-BUILDDEPS = 
-LIBDEPS = 
+BUILDDEPS =
+LIBDEPS =
 
 ######################################################################
 
@@ -1329,4 +1340,3 @@
 @include fdl.texi
 
 @bye
-