Update.

1998-03-18 00:25  Tim Waugh  <tim@cyberelk.demon.co.uk>

	* posix/wordexp.c (parse_comm): Allow quoting inside $(...).
	(parse_param): Fold in Andreas' fixes to do with when the end of
	the parameter name has been reached, and quoting inside ${...}.
	(parse_dollars): Fix differentiation between $(((1+3)*(4-2))) and
	$((echo);(ls)).

1998-03-16 22:10  Zack Weinberg  <zack@rabi.phys.columbia.edu>

	* manual/maint.texi: Split out installation and contribution
	sections to their own appendices.  Misc cleanups.
	* manual/install.texi: New file.  Mention add-ons.  Refer to FAQ.
	* manual/contrib.texi: New file.
	* manual/libc.texinfo: Pull in new appendices.
	* manual/header.texi: Correct node pointer.

1998-03-17  Andreas Jaeger  <aj@arthur.rhein-neckar.de>

	* manual/process.texi (Process Completion): Clarify return value
	of waitpid a bit.  Patch by Zack Weinberg. [PR libc/490]

1 files changed, 375 insertions, 0 deletions

diff --git a/manual/install.texi b/manual/install.texi
new file mode 100644
index 0000000000..6f686c37a8
--- /dev/null
+++ b/manual/install.texi
@@ -0,0 +1,375 @@
+@c This is for making the `INSTALL' file for the distribution.
+@c Makeinfo ignores it when processing the file from the include.
+@setfilename INSTALL
+
+@node Installation, Maintenance, Library Summary, Top
+@appendix Installing the GNU C Library
+
+@menu
+* Tools for Installation::      We recommend using these tools to build.
+* Supported Configurations::    What systems the GNU C library runs on.
+* Reporting Bugs::              How to report bugs (if you want to
+                                get them fixed) and other troubles
+                                you may have with the GNU C library.
+@end menu
+
+Installation of the GNU C library is relatively simple, but usually
+requires several GNU tools to be installed already.
+@iftex
+(@pxref{Tools for Installation}, below.)
+@end iftex
+
+Before you do anything else, you should read the file @file{FAQ} found
+at the top level of the source tree.  This file answers common questions
+and describes problems you may experience with compilation and
+installation.  It is updated more frequently than this manual.
+
+To configure the GNU C library for your system, run the shell script
+@file{configure} with @code{sh}.  Use an argument which is the
+conventional GNU name for your system configuration---for example,
+@samp{sparc-sun-sunos4.1}, for a Sun 4 running SunOS 4.1.
+@xref{Installation, Installation, Installing GNU CC, gcc.info, Using and
+Porting GNU CC}, for a full description of standard GNU configuration
+names.  If you omit the configuration name, @file{configure} will try to
+guess one for you by inspecting the system it is running on.  It may or
+may not be able to come up with a guess, and the its guess might be
+wrong.  @file{configure} will tell you the canonical name of the chosen
+configuration before proceeding.
+
+Here are some options that you should specify (if appropriate) when
+you run @code{configure}:
+
+@table @samp
+@item --with-binutils=@var{directory}
+Use the binutils (assembler and linker) in @file{@var{directory}}, not
+the ones the C compiler would default to.  You could use this option if
+the default binutils on your system cannot deal with all the constructs
+in the GNU C library.  (@code{configure} will detect the problem and
+suppress these constructs, so the library will still be usable, but
+functionality may be lost---for example, you can not build a shared libc
+with old binutils.)
+
+@c extra blank line makes it look better
+@item --without-fp
+@itemx --nfp
+
+Use this option if your computer lacks hardware floating-point support
+and your operating system does not emulate an FPU.
+
+@item --prefix=@var{directory}
+Install machine-independent data files in subdirectories of
+@file{@var{directory}}.  (You can also set this in @file{configparms};
+see below.)  The default is to install in `/usr/local'.
+
+@item --exec-prefix=@var{directory}
+Install the library and other machine-dependent files in subdirectories
+of @file{@var{directory}}.  (You can also set this in
+@file{configparms}; see below.)  The default is to use <prefix>/bin
+and <prefix>/sbin.
+
+@item --enable-shared
+@itemx --disable-shared
+Enable or disable building of an ELF shared library on systems that
+support it.  The default is to build the shared library on systems using
+ELF when the GNU @code{binutils} are available.
+
+@item --enable-profile
+@itemx --disable-profile
+Enable or disable building of the profiled C library, @samp{-lc_p}.  The
+default is to build the profiled library.  You may wish to disable it if
+you don't plan to do profiling, because it doubles the build time of
+compiling just the unprofiled static library.
+
+@item --enable-omitfp
+Enable building a highly-optimized but possibly undebuggable C
+library.  This causes the normal static and shared (if enabled) C
+libraries to be compiled with maximal optimization, including the
+@samp{-fomit-frame-pointer} switch that makes debugging impossible on
+many machines, and without debugging information (which makes the
+binaries substantially smaller).  An additional static library is
+compiled with no optimization and full debugging information, and
+installed as @samp{-lc_g}.
+
+@item --enable-add-ons[=LIST]
+Certain components of the C library are distributed separately from the
+rest of the sources.  In particular, the @code{crypt} function and its
+friends are separated due to US export control regulations, and the
+threading support code for Linux is maintained separately.  You can get
+these @dfn{add-on} packages from the same place you got the libc
+sources.  To use them, unpack them into your source tree, and give
+@code{configure} the @samp{--enable-add-ons} option.
+
+If you do not wish to use some add-on package that you have present in
+your source tree, give this option a list of the add-ons that you
+@emph{do} want used, like this: @samp{--enable-add-ons=crypt,linuxthreads}
+@end table
+
+You should not build the library in the same directory as the sources,
+because there are bugs in @code{make clean}.  Make a directory for the
+build, and run @code{configure} from that directory, like this:
+
+@smallexample
+mkdir sun4
+cd sun4
+../configure sparc-sun-sunos4.1
+@end smallexample
+
+@noindent
+@code{configure} looks for the sources in whatever directory you
+specified for finding @code{configure} itself.  It does not matter where
+in the file system the source and build directories are---as long as you
+specify the source directory when you run @code{configure}, you will get
+the proper results.
+
+This feature lets you keep sources and binaries in different
+directories, and that makes it easy to build the library for several
+different machines from the same set of sources.  Simply create a
+build directory for each target machine, and run @code{configure} in
+that directory specifying the target machine's configuration name.
+
+The library has a number of special-purpose configuration parameters.
+These are defined in the file @file{configparms}; see the comments in
+that file for the details.  To change them, copy @file{configparms} into
+your build directory and modify it as appropriate for your system.
+@code{configure} will not notice your modifications if you change the
+file in the source directory.
+
+It is easy to configure the GNU C library for cross-compilation by
+setting a few variables in @file{configparms}.  Set @code{CC} to the
+cross-compiler for the target you configured the library for; it is
+important to use this same @code{CC} value when running
+@code{configure}, like this: @samp{CC=@var{target}-gcc configure
+@var{target}}.  Set @code{BUILD_CC} to the compiler to use for for
+programs run on the build system as part of compiling the library.  You
+may need to set @code{AR} and @code{RANLIB} to cross-compiling versions
+of @code{ar} and @code{ranlib} if the native tools are not configured to
+work with object files for the target you configured for.
+
+Some of the machine-dependent code for some machines uses extensions in
+the GNU C compiler, so you may need to compile the library with GCC.
+(In fact, all of the existing complete ports require GCC.)
+
+
+To build the library and related programs, type @code{make}.  This will
+produce a lot of output, some of which may look like errors from
+@code{make} (but isn't).  Look for error messages from @code{make}
+containing @samp{***}.  Those indicate that something is really wrong.
+
+To build and run some test programs which exercise some of the library
+facilities, type @code{make check}.  This will produce several files
+with names like @file{@var{program}.out}.
+
+To format the @cite{GNU C Library Reference Manual} for printing, type
+@w{@code{make dvi}}.  You need a working @TeX{} installation to do this.
+
+To install the library and its header files, and the Info files of the
+manual, type @code{make install}.  This will build things if necessary,
+before installing them.  If you want to install the files in a different
+place than the one specified at configuration time you can specify a
+value for the Makefile variable @code{install_root} on the command line.
+This is useful to create chroot'ed environment or to prepare binary
+releases.@refill
+
+@node Tools for Installation
+@appendixsec Recommended Tools to Install the GNU C Library
+@cindex installation tools
+@cindex tools, for installing library
+
+We recommend installing the following GNU tools before attempting to
+build the GNU C library:
+
+@itemize @bullet
+@item
+GNU @code{make} 3.75
+
+You need the latest version of GNU @code{make}.  Modifying the GNU C
+Library to work with other @code{make} programs would be so hard that we
+recommend you port GNU @code{make} instead.  @strong{Really.}  We
+recommend version GNU @code{make} version 3.75.  Versions 3.76 and
+3.76.1 are known to have bugs which only show up in big projects like
+GNU @code{libc}.
+
+@item
+GCC 2.7.2.3
+
+On most platforms, the GNU C library can only be compiled with the GNU C
+compiler.  We recommend GCC version 2.7.2 or later; earlier versions may
+have problems.
+
+On PowerPC, GCC versions dated earlier than 970904 are known not to work
+(they crash), including 2.7.2.
+
+@item
+GNU @code{binutils} 2.8.1.0.23
+
+Using the GNU @code{binutils} (assembler, linker, and related tools) is
+preferable when possible, and they are required to build an ELF shared C
+library.  Version 2.1 of the library uses ELF symbol versioning
+extensively.  Support for this feature is incomplete or buggy before
+binutils 2.8.1.0.23, so you must use at least this version.
+
+@item
+GNU @code{texinfo} 3.11
+
+To correctly translate and install the Texinfo documentation you need
+this version of the @code{texinfo} package.  Earlier versions do not
+understand all the tags used in the document, and the installation
+mechanisms for the info files is not present or works differently.
+
+On some Debian Linux based systems the @code{install-info} program
+supplied with the system works differently from the one we expect.  You
+must therefore run @code{make install} like this:
+
+@smallexample
+make INSTALL_INFO=/path/to/GNU/install-info install
+@end smallexample
+
+@item
+GNU @code{awk} 3.0
+
+Several files used during the build are generated using features of GNU
+@code{awk} that are not found in other implementations.
+@c XXX: Does mawk work?
+@end itemize
+
+@noindent
+If you change any of the @file{configure.in} files you will also need
+
+@itemize @bullet
+@item
+GNU @code{autoconf} 2.12
+@end itemize
+
+@noindent
+and if you change any of the message translation files you will need
+
+@itemize @bullet
+@item
+GNU @code{gettext} 0.10 or later
+@end itemize
+
+@noindent
+You may also need these packages if you upgrade your source tree using
+patches, although we try to avoid this.
+
+
+@node Supported Configurations
+@appendixsec Supported Configurations
+@cindex configurations, all supported
+
+The GNU C Library currently supports configurations that match the
+following patterns:
+
+@smallexample
+alpha-@var{anything}-linux
+i@var{x}86-@var{anything}-gnu
+i@var{x}86-@var{anything}-linux
+m68k-@var{anything}-linux
+powerpc-@var{anything}-linux
+sparc-@var{anything}-linux
+sparc64-@var{anything}-linux
+@end smallexample
+
+Former releases of this library (version 1.09.1 and perhaps earlier
+versions) used to run on the following configurations:
+
+@smallexample
+alpha-dec-osf1
+alpha-@var{anything}-linuxecoff
+i@var{x}86-@var{anything}-bsd4.3
+i@var{x}86-@var{anything}-isc2.2
+i@var{x}86-@var{anything}-isc3.@var{n}
+i@var{x}86-@var{anything}-sco3.2
+i@var{x}86-@var{anything}-sco3.2v4
+i@var{x}86-@var{anything}-sysv
+i@var{x}86-@var{anything}-sysv4
+i@var{x}86-force_cpu386-none
+i@var{x}86-sequent-bsd
+i960-nindy960-none
+m68k-hp-bsd4.3
+m68k-mvme135-none
+m68k-mvme136-none
+m68k-sony-newsos3
+m68k-sony-newsos4
+m68k-sun-sunos4.@var{n}
+mips-dec-ultrix4.@var{n}
+mips-sgi-irix4.@var{n}
+sparc-sun-solaris2.@var{n}
+sparc-sun-sunos4.@var{n}
+@end smallexample
+
+Since no one has volunteered to test and fix these configurations,
+they are not supported at the moment.  They probably don't compile;
+they definitely don't work anymore.  Porting the library is not hard.
+If you are interested in doing a port, please contact the glibc
+maintainers by sending electronic mail to @email{bug-glibc@@gnu.org}.
+
+Each case of @samp{i@var{x}86} can be @samp{i386}, @samp{i486},
+@samp{i586}, or @samp{i686}.  All of those configurations produce a
+library that can run on any of these processors.  The library will be
+optimized for the specified processor, but will not use instructions not
+available on all of them.
+
+While no other configurations are supported, there are handy aliases for
+these few.  (These aliases work in other GNU software as well.)
+
+@smallexample
+decstation
+hp320-bsd4.3 hp300bsd
+i486-gnu
+i586-linux
+i386-sco
+i386-sco3.2v4
+i386-sequent-dynix
+i386-svr4
+news
+sun3-sunos4.@var{n} sun3
+sun4-solaris2.@var{n} sun4-sunos5.@var{n}
+sun4-sunos4.@var{n} sun4
+@end smallexample
+
+@node Reporting Bugs
+@appendixsec Reporting Bugs
+@cindex reporting bugs
+@cindex bugs, reporting
+
+There are probably bugs in the GNU C library.  There are certainly
+errors and omissions in this manual.  If you report them, they will get
+fixed.  If you don't, no one will ever know about them and they will
+remain unfixed for all eternity, if not longer.
+
+To report a bug, first you must find it.  Hopefully, this will be the
+hard part.  Once you've found a bug, make sure it's really a bug.  A
+good way to do this is to see if the GNU C library behaves the same way
+some other C library does.  If so, probably you are wrong and the
+libraries are right (but not necessarily).  If not, one of the libraries
+is probably wrong.
+
+Once you're sure you've found a bug, try to narrow it down to the
+smallest test case that reproduces the problem.  In the case of a C
+library, you really only need to narrow it down to one library
+function call, if possible.  This should not be too difficult.
+
+The final step when you have a simple test case is to report the bug.
+When reporting a bug, send your test case, the results you got, the
+results you expected, what you think the problem might be (if you've
+thought of anything), your system type, and the version of the GNU C
+library which you are using.  Also include the files
+@file{config.status} and @file{config.make} which are created by running
+@file{configure}; they will be in whatever directory was current when
+you ran @file{configure}.
+
+If you think you have found some way in which the GNU C library does not
+conform to the ISO and POSIX standards (@pxref{Standards and
+Portability}), that is definitely a bug.  Report it!@refill
+
+Send bug reports to the Internet address
+@email{bug-glibc@@gnu.org}.  If you have other problems
+with installation or use, please report those as well.@refill
+
+If you are not sure how a function should behave, and this manual
+doesn't tell you, that's a bug in the manual.  Report that too!  If the
+function's behavior disagrees with the manual, then either the library
+or the manual has a bug, so report the disagreement.  If you find any
+errors or omissions in this manual, please report them to the Internet
+address @email{bug-glibc-manual@@gnu.org}.