Debugging with GDB: Installing GDB

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# C. Installing GDB

> C.1 Requirements for Building GDB |  | Requirements for building GDB
> C.2 Invoking the GDB ``configure'` Script |  | Invoking the GDB ``configure'` script
> C.3 Compiling GDB in Another Directory |  | Compiling GDB in another directory
> C.4 Specifying Names for Hosts and Targets |  | Specifying names for hosts and targets
> C.5 ``configure'` Options |  | Summary of options for configure
> C.6 System-wide configuration and settings |  | Having a system-wide init file

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## C.1 Requirements for Building GDB

Building GDB requires various tools and packages to be available. Other packages will be used only if they are found.

## Tools/Packages Necessary for Building GDB

ISO C90 compiler
  GDB is written in ISO C90. It should be buildable with any working C90 compiler, e.g. GCC.

## Tools/Packages Optional for Building GDB

Expat
  GDB can use the Expat XML parsing library. This library may be included with your operating system distribution; if it is not, you can get the latest version from http://expat.sourceforge.net. The ``configure'` script will search for this library in several standard locations; if it is installed in an unusual path, you can use the ``--with-libexpat-prefix'` option to specify its location.

  Expat is used for:

  - Remote protocol memory maps (see section E.16 Memory Map Format)
  - Target descriptions (see section G. Target Descriptions)
  - Remote shared library lists (See section E.14 Library List Format, or alternatively see section E.15 Library List Format for SVR4 Targets)
  - MS-Windows shared libraries (see Shared Libraries)
  - Traceframe info (see section E.18 Traceframe Info Format)
  - Branch trace (see section E.19 Branch Trace Format)

zlib
  GDB will use the ``zlib'` library, if available, to read compressed debug sections. Some linkers, such as GNU gold, are capable of producing binaries with compressed debug sections. If GDB is compiled with ``zlib'`, it will be able to read the debug information in such binaries.

  The ``zlib'` library is likely included with your operating system distribution; if it is not, you can get the latest version from http://zlib.net.

iconv
  GDB's features related to character sets (see section 10.20 Character Sets) require a functioning `iconv` implementation. If you are on a GNU system, then this is provided by the GNU C Library. Some other systems also provide a working `iconv`.

  If GDB is using the `iconv` program which is installed in a non-standard place, you will need to tell GDB where to find it. This is done with ``--with-iconv-bin'` which specifies the directory that contains the `iconv` program.

  On systems without `iconv`, you can install GNU Libiconv. If you have previously installed Libiconv, you can use the ``--with-libiconv-prefix'` option to configure.

  GDB's top-level ``configure'` and ``Makefile'` will arrange to build Libiconv if a directory named ``libiconv'` appears in the top-most source directory. If Libiconv is built this way, and if the operating system does not provide a suitable `iconv` implementation, then the just-built library will automatically be used by GDB. One easy way to set this up is to download GNU Libiconv, unpack it, and then rename the directory holding the Libiconv source code to ``libiconv'`.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## C.2 Invoking the GDB ``configure'` Script

GDB comes with a ``configure'` script that automates the process of preparing GDB for installation; you can then use `make` to build the `gdb` program.

The GDB distribution includes all the source code you need for GDB in a single directory, whose name is usually composed by appending the version number to ``gdb'`.

For example, the GDB version 7.7 for GNAT GPL 2014 (20140405) distribution is in the ``gdb-7.7 for GNAT GPL 2014 (20140405)'` directory. That directory contains:

`gdb-7.7 for GNAT GPL 2014 (20140405)/configure (and supporting files)`
  script for configuring GDB and all its supporting libraries

`gdb-7.7 for GNAT GPL 2014 (20140405)/gdb`
  the source specific to GDB itself

`gdb-7.7 for GNAT GPL 2014 (20140405)/bfd`
  source for the Binary File Descriptor library

`gdb-7.7 for GNAT GPL 2014 (20140405)/include`
  GNU include files

`gdb-7.7 for GNAT GPL 2014 (20140405)/libiberty`
  source for the ``-liberty'` free software library

`gdb-7.7 for GNAT GPL 2014 (20140405)/opcodes`
  source for the library of opcode tables and disassemblers

`gdb-7.7 for GNAT GPL 2014 (20140405)/readline`
  source for the GNU command-line interface

`gdb-7.7 for GNAT GPL 2014 (20140405)/glob`
  source for the GNU filename pattern-matching subroutine

`gdb-7.7 for GNAT GPL 2014 (20140405)/mmalloc`
  source for the GNU memory-mapped malloc package

The simplest way to configure and build GDB is to run ``configure'` from the ``gdb-version-number'` source directory, which in this example is the ``gdb-7.7 for GNAT GPL 2014 (20140405)'` directory.

First switch to the ``gdb-version-number'` source directory if you are not already in it; then run ``configure'`. Pass the identifier for the platform on which GDB will run as an argument.

For example:

    cd gdb-7.7 for GNAT GPL 2014 (20140405)
    ./configure host
    make

where host is an identifier such as ``sun4'` or ``decstation'`, that identifies the platform where GDB will run. (You can often leave off host; ``configure'` tries to guess the correct value by examining your system.)

Running ``configure host'` and then running `make` builds the ``bfd'`, ``readline'`, ``mmalloc'`, and ``libiberty'` libraries, then `gdb` itself. The configured source files, and the binaries, are left in the corresponding source directories.

``configure'` is a Bourne-shell (`/bin/sh`) script; if your system does not recognize this automatically when you run a different shell, you may need to run `sh` on it explicitly:

    sh configure host

If you run ``configure'` from a directory that contains source directories for multiple libraries or programs, such as the ``gdb-7.7 for GNAT GPL 2014 (20140405)'` source directory for version 7.7 for GNAT GPL 2014 (20140405), ``configure'` creates configuration files for every directory level underneath (unless you tell it not to, with the ``--norecursion'` option).

You should run the ``configure'` script from the top directory in the source tree, the ``gdb-version-number'` directory. If you run ``configure'` from one of the subdirectories, you will configure only that subdirectory. That is usually not what you want. In particular, if you run the first ``configure'` from the ``gdb'` subdirectory of the ``gdb-version-number'` directory, you will omit the configuration of ``bfd'`, ``readline'`, and other sibling directories of the ``gdb'` subdirectory. This leads to build errors about missing include files such as ``bfd/bfd.h'`.

You can install `gdb` anywhere; it has no hardwired paths. However, you should make sure that the shell on your path (named by the ``SHELL'` environment variable) is publicly readable. Remember that GDB uses the shell to start your program--some systems refuse to let GDB debug child processes whose programs are not readable.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## C.3 Compiling GDB in Another Directory

If you want to run GDB versions for several host or target machines, you need a different `gdb` compiled for each combination of host and target. ``configure'` is designed to make this easy by allowing you to generate each configuration in a separate subdirectory, rather than in the source directory. If your `make` program handles the ``VPATH'` feature (GNU `make` does), running `make` in each of these directories builds the `gdb` program specified there.

To build `gdb` in a separate directory, run ``configure'` with the ``--srcdir'` option to specify where to find the source. (You also need to specify a path to find ``configure'` itself from your working directory. If the path to ``configure'` would be the same as the argument to ``--srcdir'`, you can leave out the ``--srcdir'` option; it is assumed.)

For example, with version 7.7 for GNAT GPL 2014 (20140405), you can build GDB in a separate directory for a Sun 4 like this:

    cd gdb-7.7 for GNAT GPL 2014 (20140405)
    mkdir ../gdb-sun4
    cd ../gdb-sun4
    ../gdb-7.7 for GNAT GPL 2014 (20140405)/configure sun4
    make

When ``configure'` builds a configuration using a remote source directory, it creates a tree for the binaries with the same structure (and using the same names) as the tree under the source directory. In the example, you'd find the Sun 4 library ``libiberty.a'` in the directory ``gdb-sun4/libiberty'`, and GDB itself in ``gdb-sun4/gdb'`.

Make sure that your path to the ``configure'` script has just one instance of ``gdb'` in it. If your path to ``configure'` looks like ``../gdb-7.7 for GNAT GPL 2014 (20140405)/gdb/configure'`, you are configuring only one subdirectory of GDB, not the whole package. This leads to build errors about missing include files such as ``bfd/bfd.h'`.

One popular reason to build several GDB configurations in separate directories is to configure GDB for cross-compiling (where GDB runs on one machine--the host---while debugging programs that run on another machine--the target). You specify a cross-debugging target by giving the ``--target=target'` option to ``configure'`.

When you run `make` to build a program or library, you must run it in a configured directory--whatever directory you were in when you called ``configure'` (or one of its subdirectories).

The `Makefile` that ``configure'` generates in each source directory also runs recursively. If you type `make` in a source directory such as ``gdb-7.7 for GNAT GPL 2014 (20140405)'` (or in a separate configured directory configured with ``--srcdir=dirname/gdb-7.7 for GNAT GPL 2014 (20140405)'`), you will build all the required libraries, and then build GDB.

When you have multiple hosts or targets configured in separate directories, you can run `make` on them in parallel (for example, if they are NFS-mounted on each of the hosts); they will not interfere with each other.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## C.4 Specifying Names for Hosts and Targets

The specifications used for hosts and targets in the ``configure'` script are based on a three-part naming scheme, but some short predefined aliases are also supported. The full naming scheme encodes three pieces of information in the following pattern:

    architecture-vendor-os

For example, you can use the alias `sun4` as a host argument, or as the value for target in a `--target=target` option. The equivalent full name is ``sparc-sun-sunos4'`.

The ``configure'` script accompanying GDB does not provide any query facility to list all supported host and target names or aliases. ``configure'` calls the Bourne shell script `config.sub` to map abbreviations to full names; you can read the script, if you wish, or you can use it to test your guesses on abbreviations--for example:

    % sh config.sub i386-linux
    i386-pc-linux-gnu
    % sh config.sub alpha-linux
    alpha-unknown-linux-gnu
    % sh config.sub hp9k700
    hppa1.1-hp-hpux
    % sh config.sub sun4
    sparc-sun-sunos4.1.1
    % sh config.sub sun3
    m68k-sun-sunos4.1.1
    % sh config.sub i986v
    Invalid configuration `i986v': machine `i986v' not recognized

`config.sub` is also distributed in the GDB source directory (``gdb-7.7 for GNAT GPL 2014 (20140405)'`, for version 7.7 for GNAT GPL 2014 (20140405)).

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## C.5 ``configure'` Options

Here is a summary of the ``configure'` options and arguments that are most often useful for building GDB. ``configure'` also has several other options not listed here. See Info file `configure.info', node `What Configure Does', for a full explanation of ``configure'`.

    configure [--help]
              [--prefix=dir]
              [--exec-prefix=dir]
              [--srcdir=dirname]
              [--norecursion] [--rm]
              [--target=target]
              host

You may introduce options with a single ``-'` rather than ``--'` if you prefer; but you may abbreviate option names if you use ``--'`.

`--help`
  Display a quick summary of how to invoke ``configure'`.

`--prefix=dir`
  Configure the source to install programs and files under directory ``dir'`.

`--exec-prefix=dir`
  Configure the source to install programs under directory ``dir'`.

`--srcdir=dirname`
  Warning: using this option requires GNU `make`, or another `make` that implements the `VPATH` feature.
  Use this option to make configurations in directories separate from the GDB source directories. Among other things, you can use this to build (or maintain) several configurations simultaneously, in separate directories. ``configure'` writes configuration-specific files in the current directory, but arranges for them to use the source in the directory dirname. ``configure'` creates directories under the working directory in parallel to the source directories below dirname.

`--norecursion`
  Configure only the directory level where ``configure'` is executed; do not propagate configuration to subdirectories.

`--target=target`
  Configure GDB for cross-debugging programs running on the specified target. Without this option, GDB is configured to debug programs that run on the same machine (host) as GDB itself.

  There is no convenient way to generate a list of all available targets.

`host ...`
  Configure GDB to run on the specified host.

  There is no convenient way to generate a list of all available hosts.

There are many other options available as well, but they are generally needed for special purposes only.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## C.6 System-wide configuration and settings

GDB can be configured to have a system-wide init file; this file will be read and executed at startup (see section What GDB does during startup).

Here is the corresponding configure option:

`--with-system-gdbinit=file`
  Specify that the default location of the system-wide init file is file.

If GDB has been configured with the option ``--prefix=$prefix'`, it may be subject to relocation. Two possible cases:

- If the default location of this init file contains ``$prefix'`, it will be subject to relocation. Suppose that the configure options are ``--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit'`; if GDB is moved from ``$prefix'` to ``$install'`, the system init file is looked for as ``$install/etc/gdbinit'` instead of ``$prefix/etc/gdbinit'`.

- By contrast, if the default location does not contain the prefix, it will not be relocated. E.g. if GDB has been configured with ``--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit'`, then GDB will always look for ``/usr/share/gdb/gdbinit'`, wherever GDB is installed.

If the configured location of the system-wide init file (as given by the ``--with-system-gdbinit'` option at configure time) is in the data-directory (as specified by ``--with-gdb-datadir'` at configure time) or in one of its subdirectories, then GDB will look for the system-wide init file in the directory specified by the ``--data-directory'` command-line option. Note that the system-wide init file is only read once, during GDB initialization. If the data-directory is changed after GDB has started with the `set data-directory` command, the file will not be reread.

> C.6.1 Installed System-wide Configuration Scripts |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### C.6.1 Installed System-wide Configuration Scripts

The ``system-gdbinit'` directory, located inside the data-directory (as specified by ``--with-gdb-datadir'` at configure time) contains a number of scripts which can be used as system-wide init files. To automatically source those scripts at startup, GDB should be configured with ``--with-system-gdbinit'`. Otherwise, any user should be able to source them by hand as needed.

The following scripts are currently available:

- ``elinos.py'` This script is useful when debugging a program on an ELinOS target. It takes advantage of the environment variables defined in a standard ELinOS environment in order to determine the location of the system shared libraries, and then sets the ``solib-absolute-prefix'` and ``solib-search-path'` variables appropriately.

- ``wrs-linux.py'` This script is useful when debugging a program on a target running Wind River Linux. It expects the `ENV_PREFIX` to be set to the host-side sysroot used by the target system.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html