contrib/binutils/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.12 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 To build under openVMS/AXP, see the file makefile.vms in the top level
  83 directory.
  84
  85
  86 If you don't have ar
  87 ====================
  88
  89 If your system does not already have an 'ar' program, the normal
  90 binutils build process will not work.  In this case, run configure as
  91 usual.  Before running make, run this script:
  92
  93 #!/bin/sh
  94 MAKE_PROG="${MAKE-make}"
  95 MAKE="${MAKE_PROG} AR=true LINK=true"
  96 export MAKE
  97 ${MAKE} $* all-libiberty
  98 ${MAKE} $* all-intl
  99 ${MAKE} $* all-bfd
 100 cd binutils
 101 MAKE="${MAKE_PROG}"
 102 export MAKE
 103 ${MAKE} $* ar_DEPENDENCIES= ar_LDADD='../bfd/*.o `cat ../libiberty/required-list ../libiberty/needed-list | sed -e "s,\([^ ][^ ]*\),../libiberty/\1,g"` `if test -f ../intl/gettext.o; then echo '../intl/*.o'; fi`' ar
 104
 105 This script will build an ar program in binutils/ar.  Move binutils/ar
 106 into a directory on your PATH.  After doing this, you can run make as
 107 usual to build the complete binutils distribution.  You do not need
 108 the ranlib program in order to build the distribution.
 109
 110 Porting
 111 =======
 112
 113 Binutils-2.12 supports many different architectures, but there
 114 are many more not supported, including some that were supported
 115 by earlier versions.  We are hoping for volunteers to improve this
 116 situation.
 117
 118 The major effort in porting binutils to a new host and/or target
 119 architecture involves the BFD library.  There is some documentation
 120 in ../bfd/doc.  The file ../gdb/doc/gdbint.texinfo (distributed
 121 with gdb-5.x) may also be of help.
 122
 123 Reporting bugs
 124 ==============
 125
 126 Send bug reports and patches to:
 127
 128    bug-binutils@gnu.org.
 129
 130 Always mention the version number you are running; this is printed by
 131 running any of the binutils with the --version option.  We appreciate
 132 reports about bugs, but we do not promise to fix them.
 133
 134 VMS
 135 ===
 136
 137 This section was written by Klaus K"ampf <kkaempf@rmi.de>.  It
 138 describes how to build and install the binutils on openVMS (Alpha and
 139 Vax).  (The BFD library only supports reading Vax object files.)
 140
 141 Compiling the release:
 142
 143 To compile the gnu binary utilities and the gnu assembler, you'll
 144 need DEC C or GNU C for openVMS/Alpha. You'll need *both* compilers
 145 on openVMS/Vax.
 146
 147 Compiling with either DEC C or GNU C works on openVMS/Alpha only. Some
 148 of the opcodes and binutils files trap a bug in the DEC C optimizer,
 149 so these files must be compiled with /noopt.
 150
 151 Compiling on openVMS/Vax is a bit complicated, as the bfd library traps
 152 a bug in GNU C and the gnu assembler a bug in (my version of) DEC C.
 153
 154 I never tried compiling with VAX C.
 155
 156
 157 You further need GNU Make Version 3.76 or later. This is available
 158 at ftp.progis.de or any GNU archive site. The makefiles assume that
 159 gmake starts gnu make as a foreign command.
 160
 161 If you're compiling with DEC C or VAX C, you must run
 162
 163   $ @setup
 164
 165 before starting gnu-make. This isn't needed with GNU C.
 166
 167 On the Alpha you can choose the compiler by editing the toplevel
 168 makefile.vms. Either select CC=cc (for DEC C) or CC=gcc (for GNU C)
 169
 170
 171 Installing the release
 172
 173 Provided that your directory setup conforms to the GNU on openVMS
 174 standard, you already have a concealed device named 'GNU_ROOT'.
 175 In this case, a simple
 176
 177  $ gmake install
 178
 179 suffices to copy all programs and libraries to the proper directories.
 180
 181 Define the programs as foreign commands by adding these lines to your
 182 login.com:
 183
 184   $ gas :== $GNU_ROOT:[bin]as.exe
 185   $ size :== $GNU_ROOT:[bin]size.exe
 186   $ nm :== $GNU_ROOT:[bin]nm.exe
 187   $ objdump :== $GNU_ROOT:[bin]objdump.exe
 188   $ strings :== $GNU_ROOT:[bin]strings.exe
 189
 190 If you have a different directory setup, copy the binary utilities
 191 ([.binutils]size.exe, [.binutils]nm.exe, [.binutils]objdump.exe,
 192 and [.binutils]strings.exe) and the gnu assembler and preprocessor
 193 ([.gas]as.exe and [.gas]gasp.exe]) to a directory of your choice
 194 and define all programs as foreign commands.
 195
 196
 197 If you're satisfied with the compilation, you may want to remove
 198 unneeded objects and libraries:
 199
 200   $ gmake clean
 201
 202
 203 If you have any problems or questions about the binutils on VMS, feel
 204 free to mail me at kkaempf@rmi.de.