remove autobackup file
diff --git a/doc/python-configure.texi~ b/doc/python-configure.texi~ deleted file mode 100644 --- a/doc/python-configure.texi~ +++ /dev/null @@ -1,794 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment $Id: texinfo.txi,v 1.204 2007/07/29 14:55:43 karl Exp $ -@comment %**start of header -@setfilename gsrc.info -@include version.texi -@settitle GNU Source Release Collection @value{VERSION} -@syncodeindex pg cp -@comment %**end of header -@copying -This manual is for the GNU Source Release Collection (version -@value{VERSION}, updated @value{UPDATED}). - -Copyright @copyright{} 2011, 2012 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or -any later version published by the Free Software Foundation; with no -Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A -copy of the license is included in the section entitled ``GNU Free -Documentation License.'' -@end quotation -@end copying - -@dircategory System administration -@direntry -* gsrc: (gsrc)Building the GNU Source Release Collection. -@end direntry - -@titlepage -@title GNU Source Release Collection -@subtitle for version @value{VERSION}, @value{UPDATED} -@author @email{bug-gsrc@@gnu.org} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top GNU Source Release Collection - -This manual is for GNU Source Release Collection (version @value{VERSION}, @value{UPDATED}). -@end ifnottex - -@menu -* Introduction:: -* Getting started:: -* Advanced configuration:: -* Appendix:: -* GNU Free Documentation License:: - -@detailmenu - --- The Detailed Node Listing --- - -Introduction - -* Building GNU packages:: - -Getting Started - -* Building a simple package:: -* Installing a package:: -* Setting your environment to use installed packages:: -* Cleaning up and other useful targets:: -* Building a more complex package:: - -Advanced configuration - -* Global configuration:: -* Package configuration:: -* Maintaining multiple versions of a package:: - -Appendix - -* Configuring Python packages - -@end detailmenu -@end menu - -@node Introduction, Getting started, Top, Top -@chapter Introduction - -The GNU Source Release Collection (GSRC) provides a simple way to -install the latest GNU packages on an existing distribution. By using -GSRC, the GNU source packages from @code{ftp.gnu.org} are -automatically downloaded, compiled and installed, either in your home -directory or a system-wide directory such as @code{/opt}. - -It allows you, for example, to easily install GNU software for -yourself on a system on which you do not have permission to install -software system-wide; or to install the latest, unpatched packages -when those distributed with your operating system are outdated or not -configured to your liking. - -GSRC is based on the GAR build system by Nick Moffitt and the GARstow -enhancements by Adam Sampson. GAR was inspired by BSD Ports, a -Makefile-based build system, and is written in GNU Make. The GARNOME -build system for GNOME is another example of a system using GAR. - -Note that GSRC is not intended to be a full package management system -or source distribution. It is just a more convenient way to compile -GNU packages from source on an existing system. - -Because GSRC is not a full distribution you will sometimes need to -install other packages from your distribution to build and run GNU -programs. For example, GSRC itself does not include Perl or Python, -so you will need to make sure these are already installed for GNU -programs which use them. - -@c @section Terminology - -@c This document uses the term ``GNU package'' to refer to software -@c written as part of the GNU Project. The meaning of the term ``GNU -@c package'' is best made clear by understanding its origin.x - -@c In the early 1980's Richard Stallman wrote a manifesto calling for the -@c creation of a computer operating system where all programs could be -@c freely modified and shared by anyone---a system that would be entirely -@c ``free software''. He gave this system the name ``GNU'' and started -@c an initiative with others to develop it (this initiative was known as -@c the ``GNU Project''). - -@c The design of the GNU system specified many new programs that needed -@c to be written, but also included some existing programs developed by -@c others that were free software. The programs developed specifically -@c for the GNU system are referred to as ``GNU software'', or ``GNU -@c packages''. Thus not every program on the GNU system is GNU software, -@c only those written specifically for it. - -@c GSRC is a collection of these GNU packages, the software which is -@c written and maintained as part of the GNU Project. It does not -@c attempt to include all the other free software in the GNU system, -@c since that is already provided by other groups in different ways. - -@menu -* Building GNU packages:: -@end menu - -@node Building GNU packages, , Introduction, Introduction -@section Building GNU packages - -If you have never built a GNU package by hand, this section will -briefly show the process so you will have an idea of what GSRC is -doing. - -@itemize @bullet -@item Download the package and unpack it -@example -$ wget http://ftpmirror.gnu.org/gnu/hello/hello-2.6.tar.gz -$ tar xvfz hello-2.6.tar.gz -@end example - -@item Run the configure script -@example -$ cd hello-2.6; ./configure -@end example - -@item Compile the source code -@example -$ make -@end example - -@item Install it -@example -$ make install -@end example - -@end itemize - -@node Getting started, Advanced configuration, Introduction, Top -@chapter Getting started - -GSRC is distributed directly using the Bazaar version control system -or via a tarball. You can check out the latest version from the -Bazaar repository using - -@example -$ bzr checkout bzr://bzr.savannah.gnu.org/gsrc/trunk/ gsrc -@end example -@noindent -This will create a directory @file{gsrc}. The build definitions for -GNU packages are in the @code{gnu/} subdirectory. Each package has -its own subdirectory within @code{gnu/}, for example @code{gnu/emacs/} -or @code{gnu/gcc/}, containing a Makefile for building it. This -makefile will execute the usual @code{./configure} and @code{make} -commands needed to build a GNU package. - -The @code{deps/} -subdirectory contains GARfiles for a few external packages, - -To stay up-to-date with the latest releases of GNU software, you can -pull in recent changes to your local copy of GSRC: - -@example -$ bzr update -@end example - -@section Initial setup - -If you have checked out the source tree from the Bazaar repository you -will need to create the build files with the following command, - -@example -$ ./bootstrap -@end example - -Before building any packages you will need to run the top-level -configure script. There is only one configuration parameter, the -installation prefix, specified with @option{--prefix}. For example, -to install all the compiled packages under @file{/gnu} use: - -@example -$ ./configure --prefix=/gnu -checking for a BSD-compatible install... /usr/bin/install -c -checking whether build environment is sane... yes -checking for a thread-safe mkdir -p... /bin/mkdir -p -checking for gawk... no -checking for mawk... mawk -checking whether make sets $(MAKE)... yes -configure: creating ./config.status -config.status: creating config.mk -config.status: creating setup.sh -config.status: creating GNUmakefile -config.status: creating doc/Makefile -$ -@end example - - -@menu -* Building a simple package:: -* Installing a package:: -* Setting your environment to use installed packages:: -* Cleaning up and other useful targets:: -* Building a more complex package:: -@end menu - -@node Building a simple package, Installing a package, Getting started, Getting started -@section Building a simple package - -To build any package, simply type @code{make} in the package's -subdirectory. You can change to the directory with the @code{cd} -command in the shell, or with the @option{-C} option of @code{make}. -For example, to build the @file{hello} package in the @file{gnu/hello} -subdirectory use: - -@example -$ make -C gnu/hello -@end example - -This will download, unpack, configure and build the @file{hello} package. -The package will be built in the subdirectory @file{gnu/hello/work}. - -@example -$ ./gnu/hello/work/hello-2.7/src/hello -Hello, world! -@end example - -@node Installing a package, Setting your environment to use installed packages, Building a simple package, Getting started -@section Installing a package - -You are now ready to install the package. If you are installing to a -new directory tree, first create the directory specified in the -top-level configure @option{--prefix} option if necessary, - -@example -$ mkdir /gnu -@end example - -Then to install the package use the @code{install} target, - -@example -$ make -C gnu/hello install -@end example - -The package should be automatically installed under @file{/gnu/}, with -any executable programs under @code{/gnu/bin/}. - -@example -$ /gnu/bin/hello --version -hello (GNU hello) 2.7 -@end example - - -@node Setting your environment to use installed packages, Cleaning up and other useful targets, Installing a package, Getting started -@section Setting your environment to use installed packages - -If you want to use the newly installed package by default you will -need to modify the relevant variables in your environment, such as -@code{PATH}, @code{LD_LIBRARY_PATH}, @code{INFOPATH}, etc. - -There is a sample script @file{setup.sh} in the top-level source -directory which can be used to set the main environment variables. - -@example -$ source setup.sh -@end example - -Note that you need to load this file into the current shell with the -@code{source} command, instead of executing it (which would only apply -the definitions temporarily in a subshell). - -After loading this file, your environment variables should include the -target directory so you can run the new packages directly: - -@example -$ echo $PATH -/gnu/bin:/usr/local/bin:/usr/bin:/bin -$ which hello -/gnu/bin/hello -@end example - -If you want to restore your original environment variables they are -saved in the variables @code{ORIG_PATH}, @code{ORIG_LD_LIBRARY_PATH}, -etc. - -@example -$ PATH=$ORIG_PATH -$ LD_LIBRARY_PATH=$ORIG_LD_LIBRARY_PATH -@end example - - -@node Cleaning up and other useful targets, Building a more complex package, Setting your environment to use installed packages, Getting started -@section Cleaning up and other useful targets - -To clean up the build directory and delete any downloaded files, use -the @code{clean} target: - - -@example -$ make -C gnu/hello clean -@end example - -There are other useful targets. For example, the whole build sequence -can be broken down into stages as follows: - -@example -$ make -C gnu/hello fetch checksum extract configure build install -@end example - -Each target depends on the previous one, so typing @code{make -C -gnu/hello install} builds all the earlier targets first. - -To see some information about the package before downloading it, use -the target @code{fetch-list}. - -@example -$ make -C gnu/hello fetch-list -make: Entering directory `/home/gnu/gsrc/gnu/hello' -Name: hello -Version: 2.7 -Location: http://ftpmirror.gnu.org/hello/ -Distribution files: - hello-2.7.tar.gz -Patch files: -Signature files: - hello-2.7.tar.gz.sig -Dependencies: -make: Leaving directory `/home/gnu/gsrc/gnu/hello' -@end example - - -@node Building a more complex package, , Cleaning up and other useful targets, Getting started -@section Building a more complex package - -If a package depends on other packages these will be built -automatically in the correct order. To see the dependencies of any -package use the @code{dep-list} target. - -@example -$ make -C gnu/gnupg dep-list -make: Entering directory `/home/gnu/gsrc/gnu/gnupg' -libgpg-error libgcrypt libassuan libksba pth zlib readline -make: Leaving directory `/home/gnu/gsrc/gnu/gnupg' -@end example - -The dependencies are searched for in the @file{gnu/} subdirectory by -default, with some additional external packages such as @code{zlib} in -the @file{deps/} subdirectory. - -Note that the dependencies can be more than one level deep, - -@example -$ make -C gnu/readline dep-list -make: Entering directory `/home/gnu/gsrc/gnu/readline' -ncurses -make: Leaving directory `/home/gnu/gsrc/gnu/readline' -@end example - -So, to install a complex package like @code{gnupg} use the same -commands as for a simple package, - -@example -$ make -C gnu/gnupg -$ make -C gnu/gnupg install -@end example - - -@node Advanced configuration, Appendix, Getting started, Top -@chapter Advanced configuration - -The default behavior of GSRC may be configured, both globally and for -individual packages. All configuration is done in simple Makefiles, so -some familiarity with GNU Make, while not required, is recommended for -more advanced changes. - -@menu -* Global configuration:: -* Package configuration:: -* Maintaining multiple versions of a package:: -@end menu - -@node Global configuration, Package configuration, , Advanced configuration -@section Global configuration - -The build loads the following configuration files: - -@table @file -@item config.mk -Specifies the installation directory prefix. Created by the configure -script from @file{config.mk.in} -@item gar.conf.mk -Specifies general configuration variables -@item gar.env.mk -Defines the environment variables that are set during each build step. -@item gar.master.mk -Defines the list of mirror sites used to download the source -tarballs. It is recommended to modify this to use local mirrors. -@end table - -The local file @file{gar.site.mk} is loaded last and can be used to -override any configuration variables. - -Some of the more important configuration variables are: - -@table @code -@item BOOTSTRAP -If defined (the default), the environment variables -@code{C_INCLUDE_PATH}, @code{CPLUS_INCLUDE_PATH} and @code{LDFLAGS} -point to the @file{include/} and @file{lib/} subdirectories of the -installation directory. This forces the use of any previously -installed libraries in preference to the normal system libraries. To -disable this feature, remove the definition @code{BOOTSTRAP=1} in -@file{config.mk.in} and rerun configure, or build with -@code{BOOTSTRAP} undefined on the command-line: - -@example -$ make -C gnu/gnupg BOOTSTRAP= -@end example - -@item IGNORE_DEPS -Specifies any packages that should be skipped as dependencies (for -example, if you prefer to use existing system packages instead). A -space separated list. - - -@item GARCHIVEDIR -@item GARBALLDIR -Specifies the directories used to cache downloaded tarballs -(@code{GARCHIVEDIR}) and the tarballs of the installed packages -(@code{GARBALLDIR}). Set in @file{gar.conf.mk}. - -@item MAKE_ARGS_PARALLEL -Set this to @code{-j @var{N}} to allow N parallel processes in the -build. Note that multiple dependencies are built one-by-one, only the -commands within each build are performed in parallel. - -@end table - -@node Package configuration, Maintaining multiple versions of a package, Global configuration, Advanced configuration -@section Package configuration - -Each package can be highly customized within its own Makefile. Because -GNU packages follow a standardized build process, customizing the GSRC -Makefile for one is straightforward. - -GNU packages take most of their configuration in the form of options -passed to the @file{configure} script. One may easily customize these -options in a GSRC Makefile by setting the CONFIGURE_OPTS variable. Any -options added to this variable will be appended to the options set by -default by GSRC. Thus, since GSRC already sets the @code{--prefix} -option, you need not specify it here. - -@example -CONFIGURE_OPTS = --disable-gtk --without-png -@end example - -If you have a patch which you would like to apply to the package, the -process may be automated by GSRC. First, in the package's directory, -make a subdirectory called @file{files/} and move the patch file(s) -there. Next, create two variables in the package's Makefile: - -@example -PATCHFILES = my-patch.diff my-patch2.diff -PATCHOPTS = -p0 -@end example - -@code{PATCHFILES} holds a list of all the patch files in the -@file{files/} subdirectory. @code{PATCHOPTS} contains the option switches -to pass to the @code{patch} program. Next, the patch file's checksum -is added to the checksums file for the package. Finally, you may build -the package as normal, with the patch being applied automatically in -the process. - -@example -$ make makesums install -@end example - -Note that if the @code{make makesums} command fails due to GPG -verification and you trust the source from which the package was -downloaded, you may instead use @code{make makesums GPGV=true} to skip -this key verification step. - -If the package requires a patch to even build properly, then this is a -bug in GSRC. Please report such build problems to @email{bug-gsrc@@gnu.org}. - -@node Maintaining multiple versions of a package, , Package configuration, Advanced configuration -@section Maintaining multiple versions of a package - -What is actually happening ``under the hood'' when GSRC installs a -package is slightly more complicated than what has been described so -far. - -When you install a package, it is first actually installed to the -@file{/gnu/packages/} directory in a sub-directory with the name -<package>-<version> (i.e. @file{/gnu/packages/hello-2.7/}). In the -example of the package @code{hello}, when the executable @file{hello} -is installed, it is installed to -@file{/gnu/packages/hello-2.7/bin/hello}. All other files installed by -the package are installed in a similar manner. Next, GSRC makes -symbolic links to those files inside the parent @file{/gnu/} -directory. Thus, @file{/gnu/bin/hello} is actually a symlink to -@file{/gnu/packages/hello-2.7/bin/hello}. - -When a new version of a package is released, you do not have to -uninstall the previous version first. When @code{hello 2.8} is built -and installed, it is put into its own package directory, -@file{/gnu/packages/hello-2.8/} and the directory of @code{hello 2.7} -is left untouched. When GSRC finalizes the installation, the old -symlinks are removed and new ones are created to the latest -version. Thus, there would then actually be two versions of the -package installed, but only one would be in use via the symlinks. - -If you want to use a particular version of the package, you may -pass the @code{GARVERSION} variable to @code{make install}. Be sure to -update the checksums when you do so, otherwise the process will fail! - -@example -$ make -C gnu/hello makesums install GARVERSION=2.7 -@end example - -If you had previously built version 2.7, then GSRC will merely re-link -to those files. Of course, if you have not previously built it, or if -you have run @code{make clean}, the process will start from the -beginning. - -Note: this will fail if the package naming format or compression -algorithm has changed between versions (i.e. a change from tar.gz to -tar.xz); in this case you must also modify @code{DISTFILES}. - -Users wishing to maintain different configurations of a package may -take advantage of the @code{GARPROFILE} variable. Its value is -appended to the package directory name, allowing you to have multiple -configurations of the same package version installed. For example: - -@example -$ make -C gnu/hello install CONFIGURE_OPTS="--disable-nls" GARPROFILE="-no-nls" -@end example - -This would install the newly configured package to -@file{/gnu/packages/hello-2.8-no-nls/}. - -@node Appendix, GNU Free Documentation License, Advanced configuration, Top -@chapter Appendix - -@menu -* Configuring Python packages:: -@end menu - -@node Configuring Python packages, , , Appendix -@section Configuring Python packages - -Python packages are typically built using Python's distutils module or -other similar methods. The result is a file called @file{setup.py}, -which the user runs, passing it directives similar to those passed to -a standard Makefile. Creating a GSRC Makefile for a Python package is -relatively uncomplicated, however it lacks the power of the -traditional @file{configure}/@file{Makefile} paradigm. Furthermore, -the GNU coding standards require a @file{configure} script when -packaging a software release. - -In the interest of standardizing GSRC Makefiles for GNU packages as -well as to provide maintainers of Python-based GNU packages an easy -means of including standards-conforming @file{configure} and -@file{Makefile} files, several files are included in GSRC for -configuring Python projects. These files are located in the -@file{util/python-configure/} directory in the GSRC package. - -The files may be included without modification in a Python project's -directory. As such, they will provide a thin wrapper around the project's -@file{setup.py} script. This configure script primarily allows the -user to set the @code{--prefix} flag, as well as to define the -@code{PYTHON} variable declaring the location of the Python -interpreter. - -These template files may, however, be greatly expanded and customized -to fit the needs of a given software package. To this end, several -Autoconf macros are included in the @file{m4/python.m4} file. This -file defines Python as a language in Autoconf, meaning that, for -example, you can include arbitrary Python code with -@code{AC_LANG_PROGRAM}. Furthermore, several useful macros are defined: - -@multitable @columnfractions .33 .33 .33 -@headitem -Macro Name & Arguments -@tab -Description -@tab -Variables exported - -@item -@code{AC_PROG_PYTHON([NAME-TO-CHECK])} -@tab -Find a Python interpreter -@tab -@code{PYTHON} - -@item -@code{PC_PROG_PYTHON_CONFIG([NAME-TO-CHECK])} -@tab -Find a python-config program -@tab -@code{PYTHON_CONFIG} - -@item -@code{PC_PYTHON_VERIFY_VERSION(VERSION, [ACTION-IF-TRUE], [ACTION-IF-NOT-TRUE])} -@tab -Verify that the Python interpreter is of a sufficient version number -@tab - -@item -@code{PC_PYTHON_CHECK_VERSION} -@tab -Get the version of the Python interpreter -@tab -@code{PYTHON_VERSION} - -@item -@code{PC_PYTHON_CHECK_PREFIX} -@tab -Check what Python thinks is the prefix -@tab -@code{PYTHON_PREFIX} - -@item -@code{PC_PYTHON_CHECK_EXEC_PREFIX} -@tab -Check what Python thinks is the exec_prefix -@tab -@code{PYTHON_EXEC_PREFIX} - -@item -@code{PC_PYTHON_CHECK_INCLUDES} -@tab -Check the include flags ('-I[header]...') for including the Python -header files -@tab -@code{PYTHON_INCLUDES} - -@item -@code{PC_PYTHON_CHECK_HEADERS} -@tab -Check for the Python header files (i.e. @file{Python.h}) -@tab -@code{HAVE_PYTHON_H} - -@item -@code{PC_PYTHON_CHECK_LIBS} -@tab -Check for the proper LIBS flags to load the Python shared libraries -@tab -@code{PYTHON_LIBS} - -@item -@code{PC_PYTHON_TEST_LIBS} -@tab -Test for the presence of the Python shared libraries -@tab -@code{HAVE_LIBPYTHON} - -@item -@code{PC_PYTHON_CHECK_CFLAGS} -@tab -Find the CFLAGS that Python expects -@tab -@code{PYTHON_CFLAGS} - -@item -@code{PC_PYTHON_CHECK_LDFLAGS} -@tab -Find the LDFLAGS that Python expects -@tab -@code{PYTHON_LDFLAGS} - -@item -@code{PC_PYTHON_CHECK_EXTENSION_SUFFIX} -@tab -Check the extension suffix given to Python extension modules (Python 3 -only) -@tab -@code{PYTHON_EXTENSION_SUFFIX} - -@item -@code{PC_PYTHON_CHECK_ABI_FLAGS} -@tab -Check the ABI flags used by Python (Python 3 only) -@tab -@code{PC_PYTHON_ABI_FLAGS} - -@item -@code{PC_PYTHON_CHECK_PLATFORM} -@tab -Check what platform Python thinks this is -@code{PYTHON_PLATFORM} - -@item -@code{PC_PYTHON_CHECK_SITE_DIR} -@tab -Check the appropriate place to install Python packages (i.e. -@file{$(prefix)/lib/python2.7/site-packages}) -@tab -@code{pythondir} - -@item -@code{PC_PYTHON_SITE_PACKAGE_DIR} -@tab -A convenience macro; adds the package's name to @code{pythondir} -@tab -@code{pkgpythondir} - -@item -@code{PC_PYTHON_CHECK_EXEC_DIR} -@tab -Check directory for installing Python extension modules -@tab -@code{pyexecdir} - -@item -@code{PC_PYTHON_EXEC_PACKAGE_DIR} -@tab -A convenience macro; adds the package's name to @code{pyexecdir} -@tab -@code{pkgpyexecdir} - -@item -@code{PC_PYTHON_CHECK_MODULE} -@tab -Test if a given Python module can be successfully loaded -@tab - -@item -@code{PC_PYTHON_CHECK_FUNC} -@tab -Test if a given Python function can be called successfully. -@tab -@end multitable - -Once these macros are integrated into your @file{configure.ac} file as -necessary, simply run @code{autoconf} to generate a new -@file{configure} script. The variables exported by this -@file{configure} script may then be used in @file{Makefile.in} to -influence the build process. - -To include these scripts in a GSRC Makefile, simply create a .tar.gz -archive including at least @file{configure}, @file{Makefile.in} and -@file{m4/}, such that the contents will extract into a directory called -@code{$(DISTNAME)} (i.e. the contents should extract into a directory -called ``mypackage-0.1/''). Put the archive into the @file{files/} -sub-directory of the package's GSRC directory. Finally, simply add the -archive's name to the @code{DISTFILES} list in the GSRC Makefile for -the package and update the checksums file with @code{make -makesums}. Now your GSRC Makefile can simply include -@file{gar.lib/auto.mk} to automate the configuration and installation -of the software. - -@node GNU Free Documentation License, , Appendix, Top -@appendix GNU Free Documentation License - -@include fdl.texi - -@bye -