[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gsrc-commit] trunk r2795: update documentation
From: |
Brandon Invergo |
Subject: |
[Gsrc-commit] trunk r2795: update documentation |
Date: |
Mon, 06 Jan 2014 21:24:29 +0000 |
User-agent: |
Bazaar (2.6b2) |
------------------------------------------------------------
revno: 2795
revision-id: address@hidden
parent: address@hidden
committer: Brandon Invergo <address@hidden>
branch nick: trunk
timestamp: Mon 2014-01-06 21:24:17 +0000
message:
update documentation
modified:
doc/gsrc.texi gsrc.texi-20100621151235-73qm58fnc905qvlr-1
=== modified file 'doc/gsrc.texi'
--- a/doc/gsrc.texi 2013-11-15 18:56:36 +0000
+++ b/doc/gsrc.texi 2014-01-06 21:24:17 +0000
@@ -10,7 +10,7 @@
This manual is for the GNU Source Release Collection (version
@value{VERSION}, updated @value{UPDATED}).
-Copyright @copyright{} 2011, 2012, 2013 Free Software Foundation, Inc.
+Copyright @copyright{} 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -118,7 +118,7 @@
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
+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.
@@ -161,20 +161,32 @@
@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.
-
address@hidden @bullet
+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. If you
+are already familiar with this, you may skip this section.
+
+The build process is performed via commands entered into a shell, which
+is generally done in a terminal or a terminal emulator. The dollar sign
+in the following examples represents the @dfn{shell prompt}, denoting
+the point at which you enter commands, while the characters following
+the prompt show the commands that you must enter. While much of the
+build process is conveniently automated, such that you do not need to
+manually compile every file, you still must take a few steps.
+
+For example, to build the package ``hello'' version 2.9, you must
+perform the following steps in your terminal:
+
address@hidden
@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
+$ wget http://ftpmirror.gnu.org/gnu/hello/hello-2.9.tar.gz
+$ tar xvfz hello-2.9.tar.gz
@end example
address@hidden Run the configure script
address@hidden Run the @file{configure} script
@example
-$ cd hello-2.6; ./configure
+$ cd hello-2.9
+$ ./configure
@end example
@item Compile the source code
@@ -187,7 +199,12 @@
$ make install
@end example
address@hidden itemize
address@hidden enumerate
+
+In some unfortunate cases, the process is not as straight-forward and
+may require some extra intervention on your part. GSRC abstracts away
+most of these steps so that all you need to enter to install a program
+is @code{make install}.
@node Getting started, Advanced configuration, Introduction, Top
@@ -227,6 +244,9 @@
$ bzr update
@end example
+Alternatively, quarter-annual ``snapshots'' of GSRC are made available
+for download at @url{http://ftpmirror.gnu.org/gnu/gsrc}.
+
@menu
* Initial setup::
* Building a simple package::
@@ -285,11 +305,22 @@
@node Building a simple package, Installing a package, Initial setup, Getting
started
@section Building a simple package
-To build any package, simply type @command{make} in the package's
-subdirectory. You can change to the directory with the @command{cd}
-command in the shell, or with the @option{-C} option of @command{make}.
-For example, to build the @dfn{hello} package in the @file{gnu/hello}
-subdirectory from the root GSRC directory use:
+All interaction with GSRC is performed via the program Make. When you
+execute Make via the @command{make} command, you generally must provide
+a @dfn{target} that tells Make which @dfn{recipe}, consisting of a
+series of pre-defined commands, to execute. For example, the
address@hidden target will tell Make to execute a recipe to build the
+software, while the @option{install} target will execute a recipe for
+installing it. Often, a default recipe will be available that will
+typically build the software, allowing you to omit the @option{build}
+target.
+
+Thus, in GSRC, to build any package, type @command{make build} (or,
+simply @command{make}) in the package's subdirectory. You can change to
+the directory with the @command{cd} command in the shell, or with the
address@hidden option of @command{make}. For example, to build the
address@hidden package in the @file{gnu/hello} subdirectory from the root
+GSRC directory use:
@example
$ make -C gnu/hello
@@ -299,7 +330,7 @@
The package will be built in the subdirectory @file{gnu/hello/work}.
@example
-$ ./gnu/hello/work/hello-2.8/src/hello
+$ ./gnu/hello/work/hello-2.9/src/hello
Hello, world!
@end example
@@ -326,7 +357,7 @@
@example
$ /gnu/bin/hello --version
-hello (GNU hello) 2.8
+hello (GNU hello) 2.9
@end example
@@ -403,7 +434,7 @@
$ make -C gnu/hello pkg-info
make: Entering directory `/home/gnu/gsrc/gnu/hello'
Name: GNU Hello
-Version: 2.8
+Version: 2.9
URL: http://www.gnu.org/software/hello/manual/
Description:
GNU Hello prints the message "Hello, world!" and then exits. It
@@ -422,7 +453,7 @@
@example
$ make -C gnu/hello pkg-info-curt
make: Entering directory `/home/gnu/gsrc/gnu/hello'
-gnu/hello 2.8
+gnu/hello 2.9
A program that produces a familiar, friendly greeting
make: Leaving directory `/home/gnu/gsrc/gnu/hello'
@end example
@@ -435,13 +466,13 @@
$ make -C gnu/hello fetch-list
make: Entering directory `/home/gnu/gsrc/gnu/hello'
Name: hello
-Version: 2.8
+Version: 2.9
Location: http://ftpmirror.gnu.org/hello/
Distribution files:
- hello-2.8.tar.gz
+ hello-2.9.tar.gz
Patch files:
Signature files:
- hello-2.8.tar.gz.sig
+ hello-2.9.tar.gz.sig
Dependencies:
make: Leaving directory `/home/gnu/gsrc/gnu/hello'
@end example
@@ -456,7 +487,7 @@
re-built. Instead, it would merely be re-stowed. To completely remove a
package, use the @option{uninstall-pkg} target. When you update a
package to a new version, the old version is merely un-stowed and the
-new version is installed alongside it @pxref{Package versions}. In
+new version is installed alongside it (@pxref{Package versions}). In
order to clean out old package versions, use the
@option{uninstall-pkg-old} target.
@@ -464,9 +495,9 @@
@node Complex packages, Finding packages, Useful targets, Getting started
@section 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 @option{dep-list} target.
+If building or using a package depends on other GNU packages, these will
+be built automatically in the correct order. To see the dependencies of
+any package use the @option{dep-list} target.
@example
$ make -C gnu/gnupg dep-list
@@ -710,12 +741,12 @@
CONFIGURE_OPTS = --disable-gtk --without-png
@end example
-For convenience, every package has a file called @file{config.mk} in
-its directory which is imported by its build script. Typically, all
-user configuration may be done here. By default, it contains the
+For convenience, every package has a file called @file{config.mk} in its
+directory which is imported by its build script. Typically, all user
+configuration should be done here. By default, it contains the
@code{CONFIGURE_OPTS} and @code{BUILD_OPTS} variables. In some special
-cases, package-specific, user-customize-able variables are also
-defined in this file.
+cases, package-specific, user-customize-able variables are also defined
+in this file.
Generally speaking, user configuration is done exclusively in
@file{config.mk} while @file{Makefile} contains the information and
@@ -770,7 +801,8 @@
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@@gnu.org}.
address@hidden@@gnu.org}. You should also contact the maintainers of
+the software package to make them aware of the problem.
@node Package versions, , Patching packages, Advanced configuration
@@ -782,21 +814,21 @@
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
+<package>-<version> (i.e. @file{/gnu/packages/hello-2.8}). In the
example of the package @dfn{hello}, the executable @file{hello}
-is installed to @file{/gnu/packages/hello-2.7/bin/hello} instead of
+is installed to @file{/gnu/packages/hello-2.8/bin/hello} instead of
@file{/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 ultimately a symlink to
address@hidden/gnu/packages/hello-2.7/bin/hello}. This is referred to as
address@hidden/gnu/packages/hello-2.8/bin/hello}. This is referred to as
@dfn{stowing}; a package with symlinks to its files installed in the
system is said to be @dfn{stowed}.
When a new version of a package is released, you do not have to
-uninstall the previous version first. When @dfn{hello 2.8} is built
+uninstall the previous version first. When @dfn{hello 2.9} is built
and installed, it is put into its own package directory,
address@hidden/gnu/packages/hello-2.8} and the directory of @dfn{hello 2.7}
address@hidden/gnu/packages/hello-2.9} and the directory of @dfn{hello 2.8}
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, while there would then actually be two versions
@@ -807,10 +839,10 @@
update the checksums when you do so, otherwise the process will fail!
@example
-$ make -C gnu/hello makesum install GARVERSION=2.7
+$ make -C gnu/hello makesum install GARVERSION=2.8
@end example
-If you had previously built version 2.7, then GSRC will merely re-stow
+If you had previously built version 2.8, then GSRC will merely re-stow
those files. Of course, if you have not previously built it, or if
you have previously run @command{make clean}, the package will be built
from scratch.
@@ -829,7 +861,7 @@
@end example
This would install the newly configured package to
address@hidden/gnu/packages/hello-2.8-no-nls}.
address@hidden/gnu/packages/hello-2.9-no-nls}.
@node Technical information, GNU Free Documentation License, Advanced
configuration, Top
@@ -916,12 +948,12 @@
For example, in a typical GNU package, configuration is done with a
@file{configure} script while building and installing are done with a
@file{Makefile}. 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
+target will depend on a target called
address@hidden/hello-2.9/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}
address@hidden target will depend on the target
address@hidden/foo-1.0/setup.py}. The file @file{gar.lib.mk}
contains many generalized Make recipes to handle each of these
different scenarios.
@@ -1059,7 +1091,7 @@
@tab
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(GARNAME)/}.
@item
@code{DISTFILE_SITES}
@@ -1166,6 +1198,15 @@
may also be included.
@item
address@hidden
address@hidden
+This variable contains a list of all of the Info documentation files
+installed by a program. To use this variable, you must include the
address@hidden file from the @file{gar.lib} directory. If this variable
+is not defined and @file{info.mk} is included, then it will have a
+default value of @code{$(GARNAME).info}
+
address@hidden
@code{BUILDDEPS}
@tab
This variable contains a space-separated list of the programs required
@@ -1214,7 +1255,7 @@
@code{CONFIGURE_SCRIPTS}, @code{BUILD_SCRIPTS} and
@code{INSTALL_SCRIPTS}. 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
address@hidden/hello-2.9/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
@@ -1222,7 +1263,7 @@
@code{INSTALL_SCRIPTS = java}, then a target named @code{install-java}
must be written.
-The second kind of targets that may be written are pre and post
+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
@@ -1237,7 +1278,7 @@
@example
NAME = GNU Hello
GARNAME = hello
-GARVERSION = 2.8
+GARVERSION = 2.9
HOME_URL = http://www.gnu.org/software/hello/manual/
DESCRIPTION = A program that produces a familiar, friendly greeting
define BLURB
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Gsrc-commit] trunk r2795: update documentation,
Brandon Invergo <=