[bug-gsrc] /srv/bzr/gsrc/trunk r759: updating documentation

[Brian Gough]

------------------------------------------------------------
revno: 759
committer: Brian Gough <address@hidden>
branch nick: trunk
timestamp: Mon 2011-08-08 17:46:05 +0100
message:
  updating documentation
modified:
  doc/gsrc.texi
  doc/version.texi

=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi     2010-12-20 12:29:36 +0000
+++ b/doc/gsrc.texi     2011-08-08 16:46:05 +0000
@@ -56,6 +56,23 @@
 * The build system::            
 * GNU Free Documentation License::  
 * Index::                       
+
address@hidden
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Building GNU packages::       
+
+Initial setup
+
+* Building a simple package::   
+* Installing a package::        
+* Setting your environment to use installed packages::  
+* Cleaning up and other useful targets::  
+* Building a more complex package::  
+
address@hidden detailmenu
 @end menu
 
 @node Introduction, Getting started, Top, Top
@@ -85,30 +102,30 @@
 so you will need to make sure these are already installed for GNU
 programs which use them.
 
address@hidden Terminology
-
-This document uses the term ``GNU package'' to refer to software
-written as part of the GNU Project.  The meaning of the term ``GNU
-package'' is best made clear by understanding its origin.x 
-
-In the early 1980's Richard Stallman wrote a manifesto calling for the
-creation of a computer operating system where all programs could be
-freely modified and shared by anyone---a system that would be entirely
-``free software''.  He gave this system the name ``GNU'' and started
-an initiative with others to develop it (this initiative was known as
-the ``GNU Project'').  
-
-The design of the GNU system specified many new programs that needed
-to be written, but also included some existing programs developed by
-others that were free software.  The programs developed specifically
-for the GNU system are referred to as ``GNU software'', or ``GNU
-packages''.  Thus not every program on the GNU system is GNU software,
-only those written specifically for it.
-
-GSRC is a collection of these GNU packages, the software which is
-written and maintained as part of the GNU Project.  It does not
-attempt to include all the other free software in the GNU system,
-since that is already provided by other groups in different ways.
address@hidden @section Terminology
+
address@hidden This document uses the term ``GNU package'' to refer to software
address@hidden 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 In the early 1980's Richard Stallman wrote a manifesto calling 
for the
address@hidden creation of a computer operating system where all programs could 
be
address@hidden freely modified and shared by anyone---a system that would be 
entirely
address@hidden ``free software''.  He gave this system the name ``GNU'' and 
started
address@hidden an initiative with others to develop it (this initiative was 
known as
address@hidden the ``GNU Project'').  
+
address@hidden The design of the GNU system specified many new programs that 
needed
address@hidden to be written, but also included some existing programs 
developed by
address@hidden others that were free software.  The programs developed 
specifically
address@hidden for the GNU system are referred to as ``GNU software'', or ``GNU
address@hidden packages''.  Thus not every program on the GNU system is GNU 
software,
address@hidden only those written specifically for it.
+
address@hidden GSRC is a collection of these GNU packages, the software which is
address@hidden written and maintained as part of the GNU Project.  It does not
address@hidden attempt to include all the other free software in the GNU system,
address@hidden since that is already provided by other groups in different ways.
 
 @menu
 * Building GNU packages::       
@@ -123,24 +140,37 @@
 
 @itemize @bullet
 @item Download the package and unpack it 
address@hidden wget http://ftpmirror.gnu.org/gnu/hello/hello-2.6.tar.gz}
address@hidden tar xvfz hello-2.6.tar.gz}
address@hidden
+$ wget http://ftpmirror.gnu.org/gnu/hello/hello-2.6.tar.gz
+$ tar xvfz hello-2.6.tar.gz
address@hidden example
+
 @item Run the configure script
address@hidden cd hello-2.6; ./configure}
address@hidden
+$ cd hello-2.6; ./configure
address@hidden example
+
 @item Compile the source code
address@hidden make}
address@hidden
+$ make
address@hidden example
+
 @item Install it
address@hidden make install}
address@hidden
+$ make install
address@hidden example
+
 @end itemize
 
 @node Getting started, Advanced configuration, Introduction, Top
 @chapter Getting started
 
-GSRC is distributed directly using the Bazaar version control system.
-You can check out the latest version using
+GSRC is distributed directly using the Bazaar version control system
+or via a tarball.  You can check out the latest version from the
+Bazaar repository using
 
 @example
-bzr checkout http://bzr.savannah.gnu.org/r/gsrc/trunk/ gsrc
+$ bzr checkout bzr://bzr.savannah.gnu.org/gsrc/trunk/ gsrc
 @end example
 @noindent
 This will create a directory @file{gsrc}.  The build definitions for
@@ -155,24 +185,169 @@
 
 @section Initial setup
 
+If you have checked out the source tree from the Bazaar repository you
+will need to create the build files with the following command,
+
address@hidden
+$ ./bootstrap
address@hidden example
+
+Before building any packages you will need to run the top-level
+configure script.  There is only one configuration parameter, the
+installation prefix, specified with @option{--prefix}.  For example,
+to install all the compiled packages under @file{/gnu} use:
+
address@hidden
+$ ./configure --prefix=/gnu
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+checking for a thread-safe mkdir -p... /bin/mkdir -p
+checking for gawk... no
+checking for mawk... mawk
+checking whether make sets $(MAKE)... yes
+configure: creating ./config.status
+config.status: creating config.mk
+config.status: creating setup.sh
+config.status: creating GNUmakefile
+config.status: creating doc/Makefile
+$
address@hidden example
+
 
 @menu
 * Building a simple package::   
 * Installing a package::        
 * Setting your environment to use installed packages::  
+* Cleaning up and other useful targets::  
 * Building a more complex package::  
 @end menu
 
 @node  Building a simple package, Installing a package, Getting started, 
Getting started
 @section Building a simple package
 
+To build any package, simply type @code{make} in the package's
+subdirectory.  You can change to the directory with the @code{cd}
+command in the shell, or with the @option{-C} option of @code{make}.
+For example, to build the @file{hello} package in the @file{gnu/hello}
+subdirectory use:
+
address@hidden
+$ make -C gnu/hello
address@hidden example
+
+This will download, unpack, configure and build the @file{hello} package.
+The package will be built in the subdirectory @file{gnu/hello/work}.
+
address@hidden
+$ ./gnu/hello/work/hello-2.7/src/hello
+Hello, world!
address@hidden example
+
 @node Installing a package, Setting your environment to use installed 
packages, Building a simple package, Getting started
 @section Installing a package
 
address@hidden Setting your environment to use installed packages, Building a 
more complex package, Installing a package, Getting started
+You are now ready to install the package.  If you are installing to a
+new directory tree, first create the directory specified in the
+top-level configure @option{--prefix} option if necessary,
+
address@hidden
+$ mkdir /gnu
address@hidden example
+
+Then to install the package use the @code{install} target,
+
address@hidden
+$ make -C gnu/hello install
address@hidden example
+
+The package should be automatically installed under @file{/gnu/}, with
+any executable programs under @code{/gnu/bin/}.
+
address@hidden
+$ /gnu/bin/hello --version
+hello (GNU hello) 2.7
address@hidden example
+
+
address@hidden Setting your environment to use installed packages, Cleaning up 
and other useful targets, Installing a package, Getting started
 @section Setting your environment to use installed packages
 
address@hidden Building a more complex package,  , Setting your environment to 
use installed packages, Getting started
+If you want to use the newly installed package by default you will
+need to modify the relevant variables in your environment, such as
address@hidden, @code{LD_LIBRARY_PATH}, @code{INFOPATH}, etc.
+
+There is a sample script @file{setup.sh} in the top-level source
+directory which can be used to set the main environment variables.
+
address@hidden
+$ source setup.sh
address@hidden example
+
+Note that you need to load this file into the current shell with the
address@hidden command, instead of executing it (which would only apply
+the definitions temporarily in a subshell).
+
+After loading this file, your environment variables should include the
+target directory so you can run the new packages directly:
+
address@hidden
+$ echo $PATH
+/gnu/bin:/usr/local/bin:/usr/bin:/bin
+$ which hello
+/gnu/bin/hello
address@hidden example
+
+If you want to restore your original environment variables they are
+saved in the variables @code{ORIG_PATH}, @code{ORIG_LD_LIBRARY_PATH},
+etc.
+
address@hidden
+$ PATH=$ORIG_PATH
+$ LD_LIBRARY_PATH=$ORIG_LD_LIBRARY_PATH
address@hidden example
+
+
address@hidden Cleaning up and other useful targets, Building a more complex 
package, Setting your environment to use installed packages, Getting started
address@hidden Cleaning up and other useful targets
+
+To clean up the build directory and delete any downloaded files, use
+the @code{clean} target:
+
+
address@hidden
+$ make -C gnu/hello clean
address@hidden example
+
+There are other useful targets.  For example, the whole build sequence
+can be broken down into stages as follows:
+
address@hidden
+$ make -C gnu/hello fetch checksum extract configure build install
address@hidden example
+
+Each target depends on the previous one, so typing @code{make -C
+gnu/hello install} builds all the earlier targets first.
+
+To see some information about the package before downloading it, use
+the target @code{fetch-list}.
+
address@hidden
+$ make -C gnu/hello fetch-list
+make: Entering directory `/home/gnu/gsrc/gnu/hello'
+Name: hello
+Version: 2.7
+Location: http://ftpmirror.gnu.org/hello/
+Distribution files: 
+       hello-2.7.tar.gz
+Patch files: 
+Signature files: 
+       hello-2.7.tar.gz.sig
+Dependencies: 
+make: Leaving directory `/home/gnu/gsrc/gnu/hello'
address@hidden example
+
+
address@hidden Building a more complex package,  , Cleaning up and other useful 
targets, Getting started
 @section Building a more complex package
 
 @node Advanced configuration, The build system, Getting started, Top

=== modified file 'doc/version.texi'
--- a/doc/version.texi  2010-12-20 12:29:36 +0000
+++ b/doc/version.texi  2011-08-08 16:46:05 +0000
@@ -1,4 +1,4 @@
address@hidden UPDATED 20 December 2010
address@hidden UPDATED-MONTH December 2010
address@hidden EDITION 0.2
address@hidden VERSION 0.2
address@hidden UPDATED 8 August 2011
address@hidden UPDATED-MONTH August 2011
address@hidden EDITION 0.9
address@hidden VERSION 0.9