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 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-2014 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.