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