README revision 89857
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.11.2 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 86If you don't have ar 87==================== 88 89If your system does not already have an 'ar' program, the normal 90binutils build process will not work. In this case, run configure as 91usual. Before running make, run this script: 92 93#!/bin/sh 94MAKE_PROG="${MAKE-make}" 95MAKE="${MAKE_PROG} AR=true LINK=true" 96export MAKE 97${MAKE} $* all-libiberty 98${MAKE} $* all-intl 99${MAKE} $* all-bfd 100cd binutils 101MAKE="${MAKE_PROG}" 102export MAKE 103${MAKE} $* ar_DEPENDENCIES= ar_LDADD='../bfd/*.o `cat ../libiberty/required-list ../libiberty/needed-list | sed -e "s,\([^ ][^ ]*\),../libiberty/\1,g"` `if test -f ../intl/gettext.o; then echo '../intl/*.o'; fi`' ar 104 105This script will build an ar program in binutils/ar. Move binutils/ar 106into a directory on your PATH. After doing this, you can run make as 107usual to build the complete binutils distribution. You do not need 108the ranlib program in order to build the distribution. 109 110Porting 111======= 112 113Binutils-2.11 supports many different architectures, but there 114are many more not supported, including some that were supported 115by earlier versions. We are hoping for volunteers to improve this 116situation. 117 118The major effort in porting binutils to a new host and/or target 119architecture involves the BFD library. There is some documentation 120in ../bfd/doc. The file ../gdb/doc/gdbint.texinfo (distributed 121with gdb-4.x) may also be of help. 122 123Reporting bugs 124============== 125 126Send bug reports and patches to: 127 128 bug-binutils@gnu.org. 129 130Always mention the version number you are running; this is printed by 131running any of the binutils with the --version option. We appreciate 132reports about bugs, but we do not promise to fix them. 133 134VMS 135=== 136 137This section was written by Klaus K"ampf <kkaempf@rmi.de>. It 138describes how to build and install the binutils on openVMS (Alpha and 139Vax). (The BFD library only supports reading Vax object files.) 140 141Compiling the release: 142 143To compile the gnu binary utilities and the gnu assembler, you'll 144need DEC C or GNU C for openVMS/Alpha. You'll need *both* compilers 145on openVMS/Vax. 146 147Compiling with either DEC C or GNU C works on openVMS/Alpha only. Some 148of the opcodes and binutils files trap a bug in the DEC C optimizer, 149so these files must be compiled with /noopt. 150 151Compiling on openVMS/Vax is a bit complicated, as the bfd library traps 152a bug in GNU C and the gnu assembler a bug in (my version of) DEC C. 153 154I never tried compiling with VAX C. 155 156 157You further need GNU Make Version 3.76 or later. This is available 158at ftp.progis.de or any GNU archive site. The makefiles assume that 159gmake starts gnu make as a foreign command. 160 161If you're compiling with DEC C or VAX C, you must run 162 163 $ @setup 164 165before starting gnu-make. This isn't needed with GNU C. 166 167On the Alpha you can choose the compiler by editing the toplevel 168makefile.vms. Either select CC=cc (for DEC C) or CC=gcc (for GNU C) 169 170 171Installing the release 172 173Provided that your directory setup conforms to the GNU on openVMS 174standard, you already have a concealed device named 'GNU_ROOT'. 175In this case, a simple 176 177 $ gmake install 178 179suffices to copy all programs and libraries to the proper directories. 180 181Define the programs as foreign commands by adding these lines to your 182login.com: 183 184 $ gas :== $GNU_ROOT:[bin]as.exe 185 $ size :== $GNU_ROOT:[bin]size.exe 186 $ nm :== $GNU_ROOT:[bin]nm.exe 187 $ objdump :== $GNU_ROOT:[bin]objdump.exe 188 $ strings :== $GNU_ROOT:[bin]strings.exe 189 190If you have a different directory setup, copy the binary utilities 191([.binutils]size.exe, [.binutils]nm.exe, [.binutils]objdump.exe, 192and [.binutils]strings.exe) and the gnu assembler and preprocessor 193([.gas]as.exe and [.gas]gasp.exe]) to a directory of your choice 194and define all programs as foreign commands. 195 196 197If you're satisfied with the compilation, you may want to remove 198unneeded objects and libraries: 199 200 $ gmake clean 201 202 203If you have any problems or questions about the binutils on VMS, feel 204free to mail me at kkaempf@rmi.de. 205