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