-This is a beta release of a completely rewritten binutils distribution.
-(Rewritten since binutils 1.x, that is.)
+ README for BINUTILS
-The linker (ld) has been moved into a separate directory, which should be
-../ld. Linker-specific notes are in ../ld/README.
+These are the GNU binutils. These are utilities of use when dealing
+with binary files, either object files or executables. These tools
+consist of the linker (ld), the assembler (gas), and the profiler
+(gprof) each of which have their own sub-directory named after them.
+There is also a collection of other binary tools, including the
+disassembler (objdump) in this directory. These tools make use of a
+pair of libraries (bfd and opcodes) and a common set of header files
+(include).
-As of version 2.5, the assembler (as) is also included in this package, in
-../gas. Assembler-specific notes can be found in ../gas/README.
+There are README and NEWS files in most of the program sub-directories
+which give more information about those specific programs.
-These programs have been tested on various architectures.
-However, since this is a beta release taken directly from an
-evolving source tree, there might be some problems. In particular,
-the programs have not been ported to as many machines as the
-old binutils. There are also features of the old versions
-that are missing on the new programs. We would appreciate
-patches to make things run on other machines; especially welcome
-are fixes for what used to work on the old programs!
-(See ./TODO, as well a ../bfd/TODO and ../ld/TODO.)
-Recent changes are in ./NEWS, ../ld/NEWS, and ../gas/NEWS.
+Copyright Notices
+=================
-Unpacking and Installation -- quick overview
-==========================
+Copyright years on binutils source files may be listed using range
+notation, e.g., 1991-2012, indicating that every year in the range,
+inclusive, is a copyrightable year that could otherwise be listed
+individually.
-In this release, the binary utilities, the linker, the generic GNU include
-files, the BFD ("binary file description") library, gprof, and getopt all
-have directories of their own underneath the binutils-2.7 directory.
-The idea is that a variety of GNU tools can
-share a common copy of these things. Configuration scripts and
-makefiles exist to cruise up and down this directory tree and
-automatically build all the pieces in the right order.
-When you unpack the binutils-2.7.tar.gz file, you'll get a directory
-called something like `binutils-2.7', which contains:
+Unpacking and Installation -- quick overview
+============================================
- COPYING bfd/ configure* libiberty/
- COPYING.LIB binutils/ configure.in move-if-change*
- CYGNUS build-all.mk etc/ opcodes/
- ChangeLog config/ gprof/ test-build.mk
- Makefile.in config.guess* inc
+When you unpack the binutils archive file, you will get a directory
+called something like `binutils-XXX', where XXX is the number of the
+release. (Probably 2.13 or higher). This directory contains
+various files and sub-directories. Most of the files in the top
+directory are for information and for configuration. The actual
+source code is in sub-directories.
To build binutils, you can just do:
- cd binutils-2.7
- ./configure [ --enable-targets='target1,target2...' ]
+ cd binutils-XXX
+ ./configure [options]
make
make install # copies the programs files into /usr/local/bin
# by default.
-This will configure and build all the libraries as well as binutils
-and the linker.
+This will configure and build all the libraries as well as the
+assembler, the binutils, and the linker.
+
+If you have GNU make, we recommend building in a different directory:
+
+ mkdir objdir
+ cd objdir
+ ../binutils-XXX/configure [options]
+ make
+ make install
+
+This relies on the VPATH feature of GNU make.
+
+By default, the binutils will be configured to support the system on
+which they are built. When doing cross development, use the --target
+configure option to specify a different target, eg:
+
+ ./configure --target=foo-elf
-The --enable-targets option adds support for more binary file
-formats besides the default. By default, support for only the
-selected target file format is compiled in. To add support for more
-formats, list them as the argument to --enable-targets, separated by
-commas. For example:
+The --enable-targets option adds support for more binary file formats
+besides the default. List them as the argument to --enable-targets,
+separated by commas. For example:
./configure --enable-targets=sun3,rs6000-aix,decstation
-The name 'all' compiles in support for all valid BFD targets (this was
-the default in previous releases):
+The name 'all' compiles in support for all valid BFD targets:
./configure --enable-targets=all
-The binutils can be used in a cross-development environment.
-The file etc/configure.texi contains more information.
+On 32-bit hosts though, this support will be restricted to 32-bit
+target unless the --enable-64-bit-bfd option is also used:
+
+ ./configure --enable-64-bit-bfd --enable-targets=all
You can also specify the --enable-shared option when you run
configure. This will build the BFD and opcodes libraries as shared
-libraries. This will only work on certain systems, and currently will
-only work when compiling with gcc. You can use arguments with the
---enable-shared option to indicate that only certain libraries should
-be built shared; for example, --enable-shared=bfd. The only
-possibilities in a binutils release are bfd and opcodes.
+libraries. You can use arguments with the --enable-shared option to
+indicate that only certain libraries should be built shared; for
+example, --enable-shared=bfd. The only potential shared libraries in
+a binutils release are bfd and opcodes.
The binutils will be linked against the shared libraries. The build
-step will attempt to place the correct library in the runtime search
+step will attempt to place the correct library in the run-time search
path for the binaries. However, in some cases, after you install the
binaries, you may have to set an environment variable, normally
LD_LIBRARY_PATH, so that the system can find the installed libbfd
shared library.
-If you specify --enable-commonbfdlib as well as --enable-shared, then
-a single shared library will be built containing the bfd, opcodes, and
-libiberty libraries. It will be installed as libbfd. This option
-will make the binutils programs as small as possible.
+On hosts that support shared system libraries the binutils will be
+linked against them. If you have static versions of the system
+libraries installed as well and you wish to create static binaries
+instead then use the LDFLAGS environment variable, like this:
+
+ ../binutils-XXX/configure LDFLAGS="--static" [more options]
+
+Note: the two dashes are important. The binutils make use of the
+libtool script which has a special interpretation of "-static" when it
+is in the LDFLAGS environment variable.
+
+To build under openVMS/AXP, see the file makefile.vms in the top level
+directory.
+
+
+Native Language Support
+=======================
+
+By default Native Language Support will be enabled for binutils. On
+some systems however this support is not present and can lead to error
+messages such as "undefined reference to `libintl_gettext'" when
+building there tools. If that happens the NLS support can be disabled
+by adding the --disable-nls switch to the configure line like this:
+
+ ../binutils-XXX/configure --disable-nls
+
If you don't have ar
====================
-If your system does not already have an ar program, the normal
+If your system does not already have an 'ar' program, the normal
binutils build process will not work. In this case, run configure as
usual. Before running make, run this script:
#!/bin/sh
-MAKE=${MAKE-make}
-${MAKE} $* AR=true all-libiberty
-${MAKE} $* AR=true all-bfd
+MAKE_PROG="${MAKE-make}"
+MAKE="${MAKE_PROG} AR=true LINK=true"
+export MAKE
+${MAKE} $* all-libiberty
+${MAKE} $* all-intl
+${MAKE} $* all-bfd
cd binutils
-${MAKE} $* ADDL_DEPS='$(BULIBS)' ADDL_LIBS='$(BULIBS) ../bfd/*.o `cat ../libiberty/required-list ../libiberty/needed-list | sed -e "s,\([^ ][^ ]*\),../libiberty/\1,g"`' ar
+MAKE="${MAKE_PROG}"
+export MAKE
+${MAKE} $* ar_DEPENDENCIES= ar_LDADD='../bfd/*.o ../libiberty/*.o `if test -f ../intl/gettext.o; then echo '../intl/*.o'; fi`' ar
This script will build an ar program in binutils/ar. Move binutils/ar
into a directory on your PATH. After doing this, you can run make as
Porting
=======
-Binutils-2.7 supports many different architectures, but there
+
+Binutils-2.13 supports many different architectures, but there
are many more not supported, including some that were supported
-by earlier versions. We are hoping for volunteers to
-improve this situation.
+by earlier versions. We are hoping for volunteers to improve this
+situation.
The major effort in porting binutils to a new host and/or target
architecture involves the BFD library. There is some documentation
in ../bfd/doc. The file ../gdb/doc/gdbint.texinfo (distributed
-with gdb-4.x) may also be of help.
-
-If your system uses some variant of old-style a.out-format,
-you can start with a copy of bfd/newsos3.c, and edit it to fit.
-(You may also need to tweak bfd/aout-target.h.)
-Alternatively, you could use the host-aout.c target. This is a
-special kludge that only works for native (non-cross) configurations.
+with gdb-5.x) may also be of help.
Reporting bugs
==============
-If you can't track down a bug and send suggestions/patches
-for fixes, you should probably *not* be using this release.
-We have little time to spend tracking down whatever random bugs you
-may run into (except for configurations that Cygnus supports for
-its customers). The general place to send bug reports or patches
-is to bug-gnu-utils@ai.mit.edu; you can also send them directly to
-raeburn@cygnus.com or ian@cygnus.com.
+
+Send bug reports and patches to:
+
+ bug-binutils@gnu.org.
+
+Please include the following in bug reports:
+
+- A description of exactly what went wrong, and exactly what should have
+ happened instead.
+
+- The configuration name(s) given to the "configure" script. The
+ "config.status" file should have this information. This is assuming
+ you built binutils yourself. If you didn't build binutils youself,
+ then we need information regarding your machine and operating system,
+ and it may be more appropriate to report bugs to wherever you obtained
+ binutils.
+
+- The options given to the tool (gas, objcopy, ld etc.) at run time.
+
+- The actual input file that caused the problem.
+
+Always mention the version number you are running; this is printed by
+running any of the binutils with the --version option. We appreciate
+reports about bugs, but we do not promise to fix them, particularly so
+when the bug report is against an old version. If you are able, please
+consider building the latest tools from git to check that your bug has
+not already been fixed.
+
+When reporting problems about gas and ld, it's useful to provide a
+testcase that triggers the problem. In the case of a gas problem, we
+want input files to gas and command line switches used. The inputs to
+gas are _NOT_ .c or .i files, but rather .s files. If your original
+source was a C program, you can generate the .s file and see the command
+line options by passing -v -save-temps to gcc in addition to all the
+usual options you use. The reason we don't want C files is that we
+might not have a C compiler around for the target you use. While it
+might be possible to build a compiler, that takes considerable time and
+disk space, and we might not end up with exactly the same compiler you
+use.
+
+In the case of a ld problem, the input files are .o, .a and .so files,
+and possibly a linker script specified with -T. Again, when using gcc
+to link, you can see these files by adding options to the gcc command
+line. Use -v -save-temps -Wl,-t, except that on targets that use gcc's
+collect2, you would add -v -save-temps -Wl,-t,-debug. The -t option
+tells ld to print all files and libraries used, so that, for example,
+you can associate -lc on the ld command line with the actual libc used.
+Note that your simple two line C program to trigger a problem typically
+expands into several megabytes of objects by the time you include
+libraries.
+
+It is antisocial to post megabyte sized attachments to mailing lists, so
+please put large testcases somewhere on an ftp or web site so that only
+interested developers need to download them, or offer to email them on
+request. Better still, try to reduce the testcase, for example, try to
+develop a ld testcase that doesn't use system libraries. However,
+please be sure it is a complete testcase and that it really does
+demonstrate the problem. Also, don't bother paring it down if that will
+cause large delays in filing the bug report.
+
+If you expect to be contributing a large number of test cases, it would
+be helpful if you would look at the test suite included in the release
+(based on the Deja Gnu testing framework, available from the usual ftp
+sites) and write test cases to fit into that framework. This is
+certainly not required.
+
+VMS
+===
+
+This section was written by Klaus K"ampf <kkaempf@rmi.de>. It
+describes how to build and install the binutils on openVMS (Alpha and
+Vax). (The BFD library only supports reading Vax object files.)
+
+Compiling the release:
+
+To compile the gnu binary utilities and the gnu assembler, you'll
+need DEC C or GNU C for openVMS/Alpha. You'll need *both* compilers
+on openVMS/Vax.
+
+Compiling with either DEC C or GNU C works on openVMS/Alpha only. Some
+of the opcodes and binutils files trap a bug in the DEC C optimizer,
+so these files must be compiled with /noopt.
+
+Compiling on openVMS/Vax is a bit complicated, as the bfd library traps
+a bug in GNU C and the gnu assembler a bug in (my version of) DEC C.
+
+I never tried compiling with VAX C.
+
+
+You further need GNU Make Version 3.76 or later. This is available
+at ftp.progis.de or any GNU archive site. The makefiles assume that
+gmake starts gnu make as a foreign command.
+
+If you're compiling with DEC C or VAX C, you must run
+
+ $ @setup
+
+before starting gnu-make. This isn't needed with GNU C.
+
+On the Alpha you can choose the compiler by editing the toplevel
+makefile.vms. Either select CC=cc (for DEC C) or CC=gcc (for GNU C)
+
+
+Installing the release
+
+Provided that your directory setup conforms to the GNU on openVMS
+standard, you already have a concealed device named 'GNU_ROOT'.
+In this case, a simple
+
+ $ gmake install
+
+suffices to copy all programs and libraries to the proper directories.
+
+Define the programs as foreign commands by adding these lines to your
+login.com:
+
+ $ gas :== $GNU_ROOT:[bin]as.exe
+ $ size :== $GNU_ROOT:[bin]size.exe
+ $ nm :== $GNU_ROOT:[bin]nm.exe
+ $ objdump :== $GNU_ROOT:[bin]objdump.exe
+ $ strings :== $GNU_ROOT:[bin]strings.exe
+
+If you have a different directory setup, copy the binary utilities
+([.binutils]size.exe, [.binutils]nm.exe, [.binutils]objdump.exe,
+and [.binutils]strings.exe) and the gnu assembler and preprocessor
+([.gas]as.exe and [.gas]gasp.exe]) to a directory of your choice
+and define all programs as foreign commands.
+
+
+If you're satisfied with the compilation, you may want to remove
+unneeded objects and libraries:
+
+ $ gmake clean
+
+
+If you have any problems or questions about the binutils on VMS, feel
+free to mail me at kkaempf@rmi.de.
+\f
+Copyright (C) 2012-2020 Free Software Foundation, Inc.
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.
projects / deliverable / binutils-gdb.git / blobdiff