binutils/README

   1 This is a beta release of a completely rewritten binutils distribution.
   2 (Rewritten since binutils 1.x, that is.)
   3
   4 The linker (ld) has been moved into a separate directory, which should be
   5 ../ld.  Linker-specific notes are in ../ld/README.
   6
   7 As of version 2.5, the assembler (as) is also included in this package, in
   8 ../gas.  Assembler-specific notes can be found in ../gas/README.
   9
  10 These programs have been tested on various architectures.
  11 However, since this is a beta release taken directly from an
  12 evolving source tree, there might be some problems.  In particular,
  13 the programs have not been ported to as many machines as the
  14 old binutils.  There are also features of the old versions
  15 that are missing on the new programs.  We would appreciate
  16 patches to make things run on other machines; especially welcome
  17 are fixes for what used to work on the old programs!
  18 (See ./TODO, as well a ../bfd/TODO and ../ld/TODO.)
  19
  20 Recent changes are in ./NEWS, ../ld/NEWS, and ../gas/NEWS.
  21
  22 Unpacking and Installation -- quick overview
  23 ==========================
  24
  25 In this release, the binary utilities, the linker, the generic GNU include
  26 files, the BFD ("binary file description") library, gprof, and getopt all
  27 have directories of their own underneath the binutils-2.7 directory.
  28 The idea is that a variety of GNU tools can
  29 share a common copy of these things.  Configuration scripts and
  30 makefiles exist to cruise up and down this directory tree and
  31 automatically build all the pieces in the right order.
  32
  33 When you unpack the binutils-2.7.tar.gz file, you'll get a directory
  34 called something like `binutils-2.7', which contains:
  35
  36         COPYING          bfd/             configure*       libiberty/
  37         COPYING.LIB      binutils/        configure.in     move-if-change*
  38         CYGNUS           build-all.mk     etc/             opcodes/
  39         ChangeLog        config/          gprof/           test-build.mk
  40         Makefile.in      config.guess*    inc
  41
  42 To build binutils, you can just do:
  43
  44         cd binutils-2.7
  45         ./configure [ --enable-targets='target1,target2...' ]
  46         make
  47         make install # copies the programs files into /usr/local/bin
  48                      # by default.
  49
  50 This will configure and build all the libraries as well as binutils
  51 and the linker.
  52
  53 The --enable-targets option adds support for more binary file
  54 formats besides the default.  By default, support for only the
  55 selected target file format is compiled in.  To add support for more
  56 formats, list them as the argument to --enable-targets, separated by
  57 commas.  For example:
  58
  59         ./configure --enable-targets=sun3,rs6000-aix,decstation
  60
  61 The name 'all' compiles in support for all valid BFD targets (this was
  62 the default in previous releases):
  63
  64         ./configure --enable-targets=all
  65
  66 The binutils can be used in a cross-development environment.
  67 The file etc/configure.texi contains more information.
  68
  69 You can also specify the --enable-shared option when you run
  70 configure.  This will build the BFD and opcodes libraries as shared
  71 libraries.  This will only work on certain systems, and currently will
  72 only work when compiling with gcc.  You can use arguments with the
  73 --enable-shared option to indicate that only certain libraries should
  74 be built shared; for example, --enable-shared=bfd.  The only
  75 possibilities in a binutils release are bfd and opcodes.
  76
  77 The binutils will be linked against the shared libraries.  The build
  78 step will attempt to place the correct library in the runtime search
  79 path for the binaries.  However, in some cases, after you install the
  80 binaries, you may have to set an environment variable, normally
  81 LD_LIBRARY_PATH, so that the system can find the installed libbfd
  82 shared library.
  83
  84 If you specify --enable-commonbfdlib as well as --enable-shared, then
  85 a single shared library will be built containing the bfd, opcodes, and
  86 libiberty libraries.  It will be installed as libbfd.  This option
  87 will make the binutils programs as small as possible.
  88
  89 If you don't have ar
  90 ====================
  91
  92 If your system does not already have an ar program, the normal
  93 binutils build process will not work.  In this case, run configure as
  94 usual.  Before running make, run this script:
  95
  96 #!/bin/sh
  97 MAKE=${MAKE-make}
  98 ${MAKE} $* AR=true all-libiberty
  99 ${MAKE} $* AR=true all-bfd
 100 cd binutils
 101 ${MAKE} $* ADDL_DEPS='$(BULIBS)' ADDL_LIBS='$(BULIBS) ../bfd/*.o `cat ../libiberty/required-list ../libiberty/needed-list | sed -e "s,\([^ ][^ ]*\),../libiberty/\1,g"`' ar
 102
 103 This script will build an ar program in binutils/ar.  Move binutils/ar
 104 into a directory on your PATH.  After doing this, you can run make as
 105 usual to build the complete binutils distribution.  You do not need
 106 the ranlib program in order to build the distribution.
 107
 108 Porting
 109 =======
 110 Binutils-2.7 supports many different architectures, but there
 111 are many more not supported, including some that were supported
 112 by earlier versions.  We are hoping for volunteers to
 113 improve this situation.
 114
 115 The major effort in porting binutils to a new host and/or target
 116 architecture involves the BFD library.  There is some documentation
 117 in ../bfd/doc.  The file ../gdb/doc/gdbint.texinfo (distributed
 118 with gdb-4.x) may also be of help.
 119
 120 If your system uses some variant of old-style a.out-format,
 121 you can start with a copy of bfd/newsos3.c, and edit it to fit.
 122 (You may also need to tweak bfd/aout-target.h.)
 123 Alternatively, you could use the host-aout.c target.  This is a
 124 special kludge that only works for native (non-cross) configurations.
 125
 126 Reporting bugs
 127 ==============
 128 If you can't track down a bug and send suggestions/patches
 129 for fixes, you should probably *not* be using this release.
 130 We have little time to spend tracking down whatever random bugs you
 131 may run into (except for configurations that Cygnus supports for
 132 its customers).  The general place to send bug reports or patches
 133 is to bug-gnu-utils@ai.mit.edu; you can also send them directly to
 134 raeburn@cygnus.com or ian@cygnus.com.