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