binutils/README

   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 On hosts that support shared system libraries the binutils will be
  83 linked against them.  If you have static versions of the system
  84 libraries installed as well and you wish to create static binaries
  85 instead then use the LDFLAGS environment variable,  like this:
  86
  87   ../binutils-XXX/configure LDFLAGS="--static" [more options]
  88
  89 Note: the two dashes are important.  The binutils make use of the
  90 libtool script which has a special interpretation of "-static" when it
  91 is in the LDFLAGS environment variable.
  92
  93 To build under openVMS/AXP, see the file makefile.vms in the top level
  94 directory.
  95
  96
  97 Native Language Support
  98 =======================
  99
 100 By default Native Language Support will be enabled for binutils.  On
 101 some systems however this support is not present and can lead to error
 102 messages such as "undefined reference to `libintl_gettext'" when
 103 building there tools.  If that happens the NLS support can be disabled
 104 by adding the --disable-nls switch to the configure line like this:
 105
 106         ../binutils-XXX/configure --disable-nls
 107
 108
 109 If you don't have ar
 110 ====================
 111
 112 If your system does not already have an 'ar' program, the normal
 113 binutils build process will not work.  In this case, run configure as
 114 usual.  Before running make, run this script:
 115
 116 #!/bin/sh
 117 MAKE_PROG="${MAKE-make}"
 118 MAKE="${MAKE_PROG} AR=true LINK=true"
 119 export MAKE
 120 ${MAKE} $* all-libiberty
 121 ${MAKE} $* all-intl
 122 ${MAKE} $* all-bfd
 123 cd binutils
 124 MAKE="${MAKE_PROG}"
 125 export MAKE
 126 ${MAKE} $* ar_DEPENDENCIES= ar_LDADD='../bfd/*.o ../libiberty/*.o `if test -f ../intl/gettext.o; then echo '../intl/*.o'; fi`' ar
 127
 128 This script will build an ar program in binutils/ar.  Move binutils/ar
 129 into a directory on your PATH.  After doing this, you can run make as
 130 usual to build the complete binutils distribution.  You do not need
 131 the ranlib program in order to build the distribution.
 132
 133 Porting
 134 =======
 135
 136 Binutils-2.13 supports many different architectures, but there
 137 are many more not supported, including some that were supported
 138 by earlier versions.  We are hoping for volunteers to improve this
 139 situation.
 140
 141 The major effort in porting binutils to a new host and/or target
 142 architecture involves the BFD library.  There is some documentation
 143 in ../bfd/doc.  The file ../gdb/doc/gdbint.texinfo (distributed
 144 with gdb-5.x) may also be of help.
 145
 146 Reporting bugs
 147 ==============
 148
 149 Send bug reports and patches to:
 150
 151    bug-binutils@gnu.org.
 152
 153 Please include the following in bug reports:
 154
 155 - A description of exactly what went wrong, and exactly what should have
 156   happened instead.
 157
 158 - The configuration name(s) given to the "configure" script.  The
 159   "config.status" file should have this information.  This is assuming
 160   you built binutils yourself.  If you didn't build binutils youself,
 161   then we need information regarding your machine and operating system,
 162   and it may be more appropriate to report bugs to wherever you obtained
 163   binutils.
 164
 165 - The options given to the tool (gas, objcopy, ld etc.) at run time.
 166
 167 - The actual input file that caused the problem.
 168
 169 Always mention the version number you are running; this is printed by
 170 running any of the binutils with the --version option.  We appreciate
 171 reports about bugs, but we do not promise to fix them, particularly so
 172 when the bug report is against an old version.  If you are able, please
 173 consider building the latest tools from CVS to check that your bug has
 174 not already been fixed.
 175
 176 When reporting problems about gas and ld, it's useful to provide a
 177 testcase that triggers the problem.  In the case of a gas problem, we
 178 want input files to gas and command line switches used.  The inputs to
 179 gas are _NOT_ .c or .i files, but rather .s files.  If your original
 180 source was a C program, you can generate the .s file and see the command
 181 line options by passing -v -save-temps to gcc in addition to all the
 182 usual options you use.  The reason we don't want C files is that we
 183 might not have a C compiler around for the target you use.  While it
 184 might be possible to build a compiler, that takes considerable time and
 185 disk space, and we might not end up with exactly the same compiler you
 186 use.
 187
 188 In the case of a ld problem, the input files are .o, .a and .so files,
 189 and possibly a linker script specified with -T.  Again, when using gcc
 190 to link, you can see these files by adding options to the gcc command
 191 line.  Use -v -save-temps -Wl,-t, except that on targets that use gcc's
 192 collect2, you would add -v -save-temps -Wl,-t,-debug.  The -t option
 193 tells ld to print all files and libraries used, so that, for example,
 194 you can associate -lc on the ld command line with the actual libc used.
 195 Note that your simple two line C program to trigger a problem typically
 196 expands into several megabytes of objects by the time you include
 197 libraries.
 198
 199 It is antisocial to post megabyte sized attachments to mailing lists, so
 200 please put large testcases somewhere on an ftp or web site so that only
 201 interested developers need to download them, or offer to email them on
 202 request.  Better still, try to reduce the testcase, for example, try to
 203 develop a ld testcase that doesn't use system libraries.  However,
 204 please be sure it is a complete testcase and that it really does
 205 demonstrate the problem.  Also, don't bother paring it down if that will
 206 cause large delays in filing the bug report.
 207
 208 If you expect to be contributing a large number of test cases, it would
 209 be helpful if you would look at the test suite included in the release
 210 (based on the Deja Gnu testing framework, available from the usual ftp
 211 sites) and write test cases to fit into that framework.  This is
 212 certainly not required.
 213
 214 VMS
 215 ===
 216
 217 This section was written by Klaus K"ampf <kkaempf@rmi.de>.  It
 218 describes how to build and install the binutils on openVMS (Alpha and
 219 Vax).  (The BFD library only supports reading Vax object files.)
 220
 221 Compiling the release:
 222
 223 To compile the gnu binary utilities and the gnu assembler, you'll
 224 need DEC C or GNU C for openVMS/Alpha. You'll need *both* compilers
 225 on openVMS/Vax.
 226
 227 Compiling with either DEC C or GNU C works on openVMS/Alpha only. Some
 228 of the opcodes and binutils files trap a bug in the DEC C optimizer,
 229 so these files must be compiled with /noopt.
 230
 231 Compiling on openVMS/Vax is a bit complicated, as the bfd library traps
 232 a bug in GNU C and the gnu assembler a bug in (my version of) DEC C.
 233
 234 I never tried compiling with VAX C.
 235
 236
 237 You further need GNU Make Version 3.76 or later. This is available
 238 at ftp.progis.de or any GNU archive site. The makefiles assume that
 239 gmake starts gnu make as a foreign command.
 240
 241 If you're compiling with DEC C or VAX C, you must run
 242
 243   $ @setup
 244
 245 before starting gnu-make. This isn't needed with GNU C.
 246
 247 On the Alpha you can choose the compiler by editing the toplevel
 248 makefile.vms. Either select CC=cc (for DEC C) or CC=gcc (for GNU C)
 249
 250
 251 Installing the release
 252
 253 Provided that your directory setup conforms to the GNU on openVMS
 254 standard, you already have a concealed device named 'GNU_ROOT'.
 255 In this case, a simple
 256
 257  $ gmake install
 258
 259 suffices to copy all programs and libraries to the proper directories.
 260
 261 Define the programs as foreign commands by adding these lines to your
 262 login.com:
 263
 264   $ gas :== $GNU_ROOT:[bin]as.exe
 265   $ size :== $GNU_ROOT:[bin]size.exe
 266   $ nm :== $GNU_ROOT:[bin]nm.exe
 267   $ objdump :== $GNU_ROOT:[bin]objdump.exe
 268   $ strings :== $GNU_ROOT:[bin]strings.exe
 269
 270 If you have a different directory setup, copy the binary utilities
 271 ([.binutils]size.exe, [.binutils]nm.exe, [.binutils]objdump.exe,
 272 and [.binutils]strings.exe) and the gnu assembler and preprocessor
 273 ([.gas]as.exe and [.gas]gasp.exe]) to a directory of your choice
 274 and define all programs as foreign commands.
 275
 276
 277 If you're satisfied with the compilation, you may want to remove
 278 unneeded objects and libraries:
 279
 280   $ gmake clean
 281
 282
 283 If you have any problems or questions about the binutils on VMS, feel
 284 free to mail me at kkaempf@rmi.de.