[Gsrc-commit] /srv/bzr/gsrc/trunk r2267: add dev info to docs

[Brandon Invergo]

------------------------------------------------------------
revno: 2267
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Sat 2013-04-06 22:43:59 +0200
message:
  add dev info to docs
modified:
  doc/gsrc.texi

=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi     2013-04-03 22:23:54 +0000
+++ b/doc/gsrc.texi     2013-04-06 20:43:59 +0000
@@ -51,7 +51,7 @@
 * Introduction::
 * Getting started::
 * Advanced configuration::
-* GNU Free Documentation License::
+* Appendix::
 @end menu
 
 @c *******************************************************************
@@ -65,11 +65,15 @@
 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.
+At its core, it is a presentation of the current state of the GNU
+system, in the most appropriate form: buildable and installable source
+code. GSRC makes it easy to discover great new software from the GNU
+system, as well as providing other benefits over standard software
+distributions. It allows you, for example, to install easily 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
@@ -355,7 +359,7 @@
 
 @example
 $ make -C gnu/hello pkg-info
-make: Entering directory `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
+make: Entering directory `/home/gnu/gsrc/gnu/hello'
 Name:        GNU Hello
 Version:     2.8
 URL:         http://www.gnu.org/software/hello/manual/
@@ -364,7 +368,7 @@
  serves as an example of standard GNU coding practices.  As such, it
  supports command-line arguments, multiple languages, and so on.
 Status:      installed (stowed)
-make: Leaving directory `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
+make: Leaving directory `/home/gnu/gsrc/gnu/hello'
 @end example
 
 The ``Status'' can  be any of: ``not installed'', ``installed (not
@@ -375,10 +379,10 @@
 
 @example
 $ make -C gnu/hello pkg-info-curt
-make: Entering directory `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
+make: Entering directory `/home/gnu/gsrc/gnu/hello'
 gnu/hello 2.8
  A program that produces a familiar, friendly greeting
-make: Leaving directory `/home/brandon/Projects/gsrc/gsrc/trunk/gnu/hello'
+make: Leaving directory `/home/gnu/gsrc/gnu/hello'
 @end example
 
 To get a better idea of what files will be downloaded and which
@@ -774,8 +778,513 @@
 
 @c *******************************************************************
 
address@hidden GNU Free Documentation License,  , Advanced configuration, Top
address@hidden GNU Free Documentation License
address@hidden Appendix,  , Advanced configuration, Top
address@hidden Appendix
+
address@hidden
+* The GSRC build system::
+* Anatomy of a GSRC Makefile::
+* GNU Free Documentation License::
address@hidden menu
+
address@hidden 
*******************************************************************
address@hidden  The GSRC build system, Anatomy of a GSRC Makefile, Appendix, 
Appendix
address@hidden The GSRC build system
+
+The GSRC build system is based on a system called GARstow by Adam
+Sampson, which, in turn, was based on an earlier system called GAR by
+Nick Moffitt. In this section, the basic architecture of the GSRC
+build system will be described.
+
+GSRC consists of several system Makefiles plus the Makefile for each
+package. When the user calls @command{make} on a package's Makefile,
+the GSRC system Makefiles are pulled in. There are several of these
+system Makefiles:
+
address@hidden @columnfractions .25 .75
address@hidden
+File
address@hidden
+Description
+
address@hidden
address@hidden
address@hidden
+This file contains the top-level targets such as @option{build} or
address@hidden
+
address@hidden
address@hidden
address@hidden
+This file contains recipes to perform the sub-tasks for each top-level
+target (see below).
+
address@hidden
address@hidden
address@hidden
+This file contains master URLs for downloading packages
+(i.e. @url{http://ftp.gnu.org/gnu}).
+
address@hidden
address@hidden
address@hidden
+This directory contains further Makefiles to define common variable
+values for typical build systems, such as the standard GNU Autotools
+process.
+
address@hidden
address@hidden
address@hidden
+This file contains the general configuration of GSRC.
+
address@hidden
address@hidden
address@hidden
+The variables in this file are used to properly set the build
+environment for GSRC.
+
address@hidden
address@hidden
address@hidden
+This file contains the user's particular GSRC configuration.
+
address@hidden multitable
+
+The typical user-level GSRC Make targets, such as @option{fetch},
address@hidden or @option{install}, come from @file{gar.mk}. Depending on
+the package's build requirements, as defined in the package's GSRC
+Makefile, these user-level targets will depend on lower-level targets
+that actually perform the required tasks. 
+
+For example, in a typical GNU package, configuration is done with a
address@hidden script while building and installing are done with a
address@hidden So, for the package @dfn{hello}, the @option{build}
+target will depend on a rule called
address@hidden/hello-2.8/Makefile} (@option{build} plus the
+location of the @file{Makefile} distributed with the package). For a
+Python-based package that is installed via a @file{setup.py}, the
address@hidden target will depend on
address@hidden/somepkg-1.0/setup.py}. The file @file{gar.lib.mk}
+contains many generalized Make recipes to handle each of these
+different scenarios.
+
+The directory @file{gar.lib} contains Makefiles that set common
+variable values for packages that share similar build systems. It has
+a file called @file{auto.mk}, for example, that defines the settings
+for a package that uses the standard Autotools process. 
+
address@hidden 
*******************************************************************
+
address@hidden  Anatomy of a GSRC Makefile, GNU Free Documentation License, The 
GSRC build system, Appendix
address@hidden Anatomy of a GSRC Makefile
+
+GSRC Makefiles are the point of entry for the user into the GSRC
+system. Since GSRC supplies GNU software and there are GNU coding
+standards that dictate how package installation is supposed to work,
+the GSRC Makefiles for most GNU software packages are similar. 
+
+In order to facilitate working with the GSRC Makefiles in an automated
+way, such as searching them via a script, they all share a common
+structure, split into three sections: metadata variables, build
+variables, and the build recipes. By convention, these three sections
+are separated by lines of seventy hash symbols (``#''). This helps to
+visually separate the sections, as well as to provide convenient
+stopping points when scanning or searching the files.
+
address@hidden
+* Metadata variables::
+* Build variables::
+* Build recipes::
+* A simple example::
+* A complex example::
address@hidden menu
+
address@hidden 
*******************************************************************
+
address@hidden  Metadata variables, Build variables, Anatomy of a GSRC 
Makefile, Anatomy of a GSRC Makefile
address@hidden Metadata variables
+
+This section consists of variable declarations that describe the
+package itself. The following variables should be present:
+
address@hidden @columnfractions .25 .75
address@hidden
+Variable name
address@hidden
+Description
+
address@hidden
address@hidden
address@hidden
+This is the common-language, official name of the package. It may
+contain multiple words and any character. Example: ``GNU
+Source-highlight''
+
address@hidden
address@hidden
address@hidden
+This is the internal GSRC name of the package. It should match the
+name of the directory containing the package and, by convention, for
+GNU packages it is the name of the package's HTTP subdirectory on
address@hidden://www.gnu.org/software}. It should consist of only lower
+case letters, numbers, hyphens or underscores. Example:
+``src-highlite''
+
address@hidden
address@hidden
address@hidden
+[optional] If the package maintainers ever use a different name for
+the package, for example a different spelling or capitalization,
+include it here. This is often useful in specifying URLs or package
+arcive names. Example: ``source-highlight''
+
address@hidden
address@hidden
address@hidden
+This is the current version number of the package. Example: ``3.1.7''
+
address@hidden
address@hidden
address@hidden
+[optional] This variable contains the distribution name of the
+package. This variable is automatically constructed and by default it
+is @code{$(GARNAME)-$(GARVERSION)}. Example: ``src-highlite-3.1.7''
+
address@hidden
address@hidden
address@hidden
+This is the home URL of the package, where a user might find more
+information about it. Example:
+``http://www.gnu.org/software/src-highlite''
+
address@hidden
address@hidden
address@hidden
+This variable should have a short, one-line description of the
+package. 
+
address@hidden
address@hidden
address@hidden
+[optional] This should contain a longer, multi-line description of the
+package. To achieve this, its value needs to be declared using the
+Make @code{define} statement.
+
address@hidden multitable
+
address@hidden 
*******************************************************************
+
address@hidden  Build variables, Build recipes, Metadata variables, Anatomy of 
a GSRC Makefile
address@hidden Build variables
+
+The second section of a GSRC Makefile holds variable definitions that
+are used in the build process. When possible, it is preferable to use
+the metadata variables in the build variable definitions, to minimize
+the number of items that need to be modified should anything change.
+
address@hidden @columnfractions .25 .75
address@hidden
+Variable name
address@hidden
+Description
+
address@hidden
address@hidden
address@hidden
+This variable defines the top-level URL from where the package files
+should be retrieved. Many URLs are already defined in variables in the
+file @file{gar.master.mk}. Most GNU packages are retrievable from
address@hidden://ftp.gnu.org/gnu}, which is assigned to the variable
address@hidden in @file{gar.master.mk}, so for a GNU package,
address@hidden would be set to @code{$(MASTER_GNU)}. Multiple
+sites may be listed; attempts to download a files will proceed for
+each site listed until one succeeds.
+
address@hidden
address@hidden
address@hidden
+This is the directory of the master site under which the package
+files can be found. For most GNU packages, this can simply be
address@hidden(GARNAME)}.
+
address@hidden
address@hidden
address@hidden
+This variable contains URL(s) from which source distribution archives 
+only are to be downloaded.
+
address@hidden
address@hidden
address@hidden
+This variable contains the sub-directory of @code{DISTFILE_SITES}
+where the source distributions can be found.
+
address@hidden
address@hidden
address@hidden
+This variable contains URL(s) from which signature files only are to
+be downloaded.
+
address@hidden
address@hidden
address@hidden
+This variable contains the sub-directory of @code{SIGFILE_SITES}
+where the signature files can be found.
+
address@hidden
address@hidden
address@hidden
+This variable contains URL(s) from which patch files only are to be
+downloaded.
+
address@hidden
address@hidden
address@hidden
+This variable contains the sub-directory of @code{DISTFILE_SITES}
+where the source distributions can be found.
+
address@hidden
address@hidden
address@hidden
+This variable lists file URIs where files can be found locally. By
+default this contains the @file{files} sub-directory of the package's
+GSRC directory and the location specified by the variable
address@hidden Note that these URIs should be prefaced with
+``file://''. 
+
address@hidden
address@hidden
address@hidden
+This variable contains a space-separated list of all of the source
+distribution archives to be fetched.
+
address@hidden
address@hidden
address@hidden
+This variable contains a space-separated list of all the signature
+files to fetch.
+
address@hidden
address@hidden
address@hidden
+This variable contains a space-separated list of all the patch
+files to fetch.
+
address@hidden
address@hidden
address@hidden
+This variable contains the name of the directory where all of the work
+should take place. Its default value is @code{$(WORKDIR)/$(DISTNAME)},
+which should be sufficient for most cases, so it is normally not
+necessary to set this variable. If, however, the package's source
+archive extracts to a directory with some other name, you should set
+it here. This should always begin with @code{$(WORKDIR)}, which by
+default is the @file{work} subdirectory of the GSRC package's
+sub-directory. 
+
address@hidden
address@hidden
address@hidden
+This variable defines the location where the build process should take
+place. Normally, and by default, this is the same as @code{WORKSRC},
+however some packages recommend building in a directory separate from
+the location of the source code.
+
address@hidden
address@hidden
address@hidden
+This variable contains a list of the scripts or files that need to be
+run during the configuration step of the build process. Phony targets
+may also be included.
+
address@hidden
address@hidden
address@hidden
+This variable contains a list of the scripts or files that need to be
+run during the build step of the build process. Phony targets
+may also be included.
+
address@hidden
address@hidden
address@hidden
+This variable contains a list of the scripts or files that need to be
+run during the install step of the build process. Phony targets
+may also be included.
+
address@hidden
address@hidden
address@hidden
+This variable contains a space-separated list of the programs required
+to build the package, using their GARNAMEs.
+
address@hidden
address@hidden
address@hidden
+This variable is slightly a misnomer. It is a space-separated list of
+all the programs and/or libraries required at run-time by the package.
address@hidden multitable
+
address@hidden 
*******************************************************************
+
address@hidden  Build recipes, A simple example, Build variables, Anatomy of a 
GSRC Makefile
address@hidden Build recipes
+
+The final section of the GSRC Makefile contains the specifics of
+building the package. For most cases, it is sufficient to just add
address@hidden ../../gar.lib/auto.mk}, which will work for any package
+that follows the GNU building and installation standards. This will,
+among other actions, automatically define the
address@hidden, @code{BUILD_SCRIPTS} and
address@hidden variables and it will include the @file{gar.mk}
+Makefile. If the package does not follow this building standard, then
+add @code{include ../../gar.mk} directly. Following this, the user's
+package configuration should be loaded with @code{include config.mk}.
+
+Because there is the possibility that the user specify some
+configuration options, any further options that must be set within the
+Makefile should be done after the user configuration has been
+loaded. By convention, whereas the user specifies options with the
address@hidden and @code{BUILD_OPTS} variables, inside the
+GSRC Makefile options should be included by @emph{appending} to the
address@hidden and @code{BUILD_ARGS} variables:
+
address@hidden
+CONFIGURE_ARGS += --some-option
address@hidden example
+
+Finally, if necessary, the actual recipes are written. Note that if
address@hidden/auto.mk} was included, no recipes should need to be
+written. In general, there are two kinds of targets for which recipes
+may need to be written. 
+
+The first correspond to the files listed under
address@hidden, @code{BUILD_SCRIPTS} and
address@hidden As mentioned previously, user-level targets,
+such as @option{build}, depend on lower-level targets such as
address@hidden/hello-2.8/Makefile}. These are the targets that
+must be implemented for each of the designated configure/build/install
+scripts. For each target, a recipe is written using the normal Make
+syntax to perform the necessary task. Recall that phony targets may be
+specified as configure/build/install scripts. So, if
address@hidden = java}, then a target named @code{install-java}
+must be written.
+
+The second kind of targets that may be written are pre and post
+rules. These recipes are run before or after the specified top-level
+target. For example, a target called @option{pre-build} is run
+immediately before the @option{build} target. These targets are
+convenient for performing pre- or post-processing on files. Note that
+there are also @option{pre-everything} and @option{post-everything}
+targets that can be written.
+
address@hidden 
*******************************************************************
+
address@hidden  A simple example, A complex example, Build recipes, Anatomy of 
a GSRC Makefile
address@hidden A simple example
+
address@hidden
+NAME = GNU Hello
+GARNAME = hello
+GARVERSION = 2.8
+HOME_URL = http://www.gnu.org/software/hello/manual/
+DESCRIPTION = A program that produces a familiar, friendly greeting
+define BLURB
+ GNU Hello prints the message "Hello, world!" and then exits.  It 
+ serves as an example of standard GNU coding practices.  As such, it
+ supports command-line arguments, multiple languages, and so on.
+endef
+
+######################################################################
+
+MASTER_SITES = $(MASTER_GNU)
+MASTER_SUBDIR = $(GARNAME)/
+DISTFILES = $(DISTNAME).tar.gz
+SIGFILES = $(DISTNAME).tar.gz.sig
+
+BUILDDEPS = 
+LIBDEPS = 
+
+######################################################################
+
+include ../../gar.lib/auto.mk
+include config.mk
address@hidden example
+
address@hidden 
*******************************************************************
+
address@hidden  A complex example,  , A simple example, Anatomy of a GSRC 
Makefile
address@hidden A complex example
+
address@hidden
+NAME = Linux Libre
+GARNAME = linux-libre
+GARVERSION = 3.8.5
+HOME_URL = http://www.fsfla.org/svnwiki/selibre/linux-libre/
+DESCRIPTION = A free version of the Linux kernel
+define BLURB
+ Linux Libre is a free (as in freedom) variant of the Linux kernel. 
+ It has been modified to remove any non-free binary blobs.
+endef
+
+######################################################################
+
+MASTER_SITES = http://linux-libre.fsfla.org/pub/
+MASTER_SUBDIR = $(GARNAME)/releases/$(GARVERSION)-gnu/
+DISTFILES = $(DISTNAME)-gnu.tar.xz
+SIGFILES = $(DISTNAME)-gnu.tar.xz.sign
+
+WORKSRC = $(WORKDIR)/linux-$(GARVERSION)
+CONFIGURE_SCRIPTS = $(WORKSRC)/Makefile
+BUILD_SCRIPTS = $(WORKSRC)/Makefile
+INSTALL_SCRIPTS = kernel
+
+BUILDDEPS = 
+LIBDEPS = 
+
+######################################################################
+
+include ../../gar.mk
+include config.mk
+
+CONFIGURE_ARGS = $(CONFIGURE_OPTS)
+BUILD_ARGS += $(if $(USE_PARALLEL),$(MAKE_ARGS_PARALLEL),)
+
+CREATED_MERGE_DIRS = \
+       sysconf $(sysconfdir) \
+       var $(vardir) \
+       rootlib /lib
+
+pre-configure:
+       make -C $(WORKSRC) mrproper
+       $(MAKECOOKIE)
+
+configure-%/Makefile:
+       $(CONFIGURE_ENV) make -C $* $(MAKE_ARGS) $(CONFIGURE_ARGS) 
$(CONFIGURE_TARGET)
+       $(MAKECOOKIE)
+
+post-configure:
+       cd $(WORKSRC) && make $(MAKE_ARGS) prepare
+       $(MAKECOOKIE)
+
+build-%/Makefile:
+       $(BUILD_ENV) make -C $* $(BUILD_ARGS)
+p      $(MAKECOOKIE)
+
+install-kernel:
+       make -C $(WORKOBJ) $(MAKE_ARGS) \
+               INSTALL_MOD_PATH=$(packageprefix) \
+               INSTALL_HDR_PATH=$(packageprefix) \
+               modules_install \
+               headers_install \
+               firmware_install
+       @@install -m755 -D $(WORKSRC)/arch/$(ARCH)/boot/bzImage 
$(packageprefix)/boot/vmlinuz-$(DISTNAME)
+       @@install -m755 $(WORKSRC)/System.map 
$(packageprefix)/boot/System.map-$(GARVERSION)
+       @@install -m755 $(WORKSRC)/.config 
$(packageprefix)/boot/config-$(GARVERSION)
+       $(MAKECOOKIE)
address@hidden example
+
address@hidden  GNU Free Documentation License,  , Anatomy of a GSRC Makefile, 
Appendix
address@hidden GNU Free Documentation License
 
 @include fdl.texi