| 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 | bug-binutils@gnu.org. |
| 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 <kkaempf@rmi.de>. 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 kkaempf@rmi.de. |
| 294 | \f |
| 295 | Copyright (C) 2012-2015 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. |