2001-07-19 12:43:13 +02:00
|
|
|
|
README for BINUTILS
|
1999-05-03 09:29:11 +02:00
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
These are the GNU binutils. These are utilities of use when dealing
|
|
|
|
|
with binary files, either object files or executables. These tools
|
|
|
|
|
consist of the linker (ld), the assembler (gas), and the profiler
|
|
|
|
|
(gprof) each of which have their own sub-directory named after them.
|
|
|
|
|
There is also a collection of other binary tools, including the
|
|
|
|
|
disassembler (objdump) in this directory. These tools make use of a
|
|
|
|
|
pair of libraries (bfd and opcodes) and a common set of header files
|
|
|
|
|
(include).
|
1999-05-03 09:29:11 +02:00
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
There are README and NEWS files in most of the program sub-directories
|
|
|
|
|
which give more information about those specific programs.
|
1999-05-03 09:29:11 +02:00
|
|
|
|
|
|
|
|
|
|
2014-03-01 12:25:26 +01:00
|
|
|
|
Copyright Notices
|
|
|
|
|
=================
|
|
|
|
|
|
|
|
|
|
Copyright years on binutils source files may be listed using range
|
|
|
|
|
notation, e.g., 1991-2012, indicating that every year in the range,
|
|
|
|
|
inclusive, is a copyrightable year that could otherwise be listed
|
|
|
|
|
individually.
|
|
|
|
|
|
|
|
|
|
|
1999-05-03 09:29:11 +02:00
|
|
|
|
Unpacking and Installation -- quick overview
|
|
|
|
|
============================================
|
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
When you unpack the binutils archive file, you will get a directory
|
|
|
|
|
called something like `binutils-XXX', where XXX is the number of the
|
2003-02-24 17:37:13 +01:00
|
|
|
|
release. (Probably 2.13 or higher). This directory contains
|
2001-07-19 12:43:13 +02:00
|
|
|
|
various files and sub-directories. Most of the files in the top
|
|
|
|
|
directory are for information and for configuration. The actual
|
|
|
|
|
source code is in sub-directories.
|
1999-05-03 09:29:11 +02:00
|
|
|
|
|
|
|
|
|
To build binutils, you can just do:
|
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
cd binutils-XXX
|
1999-05-03 09:29:11 +02:00
|
|
|
|
./configure [options]
|
|
|
|
|
make
|
|
|
|
|
make install # copies the programs files into /usr/local/bin
|
|
|
|
|
# by default.
|
|
|
|
|
|
|
|
|
|
This will configure and build all the libraries as well as the
|
|
|
|
|
assembler, the binutils, and the linker.
|
|
|
|
|
|
|
|
|
|
If you have GNU make, we recommend building in a different directory:
|
|
|
|
|
|
|
|
|
|
mkdir objdir
|
|
|
|
|
cd objdir
|
2001-07-19 12:43:13 +02:00
|
|
|
|
../binutils-XXX/configure [options]
|
1999-05-03 09:29:11 +02:00
|
|
|
|
make
|
|
|
|
|
make install
|
|
|
|
|
|
|
|
|
|
This relies on the VPATH feature of GNU make.
|
|
|
|
|
|
|
|
|
|
By default, the binutils will be configured to support the system on
|
|
|
|
|
which they are built. When doing cross development, use the --target
|
2001-07-19 12:43:13 +02:00
|
|
|
|
configure option to specify a different target, eg:
|
|
|
|
|
|
|
|
|
|
./configure --target=foo-elf
|
1999-05-03 09:29:11 +02:00
|
|
|
|
|
|
|
|
|
The --enable-targets option adds support for more binary file formats
|
|
|
|
|
besides the default. List them as the argument to --enable-targets,
|
|
|
|
|
separated by commas. For example:
|
|
|
|
|
|
|
|
|
|
./configure --enable-targets=sun3,rs6000-aix,decstation
|
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
The name 'all' compiles in support for all valid BFD targets:
|
1999-05-03 09:29:11 +02:00
|
|
|
|
|
|
|
|
|
./configure --enable-targets=all
|
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
On 32-bit hosts though, this support will be restricted to 32-bit
|
|
|
|
|
target unless the --enable-64-bit-bfd option is also used:
|
|
|
|
|
|
|
|
|
|
./configure --enable-64-bit-bfd --enable-targets=all
|
2009-07-14 09:43:18 +02:00
|
|
|
|
|
1999-05-03 09:29:11 +02:00
|
|
|
|
You can also specify the --enable-shared option when you run
|
|
|
|
|
configure. This will build the BFD and opcodes libraries as shared
|
|
|
|
|
libraries. You can use arguments with the --enable-shared option to
|
|
|
|
|
indicate that only certain libraries should be built shared; for
|
|
|
|
|
example, --enable-shared=bfd. The only potential shared libraries in
|
|
|
|
|
a binutils release are bfd and opcodes.
|
|
|
|
|
|
|
|
|
|
The binutils will be linked against the shared libraries. The build
|
2001-07-19 12:43:13 +02:00
|
|
|
|
step will attempt to place the correct library in the run-time search
|
1999-05-03 09:29:11 +02:00
|
|
|
|
path for the binaries. However, in some cases, after you install the
|
|
|
|
|
binaries, you may have to set an environment variable, normally
|
|
|
|
|
LD_LIBRARY_PATH, so that the system can find the installed libbfd
|
|
|
|
|
shared library.
|
|
|
|
|
|
2009-07-14 09:43:18 +02:00
|
|
|
|
On hosts that support shared system libraries the binutils will be
|
|
|
|
|
linked against them. If you have static versions of the system
|
|
|
|
|
libraries installed as well and you wish to create static binaries
|
|
|
|
|
instead then use the LDFLAGS environment variable, like this:
|
|
|
|
|
|
|
|
|
|
../binutils-XXX/configure LDFLAGS="--static" [more options]
|
|
|
|
|
|
|
|
|
|
Note: the two dashes are important. The binutils make use of the
|
|
|
|
|
libtool script which has a special interpretation of "-static" when it
|
|
|
|
|
is in the LDFLAGS environment variable.
|
|
|
|
|
|
1999-05-03 09:29:11 +02:00
|
|
|
|
To build under openVMS/AXP, see the file makefile.vms in the top level
|
|
|
|
|
directory.
|
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
|
2003-02-24 17:37:13 +01:00
|
|
|
|
Native Language Support
|
|
|
|
|
=======================
|
|
|
|
|
|
|
|
|
|
By default Native Language Support will be enabled for binutils. On
|
|
|
|
|
some systems however this support is not present and can lead to error
|
|
|
|
|
messages such as "undefined reference to `libintl_gettext'" when
|
|
|
|
|
building there tools. If that happens the NLS support can be disabled
|
|
|
|
|
by adding the --disable-nls switch to the configure line like this:
|
|
|
|
|
|
|
|
|
|
../binutils-XXX/configure --disable-nls
|
|
|
|
|
|
|
|
|
|
|
1999-05-03 09:29:11 +02:00
|
|
|
|
If you don't have ar
|
|
|
|
|
====================
|
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
If your system does not already have an 'ar' program, the normal
|
1999-05-03 09:29:11 +02:00
|
|
|
|
binutils build process will not work. In this case, run configure as
|
|
|
|
|
usual. Before running make, run this script:
|
|
|
|
|
|
|
|
|
|
#!/bin/sh
|
|
|
|
|
MAKE_PROG="${MAKE-make}"
|
|
|
|
|
MAKE="${MAKE_PROG} AR=true LINK=true"
|
|
|
|
|
export MAKE
|
|
|
|
|
${MAKE} $* all-libiberty
|
|
|
|
|
${MAKE} $* all-intl
|
|
|
|
|
${MAKE} $* all-bfd
|
|
|
|
|
cd binutils
|
|
|
|
|
MAKE="${MAKE_PROG}"
|
|
|
|
|
export MAKE
|
2002-12-19 23:42:38 +01:00
|
|
|
|
${MAKE} $* ar_DEPENDENCIES= ar_LDADD='../bfd/*.o ../libiberty/*.o `if test -f ../intl/gettext.o; then echo '../intl/*.o'; fi`' ar
|
1999-05-03 09:29:11 +02:00
|
|
|
|
|
|
|
|
|
This script will build an ar program in binutils/ar. Move binutils/ar
|
|
|
|
|
into a directory on your PATH. After doing this, you can run make as
|
|
|
|
|
usual to build the complete binutils distribution. You do not need
|
|
|
|
|
the ranlib program in order to build the distribution.
|
|
|
|
|
|
|
|
|
|
Porting
|
|
|
|
|
=======
|
|
|
|
|
|
2003-02-24 17:37:13 +01:00
|
|
|
|
Binutils-2.13 supports many different architectures, but there
|
1999-05-03 09:29:11 +02:00
|
|
|
|
are many more not supported, including some that were supported
|
2001-07-19 12:43:13 +02:00
|
|
|
|
by earlier versions. We are hoping for volunteers to improve this
|
|
|
|
|
situation.
|
1999-05-03 09:29:11 +02:00
|
|
|
|
|
|
|
|
|
The major effort in porting binutils to a new host and/or target
|
|
|
|
|
architecture involves the BFD library. There is some documentation
|
|
|
|
|
in ../bfd/doc. The file ../gdb/doc/gdbint.texinfo (distributed
|
2002-03-08 07:05:18 +01:00
|
|
|
|
with gdb-5.x) may also be of help.
|
1999-05-03 09:29:11 +02:00
|
|
|
|
|
|
|
|
|
Reporting bugs
|
|
|
|
|
==============
|
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
Send bug reports and patches to:
|
|
|
|
|
|
2001-07-30 12:57:07 +02:00
|
|
|
|
bug-binutils@gnu.org.
|
2001-07-19 12:43:13 +02:00
|
|
|
|
|
2003-11-10 04:06:05 +01:00
|
|
|
|
Please include the following in bug reports:
|
|
|
|
|
|
|
|
|
|
- A description of exactly what went wrong, and exactly what should have
|
|
|
|
|
happened instead.
|
|
|
|
|
|
|
|
|
|
- The configuration name(s) given to the "configure" script. The
|
|
|
|
|
"config.status" file should have this information. This is assuming
|
|
|
|
|
you built binutils yourself. If you didn't build binutils youself,
|
|
|
|
|
then we need information regarding your machine and operating system,
|
|
|
|
|
and it may be more appropriate to report bugs to wherever you obtained
|
|
|
|
|
binutils.
|
|
|
|
|
|
|
|
|
|
- The options given to the tool (gas, objcopy, ld etc.) at run time.
|
|
|
|
|
|
|
|
|
|
- The actual input file that caused the problem.
|
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
Always mention the version number you are running; this is printed by
|
|
|
|
|
running any of the binutils with the --version option. We appreciate
|
2003-11-10 04:06:05 +01:00
|
|
|
|
reports about bugs, but we do not promise to fix them, particularly so
|
|
|
|
|
when the bug report is against an old version. If you are able, please
|
2013-08-12 22:04:37 +02:00
|
|
|
|
consider building the latest tools from git to check that your bug has
|
2003-11-10 04:06:05 +01:00
|
|
|
|
not already been fixed.
|
|
|
|
|
|
|
|
|
|
When reporting problems about gas and ld, it's useful to provide a
|
|
|
|
|
testcase that triggers the problem. In the case of a gas problem, we
|
|
|
|
|
want input files to gas and command line switches used. The inputs to
|
|
|
|
|
gas are _NOT_ .c or .i files, but rather .s files. If your original
|
|
|
|
|
source was a C program, you can generate the .s file and see the command
|
|
|
|
|
line options by passing -v -save-temps to gcc in addition to all the
|
|
|
|
|
usual options you use. The reason we don't want C files is that we
|
|
|
|
|
might not have a C compiler around for the target you use. While it
|
|
|
|
|
might be possible to build a compiler, that takes considerable time and
|
|
|
|
|
disk space, and we might not end up with exactly the same compiler you
|
|
|
|
|
use.
|
|
|
|
|
|
|
|
|
|
In the case of a ld problem, the input files are .o, .a and .so files,
|
|
|
|
|
and possibly a linker script specified with -T. Again, when using gcc
|
|
|
|
|
to link, you can see these files by adding options to the gcc command
|
|
|
|
|
line. Use -v -save-temps -Wl,-t, except that on targets that use gcc's
|
|
|
|
|
collect2, you would add -v -save-temps -Wl,-t,-debug. The -t option
|
|
|
|
|
tells ld to print all files and libraries used, so that, for example,
|
|
|
|
|
you can associate -lc on the ld command line with the actual libc used.
|
|
|
|
|
Note that your simple two line C program to trigger a problem typically
|
|
|
|
|
expands into several megabytes of objects by the time you include
|
|
|
|
|
libraries.
|
|
|
|
|
|
|
|
|
|
It is antisocial to post megabyte sized attachments to mailing lists, so
|
|
|
|
|
please put large testcases somewhere on an ftp or web site so that only
|
|
|
|
|
interested developers need to download them, or offer to email them on
|
|
|
|
|
request. Better still, try to reduce the testcase, for example, try to
|
|
|
|
|
develop a ld testcase that doesn't use system libraries. However,
|
|
|
|
|
please be sure it is a complete testcase and that it really does
|
|
|
|
|
demonstrate the problem. Also, don't bother paring it down if that will
|
|
|
|
|
cause large delays in filing the bug report.
|
|
|
|
|
|
|
|
|
|
If you expect to be contributing a large number of test cases, it would
|
|
|
|
|
be helpful if you would look at the test suite included in the release
|
|
|
|
|
(based on the Deja Gnu testing framework, available from the usual ftp
|
|
|
|
|
sites) and write test cases to fit into that framework. This is
|
|
|
|
|
certainly not required.
|
1999-05-03 09:29:11 +02:00
|
|
|
|
|
|
|
|
|
VMS
|
|
|
|
|
===
|
|
|
|
|
|
|
|
|
|
This section was written by Klaus K"ampf <kkaempf@rmi.de>. It
|
|
|
|
|
describes how to build and install the binutils on openVMS (Alpha and
|
|
|
|
|
Vax). (The BFD library only supports reading Vax object files.)
|
|
|
|
|
|
|
|
|
|
Compiling the release:
|
|
|
|
|
|
|
|
|
|
To compile the gnu binary utilities and the gnu assembler, you'll
|
|
|
|
|
need DEC C or GNU C for openVMS/Alpha. You'll need *both* compilers
|
|
|
|
|
on openVMS/Vax.
|
|
|
|
|
|
|
|
|
|
Compiling with either DEC C or GNU C works on openVMS/Alpha only. Some
|
|
|
|
|
of the opcodes and binutils files trap a bug in the DEC C optimizer,
|
|
|
|
|
so these files must be compiled with /noopt.
|
|
|
|
|
|
|
|
|
|
Compiling on openVMS/Vax is a bit complicated, as the bfd library traps
|
|
|
|
|
a bug in GNU C and the gnu assembler a bug in (my version of) DEC C.
|
|
|
|
|
|
|
|
|
|
I never tried compiling with VAX C.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
You further need GNU Make Version 3.76 or later. This is available
|
|
|
|
|
at ftp.progis.de or any GNU archive site. The makefiles assume that
|
|
|
|
|
gmake starts gnu make as a foreign command.
|
|
|
|
|
|
|
|
|
|
If you're compiling with DEC C or VAX C, you must run
|
|
|
|
|
|
|
|
|
|
$ @setup
|
|
|
|
|
|
|
|
|
|
before starting gnu-make. This isn't needed with GNU C.
|
|
|
|
|
|
|
|
|
|
On the Alpha you can choose the compiler by editing the toplevel
|
|
|
|
|
makefile.vms. Either select CC=cc (for DEC C) or CC=gcc (for GNU C)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Installing the release
|
|
|
|
|
|
|
|
|
|
Provided that your directory setup conforms to the GNU on openVMS
|
2001-07-19 12:43:13 +02:00
|
|
|
|
standard, you already have a concealed device named 'GNU_ROOT'.
|
1999-05-03 09:29:11 +02:00
|
|
|
|
In this case, a simple
|
|
|
|
|
|
|
|
|
|
$ gmake install
|
|
|
|
|
|
|
|
|
|
suffices to copy all programs and libraries to the proper directories.
|
|
|
|
|
|
|
|
|
|
Define the programs as foreign commands by adding these lines to your
|
|
|
|
|
login.com:
|
|
|
|
|
|
|
|
|
|
$ gas :== $GNU_ROOT:[bin]as.exe
|
|
|
|
|
$ size :== $GNU_ROOT:[bin]size.exe
|
|
|
|
|
$ nm :== $GNU_ROOT:[bin]nm.exe
|
|
|
|
|
$ objdump :== $GNU_ROOT:[bin]objdump.exe
|
|
|
|
|
$ strings :== $GNU_ROOT:[bin]strings.exe
|
|
|
|
|
|
|
|
|
|
If you have a different directory setup, copy the binary utilities
|
|
|
|
|
([.binutils]size.exe, [.binutils]nm.exe, [.binutils]objdump.exe,
|
|
|
|
|
and [.binutils]strings.exe) and the gnu assembler and preprocessor
|
|
|
|
|
([.gas]as.exe and [.gas]gasp.exe]) to a directory of your choice
|
|
|
|
|
and define all programs as foreign commands.
|
|
|
|
|
|
|
|
|
|
|
2001-07-19 12:43:13 +02:00
|
|
|
|
If you're satisfied with the compilation, you may want to remove
|
1999-05-03 09:29:11 +02:00
|
|
|
|
unneeded objects and libraries:
|
|
|
|
|
|
|
|
|
|
$ gmake clean
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If you have any problems or questions about the binutils on VMS, feel
|
|
|
|
|
free to mail me at kkaempf@rmi.de.
|
2012-12-17 17:56:12 +01:00
|
|
|
|
|
2014-03-05 12:46:15 +01:00
|
|
|
|
Copyright (C) 2012-2014 Free Software Foundation, Inc.
|
2012-12-17 17:56:12 +01:00
|
|
|
|
|
|
|
|
|
Copying and distribution of this file, with or without modification,
|
|
|
|
|
are permitted in any medium without royalty provided the copyright
|
|
|
|
|
notice and this notice are preserved.
|