\input texinfo   @c -*-texinfo-*-
@comment $Id: texinfo.txi,v 1.204 2007/07/29 14:55:43 karl Exp $
@comment %**start of header
@setfilename gsrc.info
@include version.texi
@settitle GNU Source Release Collection @value{VERSION}
@syncodeindex pg cp
@comment %**end of header
@copying
This manual is for the GNU Source Release Collection (version
@value{VERSION}, updated @value{UPDATED}).

Copyright @copyright{} 2011, 2012 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end quotation
@end copying

@dircategory System administration
@direntry
* gsrc: (gsrc)Building the GNU Source Release Collection.
@end direntry

@titlepage
@title GNU Source Release Collection
@subtitle for version @value{VERSION}, @value{UPDATED}
@author @email{bug-gsrc@@gnu.org}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Introduction, (dir), (dir)
@top GNU Source Release Collection

This manual is for GNU Source Release Collection (version @value{VERSION}, @value{UPDATED}).
@end ifnottex

@menu
* Introduction::                
* Getting started::             
* Advanced configuration::      
* Appendix::
* GNU Free Documentation License::  

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Building GNU packages::

Getting Started

* 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::  

Advanced configuration

* Global configuration::
* Package configuration::
* Maintaining multiple versions of a package::

Appendix

* Configuring Python packages

@end detailmenu
@end menu

@node Introduction, Getting started, Top, Top
@chapter Introduction

The GNU Source Release Collection (GSRC) provides a simple way to
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}.

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
Makefile-based build system, and is written in GNU Make.  The GARNOME
build system for GNOME is another example of a system using GAR.

Note that GSRC is not intended to be a full package management system
or source distribution.  It is just a more convenient way to compile
GNU packages from source on an existing system.

Because GSRC is not a full distribution you will sometimes need to
install other packages from your distribution to build and run GNU
programs.  For example, GSRC itself does not include Perl or Python,
so you will need to make sure these are already installed for GNU
programs which use them.

@c @section Terminology

@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
@c 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
@c 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
@c others that were free software.  The programs developed specifically
@c for the GNU system are referred to as ``GNU software'', or ``GNU
@c packages''.  Thus not every program on the GNU system is GNU software,
@c only those written specifically for it.

@c GSRC is a collection of these GNU packages, the software which is
@c written and maintained as part of the GNU Project.  It does not
@c attempt to include all the other free software in the GNU system,
@c since that is already provided by other groups in different ways.

@menu
* Building GNU packages::
@end menu

@node Building GNU packages, , Introduction, Introduction
@section Building GNU packages

If you have never built a GNU package by hand, this section will
briefly show the process so you will have an idea of what GSRC is
doing.

@itemize @bullet
@item 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
@end example

@item Run the configure script
@example
$ cd hello-2.6; ./configure
@end example

@item Compile the source code
@example
$ make
@end example

@item Install it
@example
$ make install
@end example

@end itemize

@node Getting started, Advanced configuration, Introduction, Top
@chapter Getting started

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 bzr://bzr.savannah.gnu.org/gsrc/trunk/ gsrc
@end example
@noindent
This will create a directory @file{gsrc}.  The build definitions for
GNU packages are in the @code{gnu/} subdirectory.  Each package has
its own subdirectory within @code{gnu/}, for example @code{gnu/emacs/}
or @code{gnu/gcc/}, containing a Makefile for building it.  This
makefile will execute the usual @code{./configure} and @code{make}
commands needed to build a GNU package.

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:

@example
$ bzr update
@end example

@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,

@example
$ ./bootstrap
@end 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:

@example
$ ./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
$
@end 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:

@example
$ make -C gnu/hello
@end example

This will download, unpack, configure and build the @file{hello} package.
The package will be built in the subdirectory @file{gnu/hello/work}.

@example
$ ./gnu/hello/work/hello-2.7/src/hello
Hello, world!
@end example

@node Installing a package, Setting your environment to use installed packages, Building a simple package, Getting started
@section Installing a package

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,

@example
$ mkdir /gnu
@end example

Then to install the package use the @code{install} target,

@example
$ make -C gnu/hello install
@end example

The package should be automatically installed under @file{/gnu/}, with
any executable programs under @code{/gnu/bin/}.

@example
$ /gnu/bin/hello --version
hello (GNU hello) 2.7
@end example


@node 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

If you want to use the newly installed package by default you will
need to modify the relevant variables in your environment, such as
@code{PATH}, @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.

@example
$ source setup.sh
@end example

Note that you need to load this file into the current shell with the
@code{source} 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:

@example
$ echo $PATH
/gnu/bin:/usr/local/bin:/usr/bin:/bin
$ which hello
/gnu/bin/hello
@end 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.

@example
$ PATH=$ORIG_PATH
$ LD_LIBRARY_PATH=$ORIG_LD_LIBRARY_PATH
@end example


@node Cleaning up and other useful targets, Building a more complex package, Setting your environment to use installed packages, Getting started
@section Cleaning up and other useful targets

To clean up the build directory and delete any downloaded files, use
the @code{clean} target:


@example
$ make -C gnu/hello clean
@end example

There are other useful targets.  For example, the whole build sequence
can be broken down into stages as follows:

@example
$ make -C gnu/hello fetch checksum extract configure build install
@end 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}.

@example
$ 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'
@end example


@node Building a more complex package,  , Cleaning up and other useful targets, Getting started
@section Building a more complex package

If a package depends on other packages these will be built
automatically in the correct order.  To see the dependencies of any
package use the @code{dep-list} target.

@example
$ make -C gnu/gnupg dep-list
make: Entering directory `/home/gnu/gsrc/gnu/gnupg'
libgpg-error libgcrypt libassuan libksba pth zlib readline
make: Leaving directory `/home/gnu/gsrc/gnu/gnupg'
@end example

The dependencies are searched for in the @file{gnu/} subdirectory by
default, with some additional external packages such as @code{zlib} in
the @file{deps/} subdirectory.

Note that the dependencies can be more than one level deep,

@example
$ make -C gnu/readline dep-list
make: Entering directory `/home/gnu/gsrc/gnu/readline'
ncurses
make: Leaving directory `/home/gnu/gsrc/gnu/readline'
@end example

So, to install a complex package like @code{gnupg} use the same
commands as for a simple package,

@example
$ make -C gnu/gnupg
$ make -C gnu/gnupg install
@end example


@node Advanced configuration, Appendix, Getting started, Top
@chapter Advanced configuration

The default behavior of GSRC may be configured, both globally and for
individual packages. All configuration is done in simple Makefiles, so
some familiarity with GNU Make, while not required, is recommended for
more advanced changes.

@menu
* Global configuration::
* Package configuration::
* Maintaining multiple versions of a package::
@end menu

@node Global configuration, Package configuration, , Advanced configuration
@section Global configuration

The build loads the following configuration files:

@table @file
@item config.mk
Specifies the installation directory prefix.  Created by the configure
script from @file{config.mk.in}
@item gar.conf.mk
Specifies general configuration variables
@item gar.env.mk
Defines the environment variables that are set during each build step.
@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.
@end table

The local file @file{gar.site.mk} is loaded last and can be used to
override any configuration variables.

Some of the more important configuration variables are:

@table @code
@item BOOTSTRAP
If defined (the default), the environment variables
@code{C_INCLUDE_PATH}, @code{CPLUS_INCLUDE_PATH} and @code{LDFLAGS}
point to the @file{include/} and @file{lib/} subdirectories of the
installation directory.  This forces the use of any previously
installed libraries in preference to the normal system libraries.  To
disable this feature, remove the definition @code{BOOTSTRAP=1} in
@file{config.mk.in} and rerun configure, or build with
@code{BOOTSTRAP} undefined on the command-line:

@example
$ make -C gnu/gnupg BOOTSTRAP= 
@end example

@item IGNORE_DEPS
Specifies any packages that should be skipped as dependencies (for
example, if you prefer to use existing system packages instead).  A
space separated list.


@item GARCHIVEDIR
@item GARBALLDIR
Specifies the directories used to cache downloaded tarballs
(@code{GARCHIVEDIR}) and the tarballs of the installed packages
(@code{GARBALLDIR}).  Set in @file{gar.conf.mk}.

@item MAKE_ARGS_PARALLEL
Set this to @code{-j @var{N}} to allow N parallel processes in the
build.  Note that multiple dependencies are built one-by-one, only the
commands within each build are performed in parallel.

@end table

@node Package configuration, Maintaining multiple versions of a package, Global configuration, Advanced configuration
@section Package configuration

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
options in a GSRC Makefile by setting the CONFIGURE_OPTS variable. Any
options added to this variable will be appended to the options set by
default by GSRC. Thus, since GSRC already sets the @code{--prefix}
option, you need not specify it here.

@example
CONFIGURE_OPTS = --disable-gtk --without-png
@end example

If you have a patch which you would like to apply to the package, the
process may be automated by GSRC. First, in the package's directory,
make a subdirectory called @file{files/} and move the patch file(s)
there. Next, create two variables in the package's Makefile:

@example
PATCHFILES = my-patch.diff my-patch2.diff
PATCHOPTS = -p0
@end example

@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 @code{patch} program. Next, the patch file's checksum
is added to the checksums file for the package. Finally, you may build
the package as normal, with the patch being applied automatically in
the process.

@example
$ make makesums install
@end example

Note that if the @code{make makesums} command fails due to GPG
verification and you trust the source from which the package was
downloaded, you may instead use @code{make makesums GPGV=true} to skip
this key verification step.

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}.

@node Maintaining multiple versions of a package, , Package configuration, Advanced configuration
@section 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
@file{/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
@file{/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
@file{/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,
@file{/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!

@example
$ make -C gnu/hello makesums install GARVERSION=2.7
@end 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:

@example
$ make -C gnu/hello install CONFIGURE_OPTS="--disable-nls" GARPROFILE="-no-nls"
@end example

This would install the newly configured package to
@file{/gnu/packages/hello-2.8-no-nls/}. 

@node Appendix, GNU Free Documentation License, Advanced configuration, Top
@chapter Appendix

@menu
* Configuring Python packages::
@end menu

@node Configuring Python packages, , , Appendix
@section Configuring Python packages

Python packages are typically built using Python's distutils module or
other similar methods. The result is a file called @file{setup.py},
which the user runs, passing it directives similar to those passed to
a standard Makefile. Creating a GSRC Makefile for a Python package is
relatively uncomplicated, however it lacks the power of the
traditional @file{configure}/@file{Makefile} paradigm. Furthermore,
the GNU coding standards require a @file{configure} script when
packaging a software release.

In the interest of standardizing GSRC Makefiles for GNU packages as
well as to provide maintainers of Python-based GNU packages an easy
means of including standards-conforming @file{configure} and
@file{Makefile} files, several files are included in GSRC for
configuring Python projects. These files are located in the
@file{util/python-configure/} directory in the GSRC package.

The files may be included without modification in a Python project's
directory. As such, they will provide a thin wrapper around the project's
@file{setup.py} script. This configure script primarily allows the
user to set the @code{--prefix} flag, as well as to define the
@code{PYTHON} variable declaring the location of the Python
interpreter.

These template files may, however, be greatly expanded and customized
to fit the needs of a given software package. To this end, several
Autoconf macros are included in the @file{m4/python.m4} file. This
file defines Python as a language in Autoconf, meaning that, for
example, you can include arbitrary Python code with
@code{AC_LANG_PROGRAM}. Furthermore, several useful macros are defined:

@multitable @columnfractions .33 .33 .33
@headitem
Macro Name & Arguments
@tab
Description
@tab
Variables exported

@item
@code{AC_PROG_PYTHON([NAME-TO-CHECK])}
@tab
Find a Python interpreter
@tab
@code{PYTHON}

@item
@code{PC_PROG_PYTHON_CONFIG([NAME-TO-CHECK])}
@tab
Find a python-config program
@tab
@code{PYTHON_CONFIG}

@item
@code{PC_PYTHON_VERIFY_VERSION(VERSION, [ACTION-IF-TRUE], [ACTION-IF-NOT-TRUE])}
@tab
Verify that the Python interpreter is of a sufficient version number
@tab

@item
@code{PC_PYTHON_CHECK_VERSION}
@tab
Get the version of the Python interpreter
@tab
@code{PYTHON_VERSION}

@item
@code{PC_PYTHON_CHECK_PREFIX}
@tab
Check what Python thinks is the prefix
@tab
@code{PYTHON_PREFIX}

@item
@code{PC_PYTHON_CHECK_EXEC_PREFIX}
@tab
Check what Python thinks is the exec_prefix
@tab
@code{PYTHON_EXEC_PREFIX}

@item
@code{PC_PYTHON_CHECK_INCLUDES}
@tab
Check the include flags ('-I[header]...') for including the Python
header files
@tab
@code{PYTHON_INCLUDES}

@item
@code{PC_PYTHON_CHECK_HEADERS}
@tab
Check for the Python header files (i.e. @file{Python.h})
@tab
@code{HAVE_PYTHON_H}

@item
@code{PC_PYTHON_CHECK_LIBS}
@tab
Check for the proper LIBS flags to load the Python shared libraries
@tab
@code{PYTHON_LIBS}

@item
@code{PC_PYTHON_TEST_LIBS}
@tab
Test for the presence of the Python shared libraries
@tab
@code{HAVE_LIBPYTHON}

@item
@code{PC_PYTHON_CHECK_CFLAGS}
@tab
Find the CFLAGS that Python expects
@tab
@code{PYTHON_CFLAGS}

@item
@code{PC_PYTHON_CHECK_LDFLAGS}
@tab
Find the LDFLAGS that Python expects
@tab
@code{PYTHON_LDFLAGS}

@item
@code{PC_PYTHON_CHECK_EXTENSION_SUFFIX}
@tab
Check the extension suffix given to Python extension modules (Python 3
only)
@tab
@code{PYTHON_EXTENSION_SUFFIX}

@item
@code{PC_PYTHON_CHECK_ABI_FLAGS}
@tab
Check the ABI flags used by Python (Python 3 only)
@tab
@code{PC_PYTHON_ABI_FLAGS}

@item
@code{PC_PYTHON_CHECK_PLATFORM}
@tab
Check what platform Python thinks this is
@code{PYTHON_PLATFORM}

@item
@code{PC_PYTHON_CHECK_SITE_DIR}
@tab
Check the appropriate place to install Python packages (i.e.
@file{$(prefix)/lib/python2.7/site-packages})
@tab
@code{pythondir}

@item
@code{PC_PYTHON_SITE_PACKAGE_DIR}
@tab
A convenience macro; adds the package's name to @code{pythondir}
@tab
@code{pkgpythondir}

@item
@code{PC_PYTHON_CHECK_EXEC_DIR}
@tab
Check directory for installing Python extension modules
@tab
@code{pyexecdir}

@item
@code{PC_PYTHON_EXEC_PACKAGE_DIR}
@tab
A convenience macro; adds the package's name to @code{pyexecdir}
@tab
@code{pkgpyexecdir}

@item
@code{PC_PYTHON_CHECK_MODULE}
@tab
Test if a given Python module can be successfully loaded
@tab

@item
@code{PC_PYTHON_CHECK_FUNC}
@tab
Test if a given Python function can be called successfully.
@tab
@end multitable

Once these macros are integrated into your @file{configure.ac} file as
necessary, simply run @code{autoconf} to generate a new
@file{configure} script. The variables exported by this
@file{configure} script may then be used in @file{Makefile.in} to
influence the build process. 

To include these scripts in a GSRC Makefile, simply create a .tar.gz
archive including at least @file{configure}, @file{Makefile.in} and
@file{m4/}, such that the contents will extract into a directory called
@code{$(DISTNAME)} (i.e. the contents should extract into a directory
called ``mypackage-0.1/''). Put the archive into the @file{files/}
sub-directory of the package's GSRC directory. Finally, simply add the
archive's name to the @code{DISTFILES} list in the GSRC Makefile for
the package and update the checksums file with @code{make
makesums}. Now your GSRC Makefile can simply include
@file{gar.lib/auto.mk} to automate the configuration and installation
of the software.

@node GNU Free Documentation License,  , Appendix, Top
@appendix GNU Free Documentation License

@include fdl.texi

@bye