merge from gcc
[binutils.git] / binutils / README
blob5bc2508b39f16365cd497bc9f372f534a7fb6ae8
1                 README for BINUTILS
3 These are the GNU binutils.  These are utilities of use when dealing
4 with binary files, either object files or executables.  These tools
5 consist of the linker (ld), the assembler (gas), and the profiler
6 (gprof) each of which have their own sub-directory named after them.
7 There is also a collection of other binary tools, including the
8 disassembler (objdump) in this directory.  These tools make use of a
9 pair of libraries (bfd and opcodes) and a common set of header files
10 (include).
12 There are README and NEWS files in most of the program sub-directories
13 which give more information about those specific programs.
16 Unpacking and Installation -- quick overview
17 ============================================
19 When you unpack the binutils archive file, you will get a directory
20 called something like `binutils-XXX', where XXX is the number of the
21 release.  (Probably 2.13 or higher).  This directory contains
22 various files and sub-directories.  Most of the files in the top
23 directory are for information and for configuration.  The actual
24 source code is in sub-directories.
26 To build binutils, you can just do:
28         cd binutils-XXX
29         ./configure [options]
30         make
31         make install # copies the programs files into /usr/local/bin
32                      # by default.
34 This will configure and build all the libraries as well as the
35 assembler, the binutils, and the linker.
37 If you have GNU make, we recommend building in a different directory:
39         mkdir objdir
40         cd objdir
41         ../binutils-XXX/configure [options]
42         make
43         make install
45 This relies on the VPATH feature of GNU make.
47 By default, the binutils will be configured to support the system on
48 which they are built.  When doing cross development, use the --target
49 configure option to specify a different target, eg:
51         ./configure --target=foo-elf        
53 The --enable-targets option adds support for more binary file formats
54 besides the default.  List them as the argument to --enable-targets,
55 separated by commas.  For example:
57         ./configure --enable-targets=sun3,rs6000-aix,decstation
59 The name 'all' compiles in support for all valid BFD targets:
61         ./configure --enable-targets=all
63 On 32-bit hosts though, this support will be restricted to 32-bit
64 target unless the --enable-64-bit-bfd option is also used:
66         ./configure --enable-64-bit-bfd --enable-targets=all
67         
68 You can also specify the --enable-shared option when you run
69 configure.  This will build the BFD and opcodes libraries as shared
70 libraries.  You can use arguments with the --enable-shared option to
71 indicate that only certain libraries should be built shared; for
72 example, --enable-shared=bfd.  The only potential shared libraries in
73 a binutils release are bfd and opcodes.
75 The binutils will be linked against the shared libraries.  The build
76 step will attempt to place the correct library in the run-time search
77 path for the binaries.  However, in some cases, after you install the
78 binaries, you may have to set an environment variable, normally
79 LD_LIBRARY_PATH, so that the system can find the installed libbfd
80 shared library.
82 To build under openVMS/AXP, see the file makefile.vms in the top level
83 directory.
86 Native Language Support
87 =======================
89 By default Native Language Support will be enabled for binutils.  On
90 some systems however this support is not present and can lead to error
91 messages such as "undefined reference to `libintl_gettext'" when
92 building there tools.  If that happens the NLS support can be disabled
93 by adding the --disable-nls switch to the configure line like this:
95         ../binutils-XXX/configure --disable-nls
98 If you don't have ar
99 ====================
101 If your system does not already have an 'ar' program, the normal
102 binutils build process will not work.  In this case, run configure as
103 usual.  Before running make, run this script:
105 #!/bin/sh
106 MAKE_PROG="${MAKE-make}"
107 MAKE="${MAKE_PROG} AR=true LINK=true"
108 export MAKE
109 ${MAKE} $* all-libiberty
110 ${MAKE} $* all-intl
111 ${MAKE} $* all-bfd
112 cd binutils
113 MAKE="${MAKE_PROG}"
114 export MAKE
115 ${MAKE} $* ar_DEPENDENCIES= ar_LDADD='../bfd/*.o ../libiberty/*.o `if test -f ../intl/gettext.o; then echo '../intl/*.o'; fi`' ar
117 This script will build an ar program in binutils/ar.  Move binutils/ar
118 into a directory on your PATH.  After doing this, you can run make as
119 usual to build the complete binutils distribution.  You do not need
120 the ranlib program in order to build the distribution.
122 Porting
123 =======
125 Binutils-2.13 supports many different architectures, but there
126 are many more not supported, including some that were supported
127 by earlier versions.  We are hoping for volunteers to improve this
128 situation.
130 The major effort in porting binutils to a new host and/or target
131 architecture involves the BFD library.  There is some documentation
132 in ../bfd/doc.  The file ../gdb/doc/gdbint.texinfo (distributed
133 with gdb-5.x) may also be of help.
135 Reporting bugs
136 ==============
138 Send bug reports and patches to:
140    bug-binutils@gnu.org.
142 Please include the following in bug reports:
144 - A description of exactly what went wrong, and exactly what should have
145   happened instead.
147 - The configuration name(s) given to the "configure" script.  The
148   "config.status" file should have this information.  This is assuming
149   you built binutils yourself.  If you didn't build binutils youself,
150   then we need information regarding your machine and operating system,
151   and it may be more appropriate to report bugs to wherever you obtained
152   binutils.
154 - The options given to the tool (gas, objcopy, ld etc.) at run time.
156 - The actual input file that caused the problem.
158 Always mention the version number you are running; this is printed by
159 running any of the binutils with the --version option.  We appreciate
160 reports about bugs, but we do not promise to fix them, particularly so
161 when the bug report is against an old version.  If you are able, please
162 consider building the latest tools from CVS to check that your bug has
163 not already been fixed.
165 When reporting problems about gas and ld, it's useful to provide a
166 testcase that triggers the problem.  In the case of a gas problem, we
167 want input files to gas and command line switches used.  The inputs to
168 gas are _NOT_ .c or .i files, but rather .s files.  If your original
169 source was a C program, you can generate the .s file and see the command
170 line options by passing -v -save-temps to gcc in addition to all the
171 usual options you use.  The reason we don't want C files is that we
172 might not have a C compiler around for the target you use.  While it
173 might be possible to build a compiler, that takes considerable time and
174 disk space, and we might not end up with exactly the same compiler you
175 use.
177 In the case of a ld problem, the input files are .o, .a and .so files,
178 and possibly a linker script specified with -T.  Again, when using gcc
179 to link, you can see these files by adding options to the gcc command
180 line.  Use -v -save-temps -Wl,-t, except that on targets that use gcc's
181 collect2, you would add -v -save-temps -Wl,-t,-debug.  The -t option
182 tells ld to print all files and libraries used, so that, for example,
183 you can associate -lc on the ld command line with the actual libc used.
184 Note that your simple two line C program to trigger a problem typically
185 expands into several megabytes of objects by the time you include
186 libraries.
188 It is antisocial to post megabyte sized attachments to mailing lists, so
189 please put large testcases somewhere on an ftp or web site so that only
190 interested developers need to download them, or offer to email them on
191 request.  Better still, try to reduce the testcase, for example, try to
192 develop a ld testcase that doesn't use system libraries.  However,
193 please be sure it is a complete testcase and that it really does
194 demonstrate the problem.  Also, don't bother paring it down if that will
195 cause large delays in filing the bug report.
197 If you expect to be contributing a large number of test cases, it would
198 be helpful if you would look at the test suite included in the release
199 (based on the Deja Gnu testing framework, available from the usual ftp
200 sites) and write test cases to fit into that framework.  This is
201 certainly not required.
206 This section was written by Klaus K"ampf <kkaempf@rmi.de>.  It
207 describes how to build and install the binutils on openVMS (Alpha and
208 Vax).  (The BFD library only supports reading Vax object files.)
210 Compiling the release:
212 To compile the gnu binary utilities and the gnu assembler, you'll
213 need DEC C or GNU C for openVMS/Alpha. You'll need *both* compilers
214 on openVMS/Vax.
216 Compiling with either DEC C or GNU C works on openVMS/Alpha only. Some
217 of the opcodes and binutils files trap a bug in the DEC C optimizer,
218 so these files must be compiled with /noopt.
220 Compiling on openVMS/Vax is a bit complicated, as the bfd library traps
221 a bug in GNU C and the gnu assembler a bug in (my version of) DEC C.
223 I never tried compiling with VAX C.
226 You further need GNU Make Version 3.76 or later. This is available
227 at ftp.progis.de or any GNU archive site. The makefiles assume that
228 gmake starts gnu make as a foreign command.
230 If you're compiling with DEC C or VAX C, you must run
232   $ @setup
234 before starting gnu-make. This isn't needed with GNU C.
236 On the Alpha you can choose the compiler by editing the toplevel
237 makefile.vms. Either select CC=cc (for DEC C) or CC=gcc (for GNU C)
240 Installing the release
242 Provided that your directory setup conforms to the GNU on openVMS
243 standard, you already have a concealed device named 'GNU_ROOT'.
244 In this case, a simple
246  $ gmake install
248 suffices to copy all programs and libraries to the proper directories.
250 Define the programs as foreign commands by adding these lines to your
251 login.com:
253   $ gas :== $GNU_ROOT:[bin]as.exe
254   $ size :== $GNU_ROOT:[bin]size.exe
255   $ nm :== $GNU_ROOT:[bin]nm.exe
256   $ objdump :== $GNU_ROOT:[bin]objdump.exe
257   $ strings :== $GNU_ROOT:[bin]strings.exe
259 If you have a different directory setup, copy the binary utilities
260 ([.binutils]size.exe, [.binutils]nm.exe, [.binutils]objdump.exe,
261 and [.binutils]strings.exe) and the gnu assembler and preprocessor
262 ([.gas]as.exe and [.gas]gasp.exe]) to a directory of your choice
263 and define all programs as foreign commands.
266 If you're satisfied with the compilation, you may want to remove
267 unneeded objects and libraries:
269   $ gmake clean
272 If you have any problems or questions about the binutils on VMS, feel
273 free to mail me at kkaempf@rmi.de.