Regenerated: autoconf configure.in
[kopensolaris-gnu/glibc.git] / INSTALL
1 Installing the GNU C Library
2 ****************************
3
4    Installation of the GNU C library is relatively simple, but usually
5 requires several GNU tools to be installed already.
6
7    Before you do anything else, you should read the file `FAQ' found at
8 the top level of the source tree.  This file answers common questions
9 and describes problems you may experience with compilation and
10 installation.  It is updated more frequently than this manual.
11
12    To configure the GNU C library for your system, run the shell script
13 `configure' with `sh'.  You might use an argument which is the
14 conventional GNU name for your system configuration--for example,
15 `i486-pc-linux-gnu', for Linux running on i486.  *Note Installation:
16 (gcc.info)Installation, for a full description of standard GNU
17 configuration names.  If you omit the configuration name, `configure'
18 will try to guess one for you by inspecting the system it is running
19 on.  It may or may not be able to come up with a guess, and the guess
20 might be wrong.  `configure' will tell you the canonical name of the
21 chosen configuration before proceeding.
22
23    Here are some options that you should specify (if appropriate) when
24 you run `configure':
25
26 `--with-binutils=DIRECTORY'
27      Use the binutils (assembler and linker) in `DIRECTORY', not the
28      ones the C compiler would default to.  You could use this option if
29      the default binutils on your system cannot deal with all the
30      constructs in the GNU C library.  (`configure' will detect the
31      problem and suppress these constructs, so the library will still
32      be usable, but functionality may be lost--for example, you can not
33      build a shared libc with old binutils.)
34
35 `--without-fp'
36 `--nfp'
37      Use this option if your computer lacks hardware floating-point
38      support and your operating system does not emulate an FPU.
39
40 `--prefix=DIRECTORY'
41      Install machine-independent data files in subdirectories of
42      `DIRECTORY'.  (You can also set this in `configparms'; see below.)
43      The default is to install in `/usr/local'.
44
45 `--exec-prefix=DIRECTORY'
46      Install the library and other machine-dependent files in
47      subdirectories of `DIRECTORY'.  (You can also set this in
48      `configparms'; see below.)  The default is to use <prefix>/bin and
49      <prefix>/sbin.
50
51 `--enable-shared'
52 `--disable-shared'
53      Enable or disable building of an ELF shared library on systems that
54      support it.  The default is to build the shared library on systems
55      using ELF when the GNU `binutils' are available.
56
57 `--enable-profile'
58 `--disable-profile'
59      Enable or disable building of the profiled C library, `-lc_p'.  The
60      default is to build the profiled library.  You may wish to disable
61      it if you don't plan to do profiling, because it doubles the build
62      time of compiling just the unprofiled static library.
63
64 `--enable-omitfp'
65      Enable building a highly-optimized but possibly undebuggable C
66      library.  This causes the normal static and shared (if enabled) C
67      libraries to be compiled with maximal optimization, including the
68      `-fomit-frame-pointer' switch that makes debugging impossible on
69      many machines, and without debugging information (which makes the
70      binaries substantially smaller).  An additional static library is
71      compiled with no optimization and full debugging information, and
72      installed as `-lc_g'.
73
74 `--enable-add-ons[=LIST]'
75      Certain components of the C library are distributed separately
76      from the rest of the sources.  In particular, the `crypt' function
77      and its friends are separated due to US export control
78      regulations, and the threading support code for Linux is
79      maintained separately.  You can get these "add-on" packages from
80      the same place you got the libc sources.  To use them, unpack them
81      into your source tree, and give `configure' the `--enable-add-ons'
82      option.
83
84      If you do not wish to use some add-on package that you have
85      present in your source tree, give this option a list of the
86      add-ons that you *do* want used, like this:
87      `--enable-add-ons=crypt,linuxthreads'
88
89 `--with-headers=DIRECTORY'
90      Search only DIRECTORY and the C compiler's private directory for
91      header files not found in the libc sources.  `/usr/include' will
92      not be searched if this option is given.  On Linux, DIRECTORY
93      should be the kernel's private include directory (usually
94      `/usr/src/linux/include').
95
96      This option is primarily of use on a system where the headers in
97      `/usr/include' come from an older version of glibc.  Conflicts can
98      occasionally happen in this case.  Note that Linux libc5 qualifies
99      as an older version of glibc.  You can also use this option if you
100      want to compile glibc with a newer set of kernel headers than the
101      ones found in `/usr/include'.
102
103    You should not build the library in the same directory as the
104 sources, because there are bugs in `make clean'.  Make a directory for
105 the build, and run `configure' from that directory, like this:
106
107      mkdir linux
108      cd linux
109      ../configure
110
111 `configure' looks for the sources in whatever directory you specified
112 for finding `configure' itself.  It does not matter where in the file
113 system the source and build directories are--as long as you specify the
114 source directory when you run `configure', you will get the proper
115 results.
116
117    This feature lets you keep sources and binaries in different
118 directories, and that makes it easy to build the library for several
119 different machines from the same set of sources.  Simply create a build
120 directory for each target machine, and run `configure' in that
121 directory specifying the target machine's configuration name.
122
123    The library has a number of special-purpose configuration parameters.
124 These are defined in the file `configparms'; see the comments in that
125 file for the details.  To change them, copy `configparms' into your
126 build directory and modify it as appropriate for your system.
127 `configure' will not notice your modifications if you change the file
128 in the source directory.
129
130    It is easy to configure the GNU C library for cross-compilation by
131 setting a few variables in `configparms'.  Set `CC' to the
132 cross-compiler for the target you configured the library for; it is
133 important to use this same `CC' value when running `configure', like
134 this: `CC=TARGET-gcc configure TARGET'.  Set `BUILD_CC' to the compiler
135 to use for for programs run on the build system as part of compiling
136 the library.  You may need to set `AR' and `RANLIB' to cross-compiling
137 versions of `ar' and `ranlib' if the native tools are not configured to
138 work with object files for the target you configured for.
139
140    Some of the machine-dependent code for some machines uses extensions
141 in the GNU C compiler, so you may need to compile the library with GCC.
142 (In fact, all of the existing complete ports require GCC.)
143
144    To build the library and related programs, type `make'.  This will
145 produce a lot of output, some of which may look like errors from `make'
146 (but isn't).  Look for error messages from `make' containing `***'.
147 Those indicate that something is really wrong.
148
149    The compilation process takes several hours even on fast hardware;
150 expect at least two hours for the default configuration on i586 for
151 Linux.  For Hurd times are much longer.  All current releases of GCC
152 have a problem which causes them to take several minutes to compile
153 certain files in the iconvdata directory.  Do not panic if the compiler
154 appears to hang.
155
156    To build and run some test programs which exercise some of the
157 library facilities, type `make check'.  This will produce several files
158 with names like `PROGRAM.out'.
159
160    To format the `GNU C Library Reference Manual' for printing, type
161 `make dvi'.  You need a working TeX installation to do this.
162
163    To install the library and its header files, and the Info files of
164 the manual, type `make install'.  This will build things if necessary,
165 before installing them.  If you want to install the files in a different
166 place than the one specified at configuration time you can specify a
167 value for the Makefile variable `install_root' on the command line.
168 This is useful to create chroot'ed environment or to prepare binary
169 releases.
170
171    For now (in this alpha version, and at least on RedHat Linux), if you
172 are trying to install this as your default libraries, a different
173 installation method is recommended.  Move `/usr/include' out of the
174 way, create a new `/usr/include' directory (don't forget the symlinks
175 `/usr/include/asm' and `/usr/include/linux', that should point to
176 `/usr/src/linux/include/asm' and `/usr/src/linux/include/linux' -or
177 wherever you keep your kernel sources-respectively), build normally and
178 install into somewhere else via `install_root'. Then move your
179 `/usr/include' back, and copy the newly created stuff by hand over the
180 old. Remember to copy programs and shared libraries into `FILENAME.new'
181 and then move `FILENAME.new' to `FILENAME', as the files might be in
182 use. You will have to `ranlib' your copies of the static libraries
183 `/usr/lib/libNAME.a'. You will see that `libbsd-compat.a', `libieee.a',
184 and `libmcheck.a' are just object files, not archives. This is normal.
185 Copy the new header files over the old ones by something like
186 `cd /usr; (cd INSTALL_ROOT; tar cf - include) | tar xf -'.
187
188 Recommended Tools to Install the GNU C Library
189 ==============================================
190
191    We recommend installing the following GNU tools before attempting to
192 build the GNU C library:
193
194    * GNU `make' 3.75
195
196      You need the latest version of GNU `make'.  Modifying the GNU C
197      Library to work with other `make' programs would be so hard that we
198      recommend you port GNU `make' instead.  *Really.*  We recommend
199      version GNU `make' version 3.75.  Versions 3.76 and 3.76.1 are
200      known to have bugs which only show up in big projects like GNU
201      `libc'.
202
203    * GCC 2.8.1/EGCS 1.0.2
204
205      On most platforms, the GNU C library can only be compiled with the
206      GNU C compiler family.  We recommend GCC version 2.8.1 and EGCS
207      version 1.0.2 or later versions of these two; earlier versions may
208      have problems.
209
210    * GNU `binutils' 2.8.1.0.23
211
212      Using the GNU `binutils' (assembler, linker, and related tools) is
213      preferable when possible, and they are required to build an ELF
214      shared C library.  Version 2.1 of the library uses ELF symbol
215      versioning extensively.  Support for this feature is incomplete or
216      buggy before binutils 2.8.1.0.23, so you must use at least this
217      version.
218
219    * GNU `texinfo' 3.11
220
221      To correctly translate and install the Texinfo documentation you
222      need this version of the `texinfo' package.  Earlier versions do
223      not understand all the tags used in the document, and the
224      installation mechanisms for the info files is not present or works
225      differently.
226
227      On some Debian Linux based systems the `install-info' program
228      supplied with the system works differently from the one we expect.
229      You must therefore run `make install' like this:
230
231           make INSTALL_INFO=/path/to/GNU/install-info install
232
233    * GNU `awk' 3.0
234
235      Several files used during the build are generated using features
236      of GNU `awk' that are not found in other implementations.
237
238 If you change any of the `configure.in' files you will also need
239
240    * GNU `autoconf' 2.12
241
242 and if you change any of the message translation files you will need
243
244    * GNU `gettext' 0.10 or later
245
246 You may also need these packages if you upgrade your source tree using
247 patches, although we try to avoid this.
248
249 Supported Configurations
250 ========================
251
252    The GNU C Library currently supports configurations that match the
253 following patterns:
254
255      alpha-ANYTHING-linux
256      arm-ANYTHING-linuxaout
257      arm-ANYTHING-none
258      iX86-ANYTHING-gnu
259      iX86-ANYTHING-linux
260      m68k-ANYTHING-linux
261      powerpc-ANYTHING-linux
262      sparc-ANYTHING-linux
263      sparc64-ANYTHING-linux
264
265    Former releases of this library (version 1.09.1 and perhaps earlier
266 versions) used to run on the following configurations:
267
268      alpha-dec-osf1
269      alpha-ANYTHING-linuxecoff
270      iX86-ANYTHING-bsd4.3
271      iX86-ANYTHING-isc2.2
272      iX86-ANYTHING-isc3.N
273      iX86-ANYTHING-sco3.2
274      iX86-ANYTHING-sco3.2v4
275      iX86-ANYTHING-sysv
276      iX86-ANYTHING-sysv4
277      iX86-force_cpu386-none
278      iX86-sequent-bsd
279      i960-nindy960-none
280      m68k-hp-bsd4.3
281      m68k-mvme135-none
282      m68k-mvme136-none
283      m68k-sony-newsos3
284      m68k-sony-newsos4
285      m68k-sun-sunos4.N
286      mips-dec-ultrix4.N
287      mips-sgi-irix4.N
288      sparc-sun-solaris2.N
289      sparc-sun-sunos4.N
290
291    Since no one has volunteered to test and fix these configurations,
292 they are not supported at the moment.  They probably don't compile;
293 they definitely don't work anymore.  Porting the library is not hard.
294 If you are interested in doing a port, please contact the glibc
295 maintainers by sending electronic mail to <bug-glibc@gnu.org>.
296
297    Each case of `iX86' can be `i386', `i486', `i586', or `i686'.  All
298 of those configurations produce a library that can run on any of these
299 processors.  The library will be optimized for the specified processor,
300 but will not use instructions not available on all of them.
301
302    While no other configurations are supported, there are handy aliases
303 for these few.  (These aliases work in other GNU software as well.)
304
305      decstation
306      hp320-bsd4.3 hp300bsd
307      i486-gnu
308      i586-linux
309      i386-sco
310      i386-sco3.2v4
311      i386-sequent-dynix
312      i386-svr4
313      news
314      sun3-sunos4.N sun3
315      sun4-solaris2.N sun4-sunos5.N
316      sun4-sunos4.N sun4
317
318 Useful hints for the installation
319 =================================
320
321    There are a some more or less obvious methods one should know when
322 compiling GNU libc:
323
324    * Better never compile in the source directory.  Create a new
325      directory and run the `configure' from there.  Everything should
326      happen automagically.
327
328    * You can use the `-j' option of GNU make by changing the line
329      specifying `PARALLELMAKE' in the Makefile generated during the
330      configuration.
331
332      It is not useful to start the `make' process using the `-j' option
333      since this option is not propagated down to the sub-`make's.
334
335    * If you made some changes after a complete build and only want to
336      check these changes run `make' while specifying the list of
337      subdirs it has to visit.
338
339           make subdirs="nss elf"
340
341      The above build run will only visit the subdirectories `nss' and
342      `elf'.  Beside this it updates the `libc' files itself.
343
344 Reporting Bugs
345 ==============
346
347    There are probably bugs in the GNU C library.  There are certainly
348 errors and omissions in this manual.  If you report them, they will get
349 fixed.  If you don't, no one will ever know about them and they will
350 remain unfixed for all eternity, if not longer.
351
352    To report a bug, first you must find it.  Hopefully, this will be the
353 hard part.  Once you've found a bug, make sure it's really a bug.  A
354 good way to do this is to see if the GNU C library behaves the same way
355 some other C library does.  If so, probably you are wrong and the
356 libraries are right (but not necessarily).  If not, one of the libraries
357 is probably wrong.
358
359    Once you're sure you've found a bug, try to narrow it down to the
360 smallest test case that reproduces the problem.  In the case of a C
361 library, you really only need to narrow it down to one library function
362 call, if possible.  This should not be too difficult.
363
364    The final step when you have a simple test case is to report the bug.
365 When reporting a bug, send your test case, the results you got, the
366 results you expected, what you think the problem might be (if you've
367 thought of anything), your system type, and the version of the GNU C
368 library which you are using.  Also include the files `config.status'
369 and `config.make' which are created by running `configure'; they will
370 be in whatever directory was current when you ran `configure'.
371
372    If you think you have found some way in which the GNU C library does
373 not conform to the ISO and POSIX standards (*note Standards and
374 Portability::.), that is definitely a bug.  Report it!
375
376    Send bug reports to the Internet address <bug-glibc@gnu.org> using
377 the `glibcbug' script which is installed by the GNU C library.  If you
378 have other problems with installation or use, please report those as
379 well.
380
381    If you are not sure how a function should behave, and this manual
382 doesn't tell you, that's a bug in the manual.  Report that too!  If the
383 function's behavior disagrees with the manual, then either the library
384 or the manual has a bug, so report the disagreement.  If you find any
385 errors or omissions in this manual, please report them to the Internet
386 address <bug-glibc-manual@gnu.org>.  If you refer to specific sections
387 when reporting on the manual, please include the section names for
388 easier identification.
389