[Gsrc-commit] /srv/bzr/gsrc/trunk r966: clean up docs and add info on maintaining multiple versions of a package

[Brandon Invergo]

------------------------------------------------------------
revno: 966
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Thu 2012-10-18 00:00:37 +0200
message:
  clean up docs and add info on maintaining multiple versions of a package
modified:
  doc/gsrc.texi

=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi     2012-09-23 16:44:42 +0000
+++ b/doc/gsrc.texi     2012-10-17 22:00:37 +0000
@@ -57,9 +57,10 @@
 
 Introduction
 
-* Building GNU packages::       
+* Building GNU packages::
+* How it works::
 
-Initial setup
+Getting Started
 
 * Building a simple package::   
 * Installing a package::        
@@ -71,6 +72,7 @@
 
 * Global configuration::
 * Package configuration::
+* Maintaining multiple versions of a package::
 
 Appendix
 
@@ -83,13 +85,16 @@
 @chapter Introduction
 
 The GNU Source Release Collection (GSRC) provides a simple way to
-install the latest GNU packages on an existing distribution.
+install the latest GNU packages on an existing distribution. By using
+GSRC, the GNU source packages from @code{ftp.gnu.org} are
+automatically downloaded, compiled and installed, either in your home
+directory or a system-wide directory such as @code{/opt}.
 
-By using GSRC the GNU source packages from @code{ftp.gnu.org} are
-downloaded, compiled and installed, either in your home directory or a
-system-wide directory such as @code{/opt}.  Newer versions of the
-source packages are automatically downloaded and installed when they
-released.
+It allows you, for example, to easily install GNU software for
+yourself on a system on which you do not have permission to install
+software system-wide; or to install the latest, unpatched packages
+when those distributed with your operating system are outdated or not
+configured to your liking.
 
 GSRC is based on the GAR build system by Nick Moffitt and the GARstow
 enhancements by Adam Sampson.  GAR was inspired by BSD Ports, a
@@ -132,10 +137,10 @@
 @c since that is already provided by other groups in different ways.
 
 @menu
-* Building GNU packages::       
+* Building GNU packages::
 @end menu
 
address@hidden Building GNU packages,  , Introduction, Introduction
address@hidden Building GNU packages, , Introduction, Introduction
 @section Building GNU packages
 
 If you have never built a GNU package by hand, this section will
@@ -187,6 +192,13 @@
 The @code{deps/}
 subdirectory contains GARfiles for a few external packages,
 
+To stay up-to-date with the latest releases of GNU software, you can
+pull in recent changes to your local copy of GSRC:
+
address@hidden
+$ bzr update
address@hidden example
+
 @section Initial setup
 
 If you have checked out the source tree from the Bazaar repository you
@@ -398,6 +410,7 @@
 @menu
 * Global configuration::
 * Package configuration::
+* Maintaining multiple versions of a package::
 @end menu
 
 @node Global configuration, Package configuration, , Advanced configuration
@@ -457,13 +470,12 @@
 
 @end table
 
address@hidden Package configuration, ,Global configuration, Advanced 
configuration
address@hidden Pacage configuration
address@hidden Package configuration, Maintaining multiple versions of a 
package, Global configuration, Advanced configuration
address@hidden Package configuration
 
-The build process for each package can be highly customized within its
-own Makefile. Because GNU packages follow a standardized build
-process, customizing the GSRC Makefile for one is
-straightforward. 
+Each package can be highly customized within its own Makefile. Because
+GNU packages follow a standardized build process, customizing the GSRC
+Makefile for 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
@@ -505,6 +517,62 @@
 If the package requires a patch to even build properly, then this is a
 bug in GSRC. Please report such build problems to @email{bug-gsrc@@gnu.org}.
 
address@hidden Maintaining multiple versions of a package, , Package 
configuration, Getting started
address@hidden Maintaining multiple versions of a package
+
+What is actually happening ``under the hood'' when GSRC installs a
+package is slightly more complicated than what has been described so
+far. 
+
+When you install a package, it is first actually installed to the
address@hidden/gnu/packages/} directory in a sub-directory with the name
+<package>-<version> (i.e. @file{/gnu/packages/hello-2.7/}). In the
+example of the package @code{hello}, when the executable @file{hello}
+is installed, it is installed to
address@hidden/gnu/packages/hello-2.7/bin/hello}. All other files installed by
+the package are installed in a similar manner. Next, GSRC makes
+symbolic links to those files inside the parent @file{/gnu/}
+directory. Thus, @file{/gnu/bin/hello} is actually a symlink to
address@hidden/gnu/packages/hello-2.7/bin/hello}. 
+
+When a new version of a package is released, you do not have to
+uninstall the previous version first. When @code{hello 2.8} is built
+and installed, it is put into its own package directory,
address@hidden/gnu/packages/hello-2.8/} and the directory of @code{hello 2.7}
+is left untouched. When GSRC finalizes the installation, the old
+symlinks are removed and new ones are created to the latest
+version. Thus, there would then actually be two versions of the
+package installed, but only one would be in use via the symlinks.
+
+If you want to use a particular version of the package, you may
+pass the @code{GARVERSION} variable to @code{make install}. Be sure to
+update the checksums when you do so, otherwise the process will fail!
+
address@hidden
+$ make -C gnu/hello makesums install GARVERSION=2.7
address@hidden example
+
+If you had previously built version 2.7, then GSRC will merely re-link
+to those files. Of course, if you have not previously built it, or if
+you have run @code{make clean}, the process will start from the
+beginning. 
+
+Note: this will fail if the package naming format or compression
+algorithm has changed between versions (i.e. a change from tar.gz to
+tar.xz); in this case you must also modify @code{DISTFILES}.
+
+Users wishing to maintain different configurations of a package may
+take advantage of the @code{GARPROFILE} variable. Its value is
+appended to the package directory name, allowing you to have multiple
+configurations of the same package version installed. For example:
+
address@hidden
+$ make -C gnu/hello install CONFIGURE_OPTS="--disable-nls" GARPROFILE="-no-nls"
address@hidden example
+
+This would install the newly configured package to
address@hidden/gnu/packages/hello-2.8-no-nls/}. 
+
 @node Appendix, GNU Free Documentation License, Advanced configuration, Top
 @chapter Appendix