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