189857Sobrien README for BINUTILS 289857Sobrien 338889SjdpThese are the GNU binutils. These are utilities of use when dealing 489857Sobrienwith binary files, either object files or executables. These tools 589857Sobrienconsist of the linker (ld), the assembler (gas), and the profiler 689857Sobrien(gprof) each of which have their own sub-directory named after them. 789857SobrienThere is also a collection of other binary tools, including the 889857Sobriendisassembler (objdump) in this directory. These tools make use of a 989857Sobrienpair of libraries (bfd and opcodes) and a common set of header files 1089857Sobrien(include). 1133965Sjdp 1289857SobrienThere are README and NEWS files in most of the program sub-directories 1389857Sobrienwhich give more information about those specific programs. 1433965Sjdp 1533965Sjdp 1633965SjdpUnpacking and Installation -- quick overview 1733965Sjdp============================================ 1833965Sjdp 1989857SobrienWhen you unpack the binutils archive file, you will get a directory 2089857Sobriencalled something like `binutils-XXX', where XXX is the number of the 21130561Sobrienrelease. (Probably 2.13 or higher). This directory contains 2289857Sobrienvarious files and sub-directories. Most of the files in the top 2389857Sobriendirectory are for information and for configuration. The actual 2489857Sobriensource code is in sub-directories. 2533965Sjdp 2633965SjdpTo build binutils, you can just do: 2733965Sjdp 2889857Sobrien cd binutils-XXX 2938889Sjdp ./configure [options] 3033965Sjdp make 3133965Sjdp make install # copies the programs files into /usr/local/bin 3233965Sjdp # by default. 3333965Sjdp 3433965SjdpThis will configure and build all the libraries as well as the 3533965Sjdpassembler, the binutils, and the linker. 3633965Sjdp 3738889SjdpIf you have GNU make, we recommend building in a different directory: 3833965Sjdp 3938889Sjdp mkdir objdir 4038889Sjdp cd objdir 4189857Sobrien ../binutils-XXX/configure [options] 4238889Sjdp make 4338889Sjdp make install 4438889Sjdp 4538889SjdpThis relies on the VPATH feature of GNU make. 4638889Sjdp 4738889SjdpBy default, the binutils will be configured to support the system on 4838889Sjdpwhich they are built. When doing cross development, use the --target 4989857Sobrienconfigure option to specify a different target, eg: 5038889Sjdp 5189857Sobrien ./configure --target=foo-elf 5289857Sobrien 5338889SjdpThe --enable-targets option adds support for more binary file formats 5438889Sjdpbesides the default. List them as the argument to --enable-targets, 5538889Sjdpseparated by commas. For example: 5638889Sjdp 5733965Sjdp ./configure --enable-targets=sun3,rs6000-aix,decstation 5833965Sjdp 5989857SobrienThe name 'all' compiles in support for all valid BFD targets: 6033965Sjdp 6133965Sjdp ./configure --enable-targets=all 6233965Sjdp 6389857SobrienOn 32-bit hosts though, this support will be restricted to 32-bit 6489857Sobrientarget unless the --enable-64-bit-bfd option is also used: 6589857Sobrien 6689857Sobrien ./configure --enable-64-bit-bfd --enable-targets=all 6789857Sobrien 6833965SjdpYou can also specify the --enable-shared option when you run 6933965Sjdpconfigure. This will build the BFD and opcodes libraries as shared 7038889Sjdplibraries. You can use arguments with the --enable-shared option to 7138889Sjdpindicate that only certain libraries should be built shared; for 7238889Sjdpexample, --enable-shared=bfd. The only potential shared libraries in 7338889Sjdpa binutils release are bfd and opcodes. 7433965Sjdp 7533965SjdpThe binutils will be linked against the shared libraries. The build 7689857Sobrienstep will attempt to place the correct library in the run-time search 7733965Sjdppath for the binaries. However, in some cases, after you install the 7833965Sjdpbinaries, you may have to set an environment variable, normally 7933965SjdpLD_LIBRARY_PATH, so that the system can find the installed libbfd 8033965Sjdpshared library. 8133965Sjdp 8233965SjdpTo build under openVMS/AXP, see the file makefile.vms in the top level 8333965Sjdpdirectory. 8433965Sjdp 8589857Sobrien 86130561SobrienNative Language Support 87130561Sobrien======================= 88130561Sobrien 89130561SobrienBy default Native Language Support will be enabled for binutils. On 90130561Sobriensome systems however this support is not present and can lead to error 91130561Sobrienmessages such as "undefined reference to `libintl_gettext'" when 92130561Sobrienbuilding there tools. If that happens the NLS support can be disabled 93130561Sobrienby adding the --disable-nls switch to the configure line like this: 94130561Sobrien 95130561Sobrien ../binutils-XXX/configure --disable-nls 96130561Sobrien 97130561Sobrien 9833965SjdpIf you don't have ar 9933965Sjdp==================== 10033965Sjdp 10189857SobrienIf your system does not already have an 'ar' program, the normal 10233965Sjdpbinutils build process will not work. In this case, run configure as 10333965Sjdpusual. Before running make, run this script: 10433965Sjdp 10533965Sjdp#!/bin/sh 10660484SobrienMAKE_PROG="${MAKE-make}" 10760484SobrienMAKE="${MAKE_PROG} AR=true LINK=true" 10860484Sobrienexport MAKE 10960484Sobrien${MAKE} $* all-libiberty 11060484Sobrien${MAKE} $* all-intl 11160484Sobrien${MAKE} $* all-bfd 11233965Sjdpcd binutils 11360484SobrienMAKE="${MAKE_PROG}" 11460484Sobrienexport MAKE 115130561Sobrien${MAKE} $* ar_DEPENDENCIES= ar_LDADD='../bfd/*.o ../libiberty/*.o `if test -f ../intl/gettext.o; then echo '../intl/*.o'; fi`' ar 11633965Sjdp 11733965SjdpThis script will build an ar program in binutils/ar. Move binutils/ar 11833965Sjdpinto a directory on your PATH. After doing this, you can run make as 11933965Sjdpusual to build the complete binutils distribution. You do not need 12033965Sjdpthe ranlib program in order to build the distribution. 12133965Sjdp 12233965SjdpPorting 12333965Sjdp======= 12438889Sjdp 125130561SobrienBinutils-2.13 supports many different architectures, but there 12633965Sjdpare many more not supported, including some that were supported 12789857Sobrienby earlier versions. We are hoping for volunteers to improve this 12889857Sobriensituation. 12933965Sjdp 13033965SjdpThe major effort in porting binutils to a new host and/or target 13133965Sjdparchitecture involves the BFD library. There is some documentation 13233965Sjdpin ../bfd/doc. The file ../gdb/doc/gdbint.texinfo (distributed 13392828Sobrienwith gdb-5.x) may also be of help. 13433965Sjdp 13533965SjdpReporting bugs 13633965Sjdp============== 13738889Sjdp 13889857SobrienSend bug reports and patches to: 13938889Sjdp 14089857Sobrien bug-binutils@gnu.org. 14189857Sobrien 142130561SobrienPlease include the following in bug reports: 143130561Sobrien 144130561Sobrien- A description of exactly what went wrong, and exactly what should have 145130561Sobrien happened instead. 146130561Sobrien 147130561Sobrien- The configuration name(s) given to the "configure" script. The 148130561Sobrien "config.status" file should have this information. This is assuming 149130561Sobrien you built binutils yourself. If you didn't build binutils youself, 150130561Sobrien then we need information regarding your machine and operating system, 151130561Sobrien and it may be more appropriate to report bugs to wherever you obtained 152130561Sobrien binutils. 153130561Sobrien 154130561Sobrien- The options given to the tool (gas, objcopy, ld etc.) at run time. 155130561Sobrien 156130561Sobrien- The actual input file that caused the problem. 157130561Sobrien 15889857SobrienAlways mention the version number you are running; this is printed by 15989857Sobrienrunning any of the binutils with the --version option. We appreciate 160130561Sobrienreports about bugs, but we do not promise to fix them, particularly so 161130561Sobrienwhen the bug report is against an old version. If you are able, please 162130561Sobrienconsider building the latest tools from CVS to check that your bug has 163130561Sobriennot already been fixed. 16489857Sobrien 165130561SobrienWhen reporting problems about gas and ld, it's useful to provide a 166130561Sobrientestcase that triggers the problem. In the case of a gas problem, we 167130561Sobrienwant input files to gas and command line switches used. The inputs to 168130561Sobriengas are _NOT_ .c or .i files, but rather .s files. If your original 169130561Sobriensource was a C program, you can generate the .s file and see the command 170130561Sobrienline options by passing -v -save-temps to gcc in addition to all the 171130561Sobrienusual options you use. The reason we don't want C files is that we 172130561Sobrienmight not have a C compiler around for the target you use. While it 173130561Sobrienmight be possible to build a compiler, that takes considerable time and 174130561Sobriendisk space, and we might not end up with exactly the same compiler you 175130561Sobrienuse. 176130561Sobrien 177130561SobrienIn the case of a ld problem, the input files are .o, .a and .so files, 178130561Sobrienand possibly a linker script specified with -T. Again, when using gcc 179130561Sobriento link, you can see these files by adding options to the gcc command 180130561Sobrienline. Use -v -save-temps -Wl,-t, except that on targets that use gcc's 181130561Sobriencollect2, you would add -v -save-temps -Wl,-t,-debug. The -t option 182130561Sobrientells ld to print all files and libraries used, so that, for example, 183130561Sobrienyou can associate -lc on the ld command line with the actual libc used. 184130561SobrienNote that your simple two line C program to trigger a problem typically 185130561Sobrienexpands into several megabytes of objects by the time you include 186130561Sobrienlibraries. 187130561Sobrien 188130561SobrienIt is antisocial to post megabyte sized attachments to mailing lists, so 189130561Sobrienplease put large testcases somewhere on an ftp or web site so that only 190130561Sobrieninterested developers need to download them, or offer to email them on 191130561Sobrienrequest. Better still, try to reduce the testcase, for example, try to 192130561Sobriendevelop a ld testcase that doesn't use system libraries. However, 193130561Sobrienplease be sure it is a complete testcase and that it really does 194130561Sobriendemonstrate the problem. Also, don't bother paring it down if that will 195130561Sobriencause large delays in filing the bug report. 196130561Sobrien 197130561SobrienIf you expect to be contributing a large number of test cases, it would 198130561Sobrienbe helpful if you would look at the test suite included in the release 199130561Sobrien(based on the Deja Gnu testing framework, available from the usual ftp 200130561Sobriensites) and write test cases to fit into that framework. This is 201130561Sobriencertainly not required. 202130561Sobrien 20360484SobrienVMS 20460484Sobrien=== 20538889Sjdp 20660484SobrienThis section was written by Klaus K"ampf <kkaempf@rmi.de>. It 20760484Sobriendescribes how to build and install the binutils on openVMS (Alpha and 20860484SobrienVax). (The BFD library only supports reading Vax object files.) 20938889Sjdp 21060484SobrienCompiling the release: 21138889Sjdp 21260484SobrienTo compile the gnu binary utilities and the gnu assembler, you'll 21360484Sobrienneed DEC C or GNU C for openVMS/Alpha. You'll need *both* compilers 21460484Sobrienon openVMS/Vax. 21560484Sobrien 21660484SobrienCompiling with either DEC C or GNU C works on openVMS/Alpha only. Some 21760484Sobrienof the opcodes and binutils files trap a bug in the DEC C optimizer, 21860484Sobrienso these files must be compiled with /noopt. 21960484Sobrien 22060484SobrienCompiling on openVMS/Vax is a bit complicated, as the bfd library traps 22160484Sobriena bug in GNU C and the gnu assembler a bug in (my version of) DEC C. 22260484Sobrien 22360484SobrienI never tried compiling with VAX C. 22460484Sobrien 22560484Sobrien 22660484SobrienYou further need GNU Make Version 3.76 or later. This is available 22760484Sobrienat ftp.progis.de or any GNU archive site. The makefiles assume that 22860484Sobriengmake starts gnu make as a foreign command. 22960484Sobrien 23060484SobrienIf you're compiling with DEC C or VAX C, you must run 23160484Sobrien 23260484Sobrien $ @setup 23360484Sobrien 23460484Sobrienbefore starting gnu-make. This isn't needed with GNU C. 23560484Sobrien 23660484SobrienOn the Alpha you can choose the compiler by editing the toplevel 23760484Sobrienmakefile.vms. Either select CC=cc (for DEC C) or CC=gcc (for GNU C) 23860484Sobrien 23960484Sobrien 24060484SobrienInstalling the release 24160484Sobrien 24260484SobrienProvided that your directory setup conforms to the GNU on openVMS 24389857Sobrienstandard, you already have a concealed device named 'GNU_ROOT'. 24460484SobrienIn this case, a simple 24560484Sobrien 24660484Sobrien $ gmake install 24760484Sobrien 24860484Sobriensuffices to copy all programs and libraries to the proper directories. 24960484Sobrien 25060484SobrienDefine the programs as foreign commands by adding these lines to your 25160484Sobrienlogin.com: 25260484Sobrien 25360484Sobrien $ gas :== $GNU_ROOT:[bin]as.exe 25460484Sobrien $ size :== $GNU_ROOT:[bin]size.exe 25560484Sobrien $ nm :== $GNU_ROOT:[bin]nm.exe 25660484Sobrien $ objdump :== $GNU_ROOT:[bin]objdump.exe 25760484Sobrien $ strings :== $GNU_ROOT:[bin]strings.exe 25860484Sobrien 25960484SobrienIf you have a different directory setup, copy the binary utilities 26060484Sobrien([.binutils]size.exe, [.binutils]nm.exe, [.binutils]objdump.exe, 26160484Sobrienand [.binutils]strings.exe) and the gnu assembler and preprocessor 26260484Sobrien([.gas]as.exe and [.gas]gasp.exe]) to a directory of your choice 26360484Sobrienand define all programs as foreign commands. 26460484Sobrien 26560484Sobrien 26689857SobrienIf you're satisfied with the compilation, you may want to remove 26760484Sobrienunneeded objects and libraries: 26860484Sobrien 26960484Sobrien $ gmake clean 27060484Sobrien 27160484Sobrien 27260484SobrienIf you have any problems or questions about the binutils on VMS, feel 27360484Sobrienfree to mail me at kkaempf@rmi.de. 274