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