<HTML> <HEAD> <!-- This HTML file has been created by texi2html 1.51 from /mnt/apple/gdb/source/gdb.apple/source/gdb/gdb/doc/gdb.texinfo on 23 November 1999 --> <TITLE>Debugging with GDB - Installing GDB</TITLE> </HEAD> <BODY> Go to the <A HREF="gdb_1.html">first</A>, <A HREF="gdb_19.html">previous</A>, <A HREF="gdb_21.html">next</A>, <A HREF="gdb_21.html">last</A> section, <A HREF="gdb_toc.html">table of contents</A>. <P><HR><P> <H1><A NAME="SEC166" HREF="gdb_toc.html#TOC166">Installing GDB</A></H1> <P> <A NAME="IDX739"></A> <A NAME="IDX740"></A> </P> <P> GDB comes with a <CODE>configure</CODE> script that automates the process of preparing GDB for installation; you can then use <CODE>make</CODE> to build the <CODE>gdb</CODE> program. <A NAME="DOCF6" HREF="gdb_foot.html#FOOT6">(6)</A> </P> <P> 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 <SAMP>`gdb'</SAMP>. </P> <P> For example, the GDB version 19990707 distribution is in the <TT>`gdb-19990707'</TT> directory. That directory contains: </P> <DL COMPACT> <DT><CODE>gdb-19990707/configure (and supporting files)</CODE> <DD> script for configuring GDB and all its supporting libraries <DT><CODE>gdb-19990707/gdb</CODE> <DD> the source specific to GDB itself <DT><CODE>gdb-19990707/bfd</CODE> <DD> source for the Binary File Descriptor library <DT><CODE>gdb-19990707/include</CODE> <DD> GNU include files <DT><CODE>gdb-19990707/libiberty</CODE> <DD> source for the <SAMP>`-liberty'</SAMP> free software library <DT><CODE>gdb-19990707/opcodes</CODE> <DD> source for the library of opcode tables and disassemblers <DT><CODE>gdb-19990707/readline</CODE> <DD> source for the GNU command-line interface <DT><CODE>gdb-19990707/glob</CODE> <DD> source for the GNU filename pattern-matching subroutine <DT><CODE>gdb-19990707/mmalloc</CODE> <DD> source for the GNU memory-mapped malloc package </DL> <P> The simplest way to configure and build GDB is to run <CODE>configure</CODE> from the <TT>`gdb-<VAR>version-number</VAR>'</TT> source directory, which in this example is the <TT>`gdb-19990707'</TT> directory. </P> <P> First switch to the <TT>`gdb-<VAR>version-number</VAR>'</TT> source directory if you are not already in it; then run <CODE>configure</CODE>. Pass the identifier for the platform on which GDB will run as an argument. </P> <P> For example: </P> <PRE> cd gdb-19990707 ./configure <VAR>host</VAR> make </PRE> <P> where <VAR>host</VAR> is an identifier such as <SAMP>`sun4'</SAMP> or <SAMP>`decstation'</SAMP>, that identifies the platform where GDB will run. (You can often leave off <VAR>host</VAR>; <CODE>configure</CODE> tries to guess the correct value by examining your system.) </P> <P> Running <SAMP>`configure <VAR>host</VAR>'</SAMP> and then running <CODE>make</CODE> builds the <TT>`bfd'</TT>, <TT>`readline'</TT>, <TT>`mmalloc'</TT>, and <TT>`libiberty'</TT> libraries, then <CODE>gdb</CODE> itself. The configured source files, and the binaries, are left in the corresponding source directories. </P> <P> <CODE>configure</CODE> is a Bourne-shell (<CODE>/bin/sh</CODE>) script; if your system does not recognize this automatically when you run a different shell, you may need to run <CODE>sh</CODE> on it explicitly: </P> <PRE> sh configure <VAR>host</VAR> </PRE> <P> If you run <CODE>configure</CODE> from a directory that contains source directories for multiple libraries or programs, such as the <TT>`gdb-19990707'</TT> source directory for version 19990707, <CODE>configure</CODE> creates configuration files for every directory level underneath (unless you tell it not to, with the <SAMP>`--norecursion'</SAMP> option). </P> <P> You can run the <CODE>configure</CODE> script from any of the subordinate directories in the GDB distribution if you only want to configure that subdirectory, but be sure to specify a path to it. </P> <P> For example, with version 19990707, type the following to configure only the <CODE>bfd</CODE> subdirectory: </P> <PRE> cd gdb-19990707/bfd ../configure <VAR>host</VAR> </PRE> <P> You can install <CODE>gdb</CODE> anywhere; it has no hardwired paths. However, you should make sure that the shell on your path (named by the <SAMP>`SHELL'</SAMP> 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. </P> <H2><A NAME="SEC167" HREF="gdb_toc.html#TOC167">Compiling GDB in another directory</A></H2> <P> If you want to run GDB versions for several host or target machines, you need a different <CODE>gdb</CODE> compiled for each combination of host and target. <CODE>configure</CODE> 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 <CODE>make</CODE> program handles the <SAMP>`VPATH'</SAMP> feature (GNU <CODE>make</CODE> does), running <CODE>make</CODE> in each of these directories builds the <CODE>gdb</CODE> program specified there. </P> <P> To build <CODE>gdb</CODE> in a separate directory, run <CODE>configure</CODE> with the <SAMP>`--srcdir'</SAMP> option to specify where to find the source. (You also need to specify a path to find <CODE>configure</CODE> itself from your working directory. If the path to <CODE>configure</CODE> would be the same as the argument to <SAMP>`--srcdir'</SAMP>, you can leave out the <SAMP>`--srcdir'</SAMP> option; it is assumed.) </P> <P> For example, with version 19990707, you can build GDB in a separate directory for a Sun 4 like this: </P> <PRE> cd gdb-19990707 mkdir ../gdb-sun4 cd ../gdb-sun4 ../gdb-19990707/configure sun4 make </PRE> <P> When <CODE>configure</CODE> 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 <TT>`libiberty.a'</TT> in the directory <TT>`gdb-sun4/libiberty'</TT>, and GDB itself in <TT>`gdb-sun4/gdb'</TT>. </P> <P> 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 <STRONG>host</STRONG>---while debugging programs that run on another machine--the <STRONG>target</STRONG>). You specify a cross-debugging target by giving the <SAMP>`--target=<VAR>target</VAR>'</SAMP> option to <CODE>configure</CODE>. </P> <P> When you run <CODE>make</CODE> to build a program or library, you must run it in a configured directory--whatever directory you were in when you called <CODE>configure</CODE> (or one of its subdirectories). </P> <P> The <CODE>Makefile</CODE> that <CODE>configure</CODE> generates in each source directory also runs recursively. If you type <CODE>make</CODE> in a source directory such as <TT>`gdb-19990707'</TT> (or in a separate configured directory configured with <SAMP>`--srcdir=<VAR>dirname</VAR>/gdb-19990707'</SAMP>), you will build all the required libraries, and then build GDB. </P> <P> When you have multiple hosts or targets configured in separate directories, you can run <CODE>make</CODE> on them in parallel (for example, if they are NFS-mounted on each of the hosts); they will not interfere with each other. </P> <H2><A NAME="SEC168" HREF="gdb_toc.html#TOC168">Specifying names for hosts and targets</A></H2> <P> The specifications used for hosts and targets in the <CODE>configure</CODE> 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: </P> <PRE> <VAR>architecture</VAR>-<VAR>vendor</VAR>-<VAR>os</VAR> </PRE> <P> For example, you can use the alias <CODE>sun4</CODE> as a <VAR>host</VAR> argument, or as the value for <VAR>target</VAR> in a <CODE>--target=<VAR>target</VAR></CODE> option. The equivalent full name is <SAMP>`sparc-sun-sunos4'</SAMP>. </P> <P> The <CODE>configure</CODE> script accompanying GDB does not provide any query facility to list all supported host and target names or aliases. <CODE>configure</CODE> calls the Bourne shell script <CODE>config.sub</CODE> 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: </P> <PRE> % 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 </PRE> <P> <CODE>config.sub</CODE> is also distributed in the GDB source directory (<TT>`gdb-19990707'</TT>, for version 19990707). </P> <H2><A NAME="SEC169" HREF="gdb_toc.html#TOC169"><CODE>configure</CODE> options</A></H2> <P> Here is a summary of the <CODE>configure</CODE> options and arguments that are most often useful for building GDB. <CODE>configure</CODE> also has several other options not listed here. </P> <PRE> configure [--help] [--prefix=<VAR>dir</VAR>] [--exec-prefix=<VAR>dir</VAR>] [--srcdir=<VAR>dirname</VAR>] [--norecursion] [--rm] [--target=<VAR>target</VAR>] <VAR>host</VAR> </PRE> <P> You may introduce options with a single <SAMP>`-'</SAMP> rather than <SAMP>`--'</SAMP> if you prefer; but you may abbreviate option names if you use <SAMP>`--'</SAMP>. </P> <DL COMPACT> <DT><CODE>--help</CODE> <DD> Display a quick summary of how to invoke <CODE>configure</CODE>. <DT><CODE>--prefix=<VAR>dir</VAR></CODE> <DD> Configure the source to install programs and files under directory <TT>`<VAR>dir</VAR>'</TT>. <DT><CODE>--exec-prefix=<VAR>dir</VAR></CODE> <DD> Configure the source to install programs under directory <TT>`<VAR>dir</VAR>'</TT>. <DT><CODE>--srcdir=<VAR>dirname</VAR></CODE> <DD> <STRONG>Warning: using this option requires GNU <CODE>make</CODE>, or another <CODE>make</CODE> that implements the <CODE>VPATH</CODE> feature.</STRONG><BR> 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. <CODE>configure</CODE> writes configuration specific files in the current directory, but arranges for them to use the source in the directory <VAR>dirname</VAR>. <CODE>configure</CODE> creates directories under the working directory in parallel to the source directories below <VAR>dirname</VAR>. <DT><CODE>--norecursion</CODE> <DD> Configure only the directory level where <CODE>configure</CODE> is executed; do not propagate configuration to subdirectories. <DT><CODE>--target=<VAR>target</VAR></CODE> <DD> Configure GDB for cross-debugging programs running on the specified <VAR>target</VAR>. Without this option, GDB is configured to debug programs that run on the same machine (<VAR>host</VAR>) as GDB itself. There is no convenient way to generate a list of all available targets. <DT><CODE><VAR>host</VAR> ...</CODE> <DD> Configure GDB to run on the specified <VAR>host</VAR>. There is no convenient way to generate a list of all available hosts. </DL> <P> There are many other options available as well, but they are generally needed for special purposes only. </P> <P> <P><HR><P> Go to the <A HREF="gdb_1.html">first</A>, <A HREF="gdb_19.html">previous</A>, <A HREF="gdb_21.html">next</A>, <A HREF="gdb_21.html">last</A> section, <A HREF="gdb_toc.html">table of contents</A>. </BODY> </HTML>