[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gsrc-commit] /srv/bzr/gsrc/trunk r1357: update documentation for new GA
|
From: |
Brandon Invergo |
|
Subject: |
[Gsrc-commit] /srv/bzr/gsrc/trunk r1357: update documentation for new GAR features |
|
Date: |
Sat, 08 Dec 2012 17:24:49 +0100 |
|
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 1357
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Sat 2012-12-08 17:24:49 +0100
message:
update documentation for new GAR features
added:
doc/gsrc.info
modified:
ChangeLog
doc/gsrc.texi
doc/version.texi
=== modified file 'ChangeLog'
--- a/ChangeLog 2012-12-07 22:29:26 +0000
+++ b/ChangeLog 2012-12-08 16:24:49 +0000
@@ -1,3 +1,13 @@
+2012-12-08 Brandon Invergo <address@hidden>
+
+ * doc/gsrc.texi (Package configuration): add info about package
+ config.mk files
+ (Global configuration): add info about USE_COLOR and
+ REDIRECT_OUTPUT
+ (Useful targets): add info about the `pkg-info' target
+ (Getting started): mention other subdirs (i.e. `gnome/')
+ (Top): reorganize and shorten chapter/section titles
+
2012-12-07 Brandon Invergo <address@hidden>
* gar.conf.mk (REDIRECT_OUTPUT): add option to redirect build
=== added file 'doc/gsrc.info'
--- a/doc/gsrc.info 1970-01-01 00:00:00 +0000
+++ b/doc/gsrc.info 2012-12-08 16:24:49 +0000
@@ -0,0 +1,1052 @@
+This is gsrc.info, produced by makeinfo version 4.13 from gsrc.texi.
+
+This manual is for the GNU Source Release Collection (version
+2012.09.06, updated 8 December 2012).
+
+ Copyright (C) 2011, 2012 Free Software Foundation, Inc.
+
+ 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."
+
+INFO-DIR-SECTION System administration
+START-INFO-DIR-ENTRY
+* gsrc: (gsrc)Building the GNU Source Release Collection.
+END-INFO-DIR-ENTRY
+
+
+File: gsrc.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
+
+GNU Source Release Collection
+*****************************
+
+This manual is for GNU Source Release Collection (version 2012.09.06,
+8 December 2012).
+
+* Menu:
+
+* Introduction::
+* Getting started::
+* Advanced configuration::
+* GNU Free Documentation License::
+
+
+File: gsrc.info, Node: Introduction, Next: Getting started, Prev: Top, Up:
Top
+
+1 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 `ftp.gnu.org' are automatically
+downloaded, compiled and installed, either in your home directory or a
+system-wide directory such as `/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 was 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.
+
+* Menu:
+
+* Building GNU packages::
+
+
+File: gsrc.info, Node: Building GNU packages, Prev: Introduction, Up:
Introduction
+
+1.1 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.
+
+ * Download the package and unpack it
+ $ wget http://ftpmirror.gnu.org/gnu/hello/hello-2.6.tar.gz
+ $ tar xvfz hello-2.6.tar.gz
+
+ * Run the configure script
+ $ cd hello-2.6; ./configure
+
+ * Compile the source code
+ $ make
+
+ * Install it
+ $ make install
+
+
+
+File: gsrc.info, Node: Getting started, Next: Advanced configuration, Prev:
Introduction, Up: Top
+
+2 Getting started
+*****************
+
+GSRC is distributed directly using the Bazaar version control system or
+via a a compressed archive. You can check out the latest version from
+the Bazaar repository using
+
+ $ bzr checkout bzr://bzr.savannah.gnu.org/gsrc/trunk/ gsrc
+
+This will create a directory `gsrc'. The build definitions for GNU
+packages are in the `gnu/' subdirectory. Large sub-projects, such as
+GNOME, have their own subdirectory containing packages (i.e. `gnome/').
+Each package has its own subdirectory within its parent, for example
+`gnu/emacs/' or `gnome/evince/', containing a `config.mk' file for
+configuring the package and a `Makefile' for building it. This
+`Makefile' will execute the usual `./configure' and `make' commands
+needed to build a GNU package.
+
+ The `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:
+
+ $ bzr update
+
+* Menu:
+
+* Initial setup::
+* Building a simple package::
+* Installing a package::
+* Setting your environment::
+* Useful targets::
+* Complex packages::
+
+
+File: gsrc.info, Node: Initial setup, Next: Building a simple package,
Prev: Getting started, Up: Getting started
+
+2.1 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,
+
+ $ ./bootstrap
+
+ 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 `--prefix'. For example, to
+install all the compiled packages under `/gnu' use:
+
+ $ ./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
+ $
+
+
+File: gsrc.info, Node: Building a simple package, Next: Installing a
package, Prev: Initial setup, Up: Getting started
+
+2.2 Building a simple package
+=============================
+
+To build any package, simply type `make' in the package's subdirectory.
+You can change to the directory with the `cd' command in the shell, or
+with the `-C' option of `make'. For example, to build the `hello'
+package in the `gnu/hello' subdirectory use:
+
+ $ make -C gnu/hello
+
+ This will download, unpack, configure and build the `hello' package.
+The package will be built in the subdirectory `gnu/hello/work'.
+
+ $ ./gnu/hello/work/hello-2.7/src/hello
+ Hello, world!
+
+
+File: gsrc.info, Node: Installing a package, Next: Setting your environment,
Prev: Building a simple package, Up: Getting started
+
+2.3 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 `--prefix' option if necessary,
+
+ $ mkdir /gnu
+
+ Then to install the package use the `install' target,
+
+ $ make -C gnu/hello install
+
+ The package should be automatically installed under `/gnu/', with
+any executable programs under `/gnu/bin/'.
+
+ $ /gnu/bin/hello --version
+ hello (GNU hello) 2.7
+
+
+File: gsrc.info, Node: Setting your environment, Next: Useful targets,
Prev: Installing a package, Up: Getting started
+
+2.4 Setting your environment
+============================
+
+If you want to use the newly installed package by default you will need
+to modify the relevant variables in your environment, such as `PATH',
+`LD_LIBRARY_PATH', `INFOPATH', etc.
+
+ There is a sample script `setup.sh' in the top-level source
+directory which can be used to set the main environment variables.
+
+ $ source setup.sh
+
+ Note that you need to load this file into the current shell with the
+`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:
+
+ $ echo $PATH
+ /gnu/bin:/usr/local/bin:/usr/bin:/bin
+ $ which hello
+ /gnu/bin/hello
+
+ If you want to restore your original environment variables they are
+saved in the variables `ORIG_PATH', `ORIG_LD_LIBRARY_PATH', etc.
+
+ $ PATH=$ORIG_PATH
+ $ LD_LIBRARY_PATH=$ORIG_LD_LIBRARY_PATH
+
+
+File: gsrc.info, Node: Useful targets, Next: Complex packages, Prev:
Setting your environment, Up: Getting started
+
+2.5 Useful targets
+==================
+
+To clean up the build directory and delete any downloaded files, use
+the `clean' target:
+
+ $ make -C gnu/hello clean
+
+ There are other useful targets. For example, the whole build
+sequence can be broken down into stages as follows:
+
+ $ make -C gnu/hello fetch checksum extract configure build install
+
+ Each target depends on the previous one, so typing `make -C
+gnu/hello install' builds all the earlier targets first.
+
+ To see some information about a package, use the target `pkg-info'.
+
+ $ make -C gnu/hello pkg-info
+ make: Entering directory
`/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
+ Name: hello
+ Version: 2.8
+ Description: A program that produces a familiar, friendly greeting
+ URL: http://www.gnu.org/software/hello/manual/
+ make: Leaving directory
+ `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
+
+ To get a better idea of what files will be downloaded and which
+dependencies must be built in order to use a package, use the
+`fetch-list' target.
+
+ $ make -C gnu/hello fetch-list
+ make: Entering directory `/home/gnu/gsrc/gnu/hello'
+ Name: hello
+ Version: 2.8
+ Location: http://ftpmirror.gnu.org/hello/
+ Distribution files:
+ hello-2.8.tar.gz
+ Patch files:
+ Signature files:
+ hello-2.8.tar.gz.sig
+ Dependencies:
+ make: Leaving directory `/home/gnu/gsrc/gnu/hello'
+
+ Most GNU packages are highly configurable. To see which configuration
+options are available to you, you may invoke the `help' target.
+
+
+File: gsrc.info, Node: Complex packages, Prev: Useful targets, Up: Getting
started
+
+2.6 Complex packages
+====================
+
+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 `dep-list' target.
+
+ $ 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'
+
+ The dependencies are searched for in the `gnu/' subdirectory by
+default, with some additional external packages such as `zlib' in the
+`deps/' subdirectory.
+
+ Note that the dependencies can be more than one level deep,
+
+ $ make -C gnu/readline dep-list
+ make: Entering directory `/home/gnu/gsrc/gnu/readline'
+ ncurses
+ make: Leaving directory `/home/gnu/gsrc/gnu/readline'
+
+ So, to install a complex package like `gnupg' use the same commands
+as for a simple package,
+
+ $ make -C gnu/gnupg
+ $ make -C gnu/gnupg install
+
+
+File: gsrc.info, Node: Advanced configuration, Next: GNU Free Documentation
License, Prev: Getting started, Up: Top
+
+3 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::
+* Patching packages::
+* Package versions::
+
+
+File: gsrc.info, Node: Global configuration, Next: Package configuration,
Prev: Advanced configuration, Up: Advanced configuration
+
+3.1 Global configuration
+========================
+
+The build loads the following configuration files:
+
+`config.mk'
+ Specifies the installation directory prefix. Created by the
+ configure script from `config.mk.in'
+
+`gar.conf.mk'
+ Specifies general configuration variables
+
+`gar.env.mk'
+ Defines the environment variables that are set during each build
+ step.
+
+`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.
+
+ The local file `gar.site.mk' is loaded last and can be used to
+override any configuration variables.
+
+ Some of the more important configuration variables are:
+
+`BOOTSTRAP'
+ If defined (the default), the environment variables
+ `C_INCLUDE_PATH', `CPLUS_INCLUDE_PATH' and `LDFLAGS' point to the
+ `include/' and `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 `BOOTSTRAP=1' in
+ `config.mk.in' and rerun configure, or build with `BOOTSTRAP'
+ undefined on the command-line:
+
+ $ make -C gnu/gnupg BOOTSTRAP=
+
+ Set in `conf.mk'
+
+`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. Set in `gar.conf.mk'.
+
+`GARCHIVEDIR'
+
+`GARBALLDIR'
+ Specifies the directories used to cache downloaded source code
+ archives (`GARCHIVEDIR') and the archives of the installed
+ packages (`GARBALLDIR'). Set in `gar.conf.mk'.
+
+`MAKE_ARGS_PARALLEL'
+ Set this to `-j 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. Set in
+ `gar.conf.mk'
+
+`USE_COLOR'
+ It's easy to miss the messages printed by GSRC amongst all the
+ output of the build process. Set this to "y" to enable colorized
+ output of GSRC messages, which may make them more visible. Set it
+ to anything else to disable color. In either case, four more
+ variables are defined: `MSG', `ERR', `OK' and `OFF'. The first
+ three define strings to insert at the beginning of a normal
+ message, an error message, or a message indicating success,
+ respectively. The `OFF' code is inserted at the end of the
+ message. When `USE_COLOR' is "y", these variables contain ANSI
+ escape sequences to change properties of the text (i.e. to set
+ colors or text weight). Otherwise, they may contain textual
+ indicators, such as "==> " to begin a message. Some sensible
+ default values for both cases are included. Set in `gar.conf.mk'.
+
+`REDIRECT_OUTPUT'
+ A typical build process produces a lot of textual output. In some
+ cases, you may wish to redirect this output to somewhere other than
+ your screen. In this case, you may set the variable
+ `REDIRECT_OUTPUT' to any value other than "n". To edit where the
+ output will be redirected, set the OUTPUT variable. By default, if
+ you set `REDIRECT_OUTPUT', standard text output will be redirected
+ to `/dev/null', which means it is thrown away, while errors will
+ be printed to the screen. You can instead, for example, redirect
+ to log files of your choosing (*note Redirections:
+ (bash)Redirections. for more details on redirection). Set in
+ `gar.conf.mk'
+
+
+
+File: gsrc.info, Node: Package configuration, Next: Patching packages,
Prev: Global configuration, Up: Advanced configuration
+
+3.2 Package configuration
+=========================
+
+Each package can be customized to your liking. Because GNU packages
+follow a standardized build process, customizing the GSRC build for one
+is straightforward.
+
+ GNU packages take most of their configuration in the form of options
+passed to the `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.
+
+ CONFIGURE_OPTS = --disable-gtk --without-png
+
+ For convenience, every package has a file called `config.mk' in its
+directory which is imported by the `Makefile'. Typically, all user
+configuration may be done here. By default, it contains the
+`CONFIGURE_OPTS' and `BUILD_OPTS' variables. In some special cases,
+package-specific, user-customize-able variables are also defined in
+this file.
+
+ Generally speaking, user configuration may take place exclusively in
+`config.mk' while `Makefile' contains the recipe to make sure the
+package builds correctly. Thus, you should not need to modify the
+`Makefile' unless you have special requirements. Note that, because
+they are necessary for proper building and installation in GSRC, most
+configuration options relating to directory locations (such as where to
+install, where to search for libraries, etc.) are set in the
+`Makefile'. Thus, you do not need to worry about setting them correctly
+in `config.mk'.
+
+
+File: gsrc.info, Node: Patching packages, Next: Package versions, Prev:
Package configuration, Up: Advanced configuration
+
+3.3 Patching packages
+=====================
+
+If you have a patch that you would like to apply to the package, the
+process can be automated by GSRC. First, in the package's directory,
+make a subdirectory called `files/' and move the patch file(s) there.
+Next, create two variables in the package's `Makefile':
+
+ PATCHFILES = my-patch.diff my-patch2.diff
+ PATCHOPTS = -p0
+
+ `PATCHFILES' holds a list of all the patch files in the `files/'
+subdirectory. `PATCHOPTS' contains the option switches nto pass to the
+`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. The patch(es) will be applied automatically in the process.
+
+ $ make makesum install
+
+ Note that if the `make makesums' command fails due to GPG
+verification and you trust the source from which the package was
+downloaded, you may instead use `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 <address@hidden>.
+
+
+File: gsrc.info, Node: Package versions, Prev: Patching packages, Up:
Advanced configuration
+
+3.4 Package versions
+====================
+
+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
+`/gnu/packages/' directory in a sub-directory with the name
+<package>-<version> (i.e. `/gnu/packages/hello-2.7/'). In the example
+of the package `hello', the executable `hello' is installed to
+`/gnu/packages/hello-2.7/bin/hello' instead of `/gnu/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 `/gnu/'
+directory. Thus, `/gnu/bin/hello' is ultimately a symlink to
+`/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 `hello 2.8' is built and
+installed, it is put into its own package directory,
+`/gnu/packages/hello-2.8/' and the directory of `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's files. 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 switch to a particular version of the package, you may
+pass the `GARVERSION' variable to `make install'. Be sure to update the
+checksums when you do so, otherwise the process will fail!
+
+ $ make -C gnu/hello makesum install GARVERSION=2.7
+
+ If you had previously built version 2.7, then GSRC will merely
+re-symlink to those files. Of course, if you have not previously built
+it, or if you have previously run `make clean', the package will be
+build from scratch.
+
+ Note: this method may 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 `DISTFILES'.
+
+ Users wishing to maintain different configurations of a package may
+take advantage of the `GARPROFILE' variable. Its value is merely
+appended to the package directory name, allowing you to have multiple
+configurations of the same package version installed. For example:
+
+ $ make -C gnu/hello install CONFIGURE_OPTS="--disable-nls"
GARPROFILE="-no-nls"
+
+ This would install the newly configured package to
+`/gnu/packages/hello-2.8-no-nls/'.
+
+
+File: gsrc.info, Node: GNU Free Documentation License, Prev: Advanced
configuration, Up: Top
+
+Appendix A GNU Free Documentation License
+*****************************************
+
+ Version 1.3, 3 November 2008
+
+ Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+ `http://fsf.org/'
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ 0. PREAMBLE
+
+ The purpose of this License is to make a manual, textbook, or other
+ functional and useful document "free" in the sense of freedom: to
+ assure everyone the effective freedom to copy and redistribute it,
+ with or without modifying it, either commercially or
+ noncommercially. Secondarily, this License preserves for the
+ author and publisher a way to get credit for their work, while not
+ being considered responsible for modifications made by others.
+
+ This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense.
+ It complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same freedoms
+ that the software does. But this License is not limited to
+ software manuals; it can be used for any textual work, regardless
+ of subject matter or whether it is published as a printed book.
+ We recommend this License principally for works whose purpose is
+ instruction or reference.
+
+ 1. APPLICABILITY AND DEFINITIONS
+
+ This License applies to any manual or other work, in any medium,
+ that contains a notice placed by the copyright holder saying it
+ can be distributed under the terms of this License. Such a notice
+ grants a world-wide, royalty-free license, unlimited in duration,
+ to use that work under the conditions stated herein. The
+ "Document", below, refers to any such manual or work. Any member
+ of the public is a licensee, and is addressed as "you". You
+ accept the license if you copy, modify or distribute the work in a
+ way requiring permission under copyright law.
+
+ A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+
+ A "Secondary Section" is a named appendix or a front-matter section
+ of the Document that deals exclusively with the relationship of the
+ publishers or authors of the Document to the Document's overall
+ subject (or to related matters) and contains nothing that could
+ fall directly within that overall subject. (Thus, if the Document
+ is in part a textbook of mathematics, a Secondary Section may not
+ explain any mathematics.) The relationship could be a matter of
+ historical connection with the subject or with related matters, or
+ of legal, commercial, philosophical, ethical or political position
+ regarding them.
+
+ The "Invariant Sections" are certain Secondary Sections whose
+ titles are designated, as being those of Invariant Sections, in
+ the notice that says that the Document is released under this
+ License. If a section does not fit the above definition of
+ Secondary then it is not allowed to be designated as Invariant.
+ The Document may contain zero Invariant Sections. If the Document
+ does not identify any Invariant Sections then there are none.
+
+ The "Cover Texts" are certain short passages of text that are
+ listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+ that says that the Document is released under this License. A
+ Front-Cover Text may be at most 5 words, and a Back-Cover Text may
+ be at most 25 words.
+
+ A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, that is suitable for revising the document
+ straightforwardly with generic text editors or (for images
+ composed of pixels) generic paint programs or (for drawings) some
+ widely available drawing editor, and that is suitable for input to
+ text formatters or for automatic translation to a variety of
+ formats suitable for input to text formatters. A copy made in an
+ otherwise Transparent file format whose markup, or absence of
+ markup, has been arranged to thwart or discourage subsequent
+ modification by readers is not Transparent. An image format is
+ not Transparent if used for any substantial amount of text. A
+ copy that is not "Transparent" is called "Opaque".
+
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format,
+ SGML or XML using a publicly available DTD, and
+ standard-conforming simple HTML, PostScript or PDF designed for
+ human modification. Examples of transparent image formats include
+ PNG, XCF and JPG. Opaque formats include proprietary formats that
+ can be read and edited only by proprietary word processors, SGML or
+ XML for which the DTD and/or processing tools are not generally
+ available, and the machine-generated HTML, PostScript or PDF
+ produced by some word processors for output purposes only.
+
+ The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the
+ material this License requires to appear in the title page. For
+ works in formats which do not have any title page as such, "Title
+ Page" means the text near the most prominent appearance of the
+ work's title, preceding the beginning of the body of the text.
+
+ The "publisher" means any person or entity that distributes copies
+ of the Document to the public.
+
+ A section "Entitled XYZ" means a named subunit of the Document
+ whose title either is precisely XYZ or contains XYZ in parentheses
+ following text that translates XYZ in another language. (Here XYZ
+ stands for a specific section name mentioned below, such as
+ "Acknowledgements", "Dedications", "Endorsements", or "History".)
+ To "Preserve the Title" of such a section when you modify the
+ Document means that it remains a section "Entitled XYZ" according
+ to this definition.
+
+ The Document may include Warranty Disclaimers next to the notice
+ which states that this License applies to the Document. These
+ Warranty Disclaimers are considered to be included by reference in
+ this License, but only as regards disclaiming warranties: any other
+ implication that these Warranty Disclaimers may have is void and
+ has no effect on the meaning of this License.
+
+ 2. VERBATIM COPYING
+
+ You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License
+ applies to the Document are reproduced in all copies, and that you
+ add no other conditions whatsoever to those of this License. You
+ may not use technical measures to obstruct or control the reading
+ or further copying of the copies you make or distribute. However,
+ you may accept compensation in exchange for copies. If you
+ distribute a large enough number of copies you must also follow
+ the conditions in section 3.
+
+ You may also lend copies, under the same conditions stated above,
+ and you may publicly display copies.
+
+ 3. COPYING IN QUANTITY
+
+ If you publish printed copies (or copies in media that commonly
+ have printed covers) of the Document, numbering more than 100, and
+ the Document's license notice requires Cover Texts, you must
+ enclose the copies in covers that carry, clearly and legibly, all
+ these Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also clearly
+ and legibly identify you as the publisher of these copies. The
+ front cover must present the full title with all words of the
+ title equally prominent and visible. You may add other material
+ on the covers in addition. Copying with changes limited to the
+ covers, as long as they preserve the title of the Document and
+ satisfy these conditions, can be treated as verbatim copying in
+ other respects.
+
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto
+ adjacent pages.
+
+ If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a
+ machine-readable Transparent copy along with each Opaque copy, or
+ state in or with each Opaque copy a computer-network location from
+ which the general network-using public has access to download
+ using public-standard network protocols a complete Transparent
+ copy of the Document, free of added material. If you use the
+ latter option, you must take reasonably prudent steps, when you
+ begin distribution of Opaque copies in quantity, to ensure that
+ this Transparent copy will remain thus accessible at the stated
+ location until at least one year after the last time you
+ distribute an Opaque copy (directly or through your agents or
+ retailers) of that edition to the public.
+
+ It is requested, but not required, that you contact the authors of
+ the Document well before redistributing any large number of
+ copies, to give them a chance to provide you with an updated
+ version of the Document.
+
+ 4. MODIFICATIONS
+
+ You may copy and distribute a Modified Version of the Document
+ under the conditions of sections 2 and 3 above, provided that you
+ release the Modified Version under precisely this License, with
+ the Modified Version filling the role of the Document, thus
+ licensing distribution and modification of the Modified Version to
+ whoever possesses a copy of it. In addition, you must do these
+ things in the Modified Version:
+
+ A. Use in the Title Page (and on the covers, if any) a title
+ distinct from that of the Document, and from those of
+ previous versions (which should, if there were any, be listed
+ in the History section of the Document). You may use the
+ same title as a previous version if the original publisher of
+ that version gives permission.
+
+ B. List on the Title Page, as authors, one or more persons or
+ entities responsible for authorship of the modifications in
+ the Modified Version, together with at least five of the
+ principal authors of the Document (all of its principal
+ authors, if it has fewer than five), unless they release you
+ from this requirement.
+
+ C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+ D. Preserve all the copyright notices of the Document.
+
+ E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+ F. Include, immediately after the copyright notices, a license
+ notice giving the public permission to use the Modified
+ Version under the terms of this License, in the form shown in
+ the Addendum below.
+
+ G. Preserve in that license notice the full lists of Invariant
+ Sections and required Cover Texts given in the Document's
+ license notice.
+
+ H. Include an unaltered copy of this License.
+
+ I. Preserve the section Entitled "History", Preserve its Title,
+ and add to it an item stating at least the title, year, new
+ authors, and publisher of the Modified Version as given on
+ the Title Page. If there is no section Entitled "History" in
+ the Document, create one stating the title, year, authors,
+ and publisher of the Document as given on its Title Page,
+ then add an item describing the Modified Version as stated in
+ the previous sentence.
+
+ J. Preserve the network location, if any, given in the Document
+ for public access to a Transparent copy of the Document, and
+ likewise the network locations given in the Document for
+ previous versions it was based on. These may be placed in
+ the "History" section. You may omit a network location for a
+ work that was published at least four years before the
+ Document itself, or if the original publisher of the version
+ it refers to gives permission.
+
+ K. For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the
+ section all the substance and tone of each of the contributor
+ acknowledgements and/or dedications given therein.
+
+ L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section
+ titles.
+
+ M. Delete any section Entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+ N. Do not retitle any existing section to be Entitled
+ "Endorsements" or to conflict in title with any Invariant
+ Section.
+
+ O. Preserve any Warranty Disclaimers.
+
+ If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no
+ material copied from the Document, you may at your option
+ designate some or all of these sections as invariant. To do this,
+ add their titles to the list of Invariant Sections in the Modified
+ Version's license notice. These titles must be distinct from any
+ other section titles.
+
+ You may add a section Entitled "Endorsements", provided it contains
+ nothing but endorsements of your Modified Version by various
+ parties--for example, statements of peer review or that the text
+ has been approved by an organization as the authoritative
+ definition of a standard.
+
+ You may add a passage of up to five words as a Front-Cover Text,
+ and a passage of up to 25 words as a Back-Cover Text, to the end
+ of the list of Cover Texts in the Modified Version. Only one
+ passage of Front-Cover Text and one of Back-Cover Text may be
+ added by (or through arrangements made by) any one entity. If the
+ Document already includes a cover text for the same cover,
+ previously added by you or by arrangement made by the same entity
+ you are acting on behalf of, you may not add another; but you may
+ replace the old one, on explicit permission from the previous
+ publisher that added the old one.
+
+ The author(s) and publisher(s) of the Document do not by this
+ License give permission to use their names for publicity for or to
+ assert or imply endorsement of any Modified Version.
+
+ 5. COMBINING DOCUMENTS
+
+ You may combine the Document with other documents released under
+ this License, under the terms defined in section 4 above for
+ modified versions, provided that you include in the combination
+ all of the Invariant Sections of all of the original documents,
+ unmodified, and list them all as Invariant Sections of your
+ combined work in its license notice, and that you preserve all
+ their Warranty Disclaimers.
+
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name
+ but different contents, make the title of each such section unique
+ by adding at the end of it, in parentheses, the name of the
+ original author or publisher of that section if known, or else a
+ unique number. Make the same adjustment to the section titles in
+ the list of Invariant Sections in the license notice of the
+ combined work.
+
+ In the combination, you must combine any sections Entitled
+ "History" in the various original documents, forming one section
+ Entitled "History"; likewise combine any sections Entitled
+ "Acknowledgements", and any sections Entitled "Dedications". You
+ must delete all sections Entitled "Endorsements."
+
+ 6. COLLECTIONS OF DOCUMENTS
+
+ You may make a collection consisting of the Document and other
+ documents released under this License, and replace the individual
+ copies of this License in the various documents with a single copy
+ that is included in the collection, provided that you follow the
+ rules of this License for verbatim copying of each of the
+ documents in all other respects.
+
+ You may extract a single document from such a collection, and
+ distribute it individually under this License, provided you insert
+ a copy of this License into the extracted document, and follow
+ this License in all other respects regarding verbatim copying of
+ that document.
+
+ 7. AGGREGATION WITH INDEPENDENT WORKS
+
+ A compilation of the Document or its derivatives with other
+ separate and independent documents or works, in or on a volume of
+ a storage or distribution medium, is called an "aggregate" if the
+ copyright resulting from the compilation is not used to limit the
+ legal rights of the compilation's users beyond what the individual
+ works permit. When the Document is included in an aggregate, this
+ License does not apply to the other works in the aggregate which
+ are not themselves derivative works of the Document.
+
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one half
+ of the entire aggregate, the Document's Cover Texts may be placed
+ on covers that bracket the Document within the aggregate, or the
+ electronic equivalent of covers if the Document is in electronic
+ form. Otherwise they must appear on printed covers that bracket
+ the whole aggregate.
+
+ 8. TRANSLATION
+
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section
+ 4. Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License, and all the license notices in the
+ Document, and any Warranty Disclaimers, provided that you also
+ include the original English version of this License and the
+ original versions of those notices and disclaimers. In case of a
+ disagreement between the translation and the original version of
+ this License or a notice or disclaimer, the original version will
+ prevail.
+
+ If a section in the Document is Entitled "Acknowledgements",
+ "Dedications", or "History", the requirement (section 4) to
+ Preserve its Title (section 1) will typically require changing the
+ actual title.
+
+ 9. TERMINATION
+
+ You may not copy, modify, sublicense, or distribute the Document
+ except as expressly provided under this License. Any attempt
+ otherwise to copy, modify, sublicense, or distribute it is void,
+ and will automatically terminate your rights under this License.
+
+ However, if you cease all violation of this License, then your
+ license from a particular copyright holder is reinstated (a)
+ provisionally, unless and until the copyright holder explicitly
+ and finally terminates your license, and (b) permanently, if the
+ copyright holder fails to notify you of the violation by some
+ reasonable means prior to 60 days after the cessation.
+
+ Moreover, your license from a particular copyright holder is
+ reinstated permanently if the copyright holder notifies you of the
+ violation by some reasonable means, this is the first time you have
+ received notice of violation of this License (for any work) from
+ that copyright holder, and you cure the violation prior to 30 days
+ after your receipt of the notice.
+
+ Termination of your rights under this section does not terminate
+ the licenses of parties who have received copies or rights from
+ you under this License. If your rights have been terminated and
+ not permanently reinstated, receipt of a copy of some or all of
+ the same material does not give you any rights to use it.
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+ The Free Software Foundation may publish new, revised versions of
+ the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ `http://www.gnu.org/copyleft/'.
+
+ Each version of the License is given a distinguishing version
+ number. If the Document specifies that a particular numbered
+ version of this License "or any later version" applies to it, you
+ have the option of following the terms and conditions either of
+ that specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If
+ the Document does not specify a version number of this License,
+ you may choose any version ever published (not as a draft) by the
+ Free Software Foundation. If the Document specifies that a proxy
+ can decide which future versions of this License can be used, that
+ proxy's public statement of acceptance of a version permanently
+ authorizes you to choose that version for the Document.
+
+ 11. RELICENSING
+
+ "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
+ World Wide Web server that publishes copyrightable works and also
+ provides prominent facilities for anybody to edit those works. A
+ public wiki that anybody can edit is an example of such a server.
+ A "Massive Multiauthor Collaboration" (or "MMC") contained in the
+ site means any set of copyrightable works thus published on the MMC
+ site.
+
+ "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
+ license published by Creative Commons Corporation, a not-for-profit
+ corporation with a principal place of business in San Francisco,
+ California, as well as future copyleft versions of that license
+ published by that same organization.
+
+ "Incorporate" means to publish or republish a Document, in whole or
+ in part, as part of another Document.
+
+ An MMC is "eligible for relicensing" if it is licensed under this
+ License, and if all works that were first published under this
+ License somewhere other than this MMC, and subsequently
+ incorporated in whole or in part into the MMC, (1) had no cover
+ texts or invariant sections, and (2) were thus incorporated prior
+ to November 1, 2008.
+
+ The operator of an MMC Site may republish an MMC contained in the
+ site under CC-BY-SA on the same site at any time before August 1,
+ 2009, provided the MMC is eligible for relicensing.
+
+
+ADDENDUM: How to use this License for your documents
+====================================================
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+ Copyright (C) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3
+ 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''.
+
+ If you have Invariant Sections, Front-Cover Texts and Back-Cover
+Texts, replace the "with...Texts." line with this:
+
+ with the Invariant Sections being LIST THEIR TITLES, with
+ the Front-Cover Texts being LIST, and with the Back-Cover Texts
+ being LIST.
+
+ If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+ If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License, to
+permit their use in free software.
+
+
+
+Tag Table:
+Node: Top768
+Node: Introduction1105
+Node: Building GNU packages2633
+Node: Getting started3221
+Node: Initial setup4481
+Node: Building a simple package5574
+Node: Installing a package6244
+Node: Setting your environment6903
+Node: Useful targets8046
+Node: Complex packages9728
+Node: Advanced configuration10785
+Node: Global configuration11299
+Node: Package configuration14973
+Node: Patching packages16577
+Node: Package versions17823
+Node: GNU Free Documentation License20330
+
+End Tag Table
=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi 2012-12-06 23:56:09 +0000
+++ b/doc/gsrc.texi 2012-12-08 16:24:49 +0000
@@ -38,6 +38,8 @@
@contents
address@hidden
*******************************************************************
+
@ifnottex
@node Top, Introduction, (dir), (dir)
@top GNU Source Release Collection
@@ -46,36 +48,14 @@
@end ifnottex
@menu
-* Introduction::
-* Getting started::
-* Advanced configuration::
-* Appendix::
-* GNU Free Documentation License::
-
address@hidden
- --- 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::
-
address@hidden detailmenu
+* Introduction::
+* Getting started::
+* Advanced configuration::
+* GNU Free Documentation License::
@end menu
address@hidden
*******************************************************************
+
@node Introduction, Getting started, Top, Top
@chapter Introduction
@@ -94,7 +74,7 @@
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.
+build system for GNOME was 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
@@ -135,7 +115,9 @@
* Building GNU packages::
@end menu
address@hidden Building GNU packages, , Introduction, Introduction
address@hidden
*******************************************************************
+
address@hidden Building GNU packages, , Introduction, Introduction
@section Building GNU packages
If you have never built a GNU package by hand, this section will
@@ -166,26 +148,32 @@
@end itemize
address@hidden
*******************************************************************
+
@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
+or via a a compressed archive. 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.
+GNU packages are in the @code{gnu/} subdirectory. Large sub-projects,
+such as GNOME, have their own subdirectory containing packages
+(i.e. @code{gnome/}). Each package has its own subdirectory within
+its parent, for example @code{gnu/emacs/} or @code{gnome/evince/},
+containing a @file{config.mk} file for configuring the package and a
address@hidden for building it. This @file{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,
+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:
@@ -194,6 +182,18 @@
$ bzr update
@end example
address@hidden
+* Initial setup::
+* Building a simple package::
+* Installing a package::
+* Setting your environment::
+* Useful targets::
+* Complex packages::
address@hidden menu
+
address@hidden
*******************************************************************
+
address@hidden Initial setup, Building a simple package, Getting started,
Getting started
@section Initial setup
If you have checked out the source tree from the Bazaar repository you
@@ -224,16 +224,9 @@
$
@end example
-
address@hidden
-* 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 menu
-
address@hidden Building a simple package, Installing a package, Getting
started, Getting started
address@hidden
*******************************************************************
+
address@hidden Building a simple package, Installing a package, Initial setup,
Getting started
@section Building a simple package
To build any package, simply type @code{make} in the package's
@@ -254,7 +247,9 @@
Hello, world!
@end example
address@hidden Installing a package, Setting your environment to use installed
packages, Building a simple package, Getting started
address@hidden
*******************************************************************
+
address@hidden Installing a package, Setting your environment, Building a
simple package, Getting started
@section Installing a package
You are now ready to install the package. If you are installing to a
@@ -279,9 +274,10 @@
hello (GNU hello) 2.7
@end example
address@hidden
*******************************************************************
address@hidden Setting your environment to use installed packages, Cleaning up
and other useful targets, Installing a package, Getting started
address@hidden Setting your environment to use installed packages
address@hidden Setting your environment, Useful targets, Installing a package,
Getting started
address@hidden Setting your environment
If you want to use the newly installed package by default you will
need to modify the relevant variables in your environment, such as
@@ -317,14 +313,14 @@
$ LD_LIBRARY_PATH=$ORIG_LD_LIBRARY_PATH
@end example
address@hidden
*******************************************************************
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
address@hidden Useful targets, Complex packages, Setting your environment,
Getting started
address@hidden 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
@@ -339,27 +335,45 @@
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}.
+To see some information about a package, use the target @code{pkg-info}.
+
address@hidden
+$ make -C gnu/hello pkg-info
+make: Entering directory `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
+Name: hello
+Version: 2.8
+Description: A program that produces a familiar, friendly greeting
+URL: http://www.gnu.org/software/hello/manual/
+make: Leaving directory
+`/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
address@hidden example
+
+To get a better idea of what files will be downloaded and which
+dependencies must be built in order to use a package, use the
address@hidden target.
@example
$ make -C gnu/hello fetch-list
make: Entering directory `/home/gnu/gsrc/gnu/hello'
Name: hello
-Version: 2.7
+Version: 2.8
Location: http://ftpmirror.gnu.org/hello/
Distribution files:
- hello-2.7.tar.gz
+ hello-2.8.tar.gz
Patch files:
Signature files:
- hello-2.7.tar.gz.sig
+ hello-2.8.tar.gz.sig
Dependencies:
make: Leaving directory `/home/gnu/gsrc/gnu/hello'
@end example
-
address@hidden Building a more complex package, , Cleaning up and other useful
targets, Getting started
address@hidden Building a more complex package
+Most GNU packages are highly configurable. To see which configuration
+options are available to you, you may invoke the @code{help} target.
+
address@hidden
*******************************************************************
+
address@hidden Complex packages, , Useful targets, Getting started
address@hidden Complex packages
If a package depends on other packages these will be built
automatically in the correct order. To see the dependencies of any
@@ -393,6 +407,7 @@
$ make -C gnu/gnupg install
@end example
address@hidden
*******************************************************************
@node Advanced configuration, GNU Free Documentation License, Getting started,
Top
@chapter Advanced configuration
@@ -405,10 +420,13 @@
@menu
* Global configuration::
* Package configuration::
-* Maintaining multiple versions of a package::
+* Patching packages::
+* Package versions::
@end menu
address@hidden Global configuration, Package configuration, , Advanced
configuration
address@hidden
*******************************************************************
+
address@hidden Global configuration, Package configuration, Advanced
configuration, Advanced configuration
@section Global configuration
The build loads the following configuration files:
@@ -446,47 +464,98 @@
$ make -C gnu/gnupg BOOTSTRAP=
@end example
+Set in @file{conf.mk}
+
@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.
-
+space separated list. Set in @file{gar.conf.mk}.
@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}.
+Specifies the directories used to cache downloaded source code
+archives (@code{GARCHIVEDIR}) and the archives 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.
+commands within each build are performed in parallel. Set in
address@hidden
+
address@hidden USE_COLOR
+It's easy to miss the messages printed by GSRC amongst all the output
+of the build process. Set this to ``y'' to enable colorized output of
+GSRC messages, which may make them more visible. Set it to anything
+else to disable color. In either case, four more variables are
+defined: @code{MSG}, @code{ERR}, @code{OK} and @code{OFF}. The first
+three define strings to insert at the beginning of a normal message,
+an error message, or a message indicating success, respectively. The
address@hidden code is inserted at the end of the message. When
address@hidden is ``y'', these variables contain ANSI escape
+sequences to change properties of the text (i.e. to set colors or text
+weight). Otherwise, they may contain textual indicators, such as
+``==> '' to begin a message. Some sensible default values for both
+cases are included. Set in @file{gar.conf.mk}.
+
address@hidden REDIRECT_OUTPUT
+A typical build process produces a lot of textual output. In some
+cases, you may wish to redirect this output to somewhere other than
+your screen. In this case, you may set the variable
address@hidden to any value other than ``n''. To edit where
+the output will be redirected, set the OUTPUT variable. By default, if
+you set @code{REDIRECT_OUTPUT}, standard text output will be
+redirected to @file{/dev/null}, which means it is thrown away, while
+errors will be printed to the screen. You can instead, for example,
+redirect to log files of your choosing (@pxref{Redirections, , ,bash,
+Bash} for more details on
+redirection). Set in @file{gar.conf.mk}
@end table
address@hidden Package configuration, Maintaining multiple versions of a
package, Global configuration, Advanced configuration
address@hidden
*******************************************************************
+
address@hidden Package configuration, Patching packages, 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.
+Each package can be customized to your liking. Because GNU packages
+follow a standardized build process, customizing the GSRC build 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.
+default by GSRC.
@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,
+For convenience, every package has a file called @file{config.mk} in
+its directory which is imported by the @file{Makefile}. Typically, all
+user configuration may be done here. By default, it contains the
address@hidden and @code{BUILD_OPTS} variables. In some special
+cases, package-specific, user-customize-able variables are also
+defined in this file.
+
+Generally speaking, user configuration may take place exclusively in
address@hidden while @file{Makefile} contains the recipe to make
+sure the package builds correctly. Thus, you should not need to modify
+the @file{Makefile} unless you have special requirements. Note that,
+because they are necessary for proper building and installation in
+GSRC, most configuration options relating to directory locations (such
+as where to install, where to search for libraries, etc.) are set in
+the @file{Makefile}. Thus, you do not need to worry about setting them
+correctly in @file{config.mk}.
+
address@hidden Patching packages, Package versions, Package configuration,
Advanced configuration
address@hidden Patching packages
+
+If you have a patch that you would like to apply to the package, the
+process can 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:
+there. Next, create two variables in the package's @file{Makefile}:
@example
PATCHFILES = my-patch.diff my-patch2.diff
@@ -495,13 +564,13 @@
@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
+nto 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 package as normal. The patch(es) will be applied automatically in
the process.
@example
-$ make makesums install
+$ make makesum install
@end example
Note that if the @code{make makesums} command fails due to GPG
@@ -510,10 +579,13 @@
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}.
-
address@hidden Maintaining multiple versions of a package, , Package
configuration, Advanced configuration
address@hidden Maintaining multiple versions of a package
+bug in GSRC. Please report such build problems to
address@hidden@@gnu.org}.
+
address@hidden
*******************************************************************
+
address@hidden Package versions, , Patching packages, Advanced configuration
address@hidden Package versions
What is actually happening ``under the hood'' when GSRC installs a
package is slightly more complicated than what has been described so
@@ -522,12 +594,12 @@
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
address@hidden/gnu/packages/hello-2.7/bin/hello}. All other files installed by
+example of the package @code{hello}, the executable @file{hello}
+is installed to @file{/gnu/packages/hello-2.7/bin/hello} instead of
address@hidden/gnu/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
+directory. Thus, @file{/gnu/bin/hello} is ultimately 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
@@ -536,28 +608,28 @@
@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
+version's files. 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
+If you want to switch to 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
+$ make -C gnu/hello makesum install GARVERSION=2.7
@end example
-If you had previously built version 2.7, then GSRC will merely re-link
+If you had previously built version 2.7, then GSRC will merely re-symlink
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.
+you have previously run @code{make clean}, the package will be build
+from scratch.
-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}.
+Note: this method may 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
+take advantage of the @code{GARPROFILE} variable. Its value is merely
appended to the package directory name, allowing you to have multiple
configurations of the same package version installed. For example:
@@ -568,6 +640,8 @@
This would install the newly configured package to
@file{/gnu/packages/hello-2.8-no-nls/}.
address@hidden
*******************************************************************
+
@node GNU Free Documentation License, , Advanced configuration, Top
@appendix GNU Free Documentation License
=== modified file 'doc/version.texi'
--- a/doc/version.texi 2012-12-07 19:20:30 +0000
+++ b/doc/version.texi 2012-12-08 16:24:49 +0000
@@ -1,4 +1,4 @@
address@hidden UPDATED 7 December 2012
address@hidden UPDATED 8 December 2012
@set UPDATED-MONTH December 2012
@set EDITION 2012.09.06
@set VERSION 2012.09.06
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Gsrc-commit] /srv/bzr/gsrc/trunk r1357: update documentation for new GAR features,
Brandon Invergo <=