contrib/binutils/binutils/README

   1 These are the GNU binutils.  These are utilities of use when dealing
   2 with object files.
   3
   4 The linker (ld) is in a separate directory, which should be ../ld.
   5 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 Recent changes are in ./NEWS, ../ld/NEWS, and ../gas/NEWS.
  11
  12 Unpacking and Installation -- quick overview
  13 ============================================
  14
  15 When you unpack the binutils-2.9.tar.gz file, you'll get a directory
  16 called something like `binutils-2.9', which contains various files and
  17 directories.  Most of the files in the top directory are for
  18 information and for configuration.  The actual source code is in
  19 subdirectories.
  20
  21 To build binutils, you can just do:
  22
  23         cd binutils-2.9
  24         ./configure [options]
  25         make
  26         make install # copies the programs files into /usr/local/bin
  27                      # by default.
  28
  29 This will configure and build all the libraries as well as the
  30 assembler, the binutils, and the linker.
  31
  32 If you have GNU make, we recommend building in a different directory:
  33
  34         mkdir objdir
  35         cd objdir
  36         ../binutils-2.9/configure [options]
  37         make
  38         make install
  39
  40 This relies on the VPATH feature of GNU make.
  41
  42 By default, the binutils will be configured to support the system on
  43 which they are built.  When doing cross development, use the --target
  44 configure option to specify a different target.
  45
  46 The --enable-targets option adds support for more binary file formats
  47 besides the default.  List them as the argument to --enable-targets,
  48 separated by commas.  For example:
  49
  50         ./configure --enable-targets=sun3,rs6000-aix,decstation
  51
  52 The name 'all' compiles in support for all valid BFD targets (this was
  53 the default in releases before 2.3):
  54
  55         ./configure --enable-targets=all
  56
  57 You can also specify the --enable-shared option when you run
  58 configure.  This will build the BFD and opcodes libraries as shared
  59 libraries.  You can use arguments with the --enable-shared option to
  60 indicate that only certain libraries should be built shared; for
  61 example, --enable-shared=bfd.  The only potential shared libraries in
  62 a binutils release are bfd and opcodes.
  63
  64 The binutils will be linked against the shared libraries.  The build
  65 step will attempt to place the correct library in the runtime search
  66 path for the binaries.  However, in some cases, after you install the
  67 binaries, you may have to set an environment variable, normally
  68 LD_LIBRARY_PATH, so that the system can find the installed libbfd
  69 shared library.
  70
  71 To build under openVMS/AXP, see the file makefile.vms in the top level
  72 directory.
  73
  74 If you don't have ar
  75 ====================
  76
  77 If your system does not already have an ar program, the normal
  78 binutils build process will not work.  In this case, run configure as
  79 usual.  Before running make, run this script:
  80
  81 #!/bin/sh
  82 MAKE=${MAKE-make}
  83 ${MAKE} $* AR=true all-libiberty
  84 ${MAKE} $* AR=true all-bfd
  85 cd binutils
  86 ${MAKE} $* ADDL_DEPS='$(BULIBS)' ADDL_LIBS='$(BULIBS) ../bfd/*.o `cat ../libiberty/required-list ../libiberty/needed-list | sed -e "s,\([^ ][^ ]*\),../libiberty/\1,g"`' ar
  87
  88 This script will build an ar program in binutils/ar.  Move binutils/ar
  89 into a directory on your PATH.  After doing this, you can run make as
  90 usual to build the complete binutils distribution.  You do not need
  91 the ranlib program in order to build the distribution.
  92
  93 Porting
  94 =======
  95
  96 Binutils-2.9 supports many different architectures, but there
  97 are many more not supported, including some that were supported
  98 by earlier versions.  We are hoping for volunteers to
  99 improve this situation.
 100
 101 The major effort in porting binutils to a new host and/or target
 102 architecture involves the BFD library.  There is some documentation
 103 in ../bfd/doc.  The file ../gdb/doc/gdbint.texinfo (distributed
 104 with gdb-4.x) may also be of help.
 105
 106 Reporting bugs
 107 ==============
 108
 109 Send bug reports and patches to bug-gnu-utils@gnu.org.  Always mention
 110 the version number you are running; this is printed by running any of
 111 the binutils with the --version option.  We appreciate reports about
 112 bugs, but we do not promise to fix them.
 113
 114 Testing
 115 =======
 116
 117 Testing this release of the binutils requires an unreleased version of
 118 dejagnu.  There is a dejagnu snapshot available at
 119     ftp://ftp.cygnus.com/pub/binutils
 120 which may be used for testing.
 121
 122 Maintenance
 123 ===========
 124
 125 The configure and Makefile.in files in the subdirectories are
 126 generated by autoconf and automake, respectively.  The libtool package
 127 is also required.  In order to make the generation rules fire
 128 automatically, you must configure with the --enable-maintainer-mode
 129 option.  This option is not the default in order to avoid problems on
 130 systems which have out of date versions of autoconf or automake
 131 installed.  The generated files in this release were built with
 132 unreleased versions of autoconf, automake, and libtool.  You can find
 133 snapshots of the appropriate sources at
 134     ftp://ftp.cygnus.com/pub/binutils