home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / gdb-4.9 / gdb / README < prev    next >
Encoding:
Text File  |  1993-05-12  |  20.4 KB  |  536 lines
  1.               README for gdb-4.9 release
  2.             Updated 10-May-93 by Fred Fish
  3.  
  4. This is GDB, the GNU source-level debugger, presently running under un*x.
  5. A summary of new features is in the file `NEWS'.
  6.  
  7.  
  8. Unpacking and Installation -- quick overview
  9. ==========================
  10.  
  11. In this release, the GDB debugger sources, the generic GNU include
  12. files, the BFD ("binary file description") library, the readline library,
  13. and other libraries all have directories of their own underneath
  14. the gdb-4.9 directory.  The idea is that a variety of GNU tools can
  15. share a common copy of these things.  Configuration scripts and
  16. makefiles exist to cruise up and down this directory tree and
  17. automatically build all the pieces in the right order.
  18.  
  19. When you unpack the gdb-4.9.tar.z or gdb-4.9.tar.Z file, you'll find
  20. a directory called `gdb-4.9', which contains:
  21.  
  22.   Makefile.in      config.sub*      glob/            opcodes/
  23.   README           configure*       include/         readline/
  24.   bfd/             configure.in     libiberty/       texinfo/
  25.   config/          etc/             mmalloc/
  26.   config.guess*    gdb/             move-if-change*
  27.  
  28. To build GDB, you can just do:
  29.  
  30.     cd gdb-4.9
  31.     ./configure
  32.     make
  33.     cp gdb/gdb /usr/local/bin/gdb    (or wherever you want)
  34.  
  35. This will configure and build all the libraries as well as GDB.
  36. If `configure' can't determine your system type, specify one as its
  37. argument, e.g. sun4 or decstation.
  38.  
  39. If you get compiler warnings during this stage, see the `Reporting Bugs'
  40. section below; there are a few known problems.
  41.  
  42. GDB can be used as a cross-debugger, running on a machine of one type
  43. while debugging a program running on a machine of another type.  See below.
  44.  
  45.  
  46. More Documentation
  47. ******************
  48.  
  49.    The GDB 4 release includes an already-formatted reference card,
  50. ready for printing with PostScript or GhostScript, in the `gdb'
  51. subdirectory of the main source directory.  (In `gdb-4.9/gdb/refcard.ps'.)
  52. If you can use PostScript or GhostScript with your printer, you can
  53. print the reference card immediately with `refcard.ps'.
  54.  
  55.    The release also includes the source for the reference card.  You
  56. can format it, using TeX, by typing:
  57.  
  58.      make refcard.dvi
  59.  
  60.    The GDB reference card is designed to print in landscape mode on US
  61. "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
  62. high.  You will need to specify this form of printing as an option to
  63. your DVI output program.
  64.  
  65.    All the documentation for GDB comes as part of the machine-readable
  66. distribution.  The documentation is written in Texinfo format, which is
  67. a documentation system that uses a single source file to produce both
  68. on-line information and a printed manual.  You can use one of the Info
  69. formatting commands to create the on-line version of the documentation
  70. and TeX (or `texi2roff') to typeset the printed version.
  71.  
  72.    GDB includes an already formatted copy of the on-line Info version of
  73. this manual in the `gdb' subdirectory.  The main Info file is
  74. `gdb-VERSION-NUMBER/gdb/gdb.info', and it refers to subordinate files
  75. matching `gdb.info*' in the same directory.  If necessary, you can
  76. print out these files, or read them with any editor; but they are
  77. easier to read using the `info' subsystem in GNU Emacs or the
  78. standalone `info' program, available as part of the GNU Texinfo
  79. distribution.
  80.  
  81.    If you want to format these Info files yourself, you need one of the
  82. Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
  83.  
  84.    If you have `makeinfo' installed, and are in the top level GDB
  85. source directory (`gdb-4.9', in the case of version 4.9), you can make
  86. the Info file by typing:
  87.  
  88.      cd gdb
  89.      make gdb.info
  90.  
  91.    If you want to typeset and print copies of this manual, you need TeX,
  92. a program to print its DVI output files, and `texinfo.tex', the Texinfo
  93. definitions file.
  94.  
  95.    TeX is a typesetting program; it does not print files directly, but
  96. produces output files called DVI files.  To print a typeset document,
  97. you need a program to print DVI files.  If your system has TeX
  98. installed, chances are it has such a program.  The precise command to
  99. use depends on your system; `lpr -d' is common; another (for PostScript
  100. devices) is `dvips'.  The DVI print command may require a file name
  101. without any extension or a `.dvi' extension.
  102.  
  103.    TeX also requires a macro definitions file called `texinfo.tex'. 
  104. This file tells TeX how to typeset a document written in Texinfo
  105. format.  On its own, TeX cannot read, much less typeset a Texinfo file.
  106.  `texinfo.tex' is distributed with GDB and is located in the
  107. `gdb-VERSION-NUMBER/texinfo' directory.
  108.  
  109.    If you have TeX and a DVI printer program installed, you can typeset
  110. and print this manual.  First switch to the the `gdb' subdirectory of
  111. the main source directory (for example, to `gdb-4.9/gdb') and then type:
  112.  
  113.      make gdb.dvi
  114.  
  115.  
  116. Installing GDB
  117. **************
  118.  
  119.    GDB comes with a `configure' script that automates the process of
  120. preparing GDB for installation; you can then use `make' to build the
  121. `gdb' program.
  122.  
  123.    The GDB distribution includes all the source code you need for GDB in
  124. a single directory, whose name is usually composed by appending the
  125. version number to `gdb'.
  126.  
  127.    For example, the GDB version 4.9 distribution is in the `gdb-4.9'
  128. directory.  That directory contains:
  129.  
  130. `gdb-4.9/configure (and supporting files)'
  131.      script for configuring GDB and all its supporting libraries.
  132.  
  133. `gdb-4.9/gdb'
  134.      the source specific to GDB itself
  135.  
  136. `gdb-4.9/bfd'
  137.      source for the Binary File Descriptor library
  138.  
  139. `gdb-4.9/include'
  140.      GNU include files
  141.  
  142. `gdb-4.9/libiberty'
  143.      source for the `-liberty' free software library
  144.  
  145. `gdb-4.9/opcodes'
  146.      source for the library of opcode tables and disassemblers
  147.  
  148. `gdb-4.9/readline'
  149.      source for the GNU command-line interface
  150.  
  151. `gdb-4.9/glob'
  152.      source for the GNU filename pattern-matching subroutine
  153.  
  154. `gdb-4.9/mmalloc'
  155.      source for the GNU memory-mapped malloc package
  156.  
  157. 'gdb-4.9/sim'
  158.      source for some simulators (z8000, H8/300, H8/500, etc)
  159.  
  160.    The simplest way to configure and build GDB is to run `configure'
  161. from the `gdb-VERSION-NUMBER' source directory, which in this example
  162. is the `gdb-4.9' directory.
  163.  
  164.    First switch to the `gdb-VERSION-NUMBER' source directory if you are
  165. not already in it; then run `configure'.  Pass the identifier for the
  166. platform on which GDB will run as an argument.
  167.  
  168.    For example:
  169.  
  170.      cd gdb-4.9
  171.      ./configure HOST
  172.      make
  173.  
  174. where HOST is an identifier such as `sun4' or `decstation', that
  175. identifies the platform where GDB will run.
  176.  
  177.    Running `configure HOST' followed by `make' builds the `bfd',
  178. `readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. 
  179. The configured source files, and the binaries, are left in the
  180. corresponding source directories.
  181.  
  182.    `configure' is a Bourne-shell (`/bin/sh') script; if your system
  183. does not recognize this automatically when you run a different shell,
  184. you may need to run `sh' on it explicitly:
  185.  
  186.      sh configure HOST
  187.  
  188.    If you run `configure' from a directory that contains source
  189. directories for multiple libraries or programs, such as the `gdb-4.9'
  190. source directory for version 4.9, `configure' creates configuration
  191. files for every directory level underneath (unless you tell it not to,
  192. with the `--norecursion' option).
  193.  
  194.    You can run the `configure' script from any of the subordinate
  195. directories in the GDB distribution, if you only want to configure that
  196. subdirectory; but be sure to specify a path to it.
  197.  
  198.    For example, with version 4.9, type the following to configure only
  199. the `bfd' subdirectory:
  200.  
  201.      cd gdb-4.9/bfd
  202.      ../configure HOST
  203.  
  204.    You can install `gdb' anywhere; it has no hardwired paths. However,
  205. you should make sure that the shell on your path (named by the `SHELL'
  206. environment variable) is publicly readable.  Remember that GDB uses the
  207. shell to start your program--some systems refuse to let GDB debug child
  208. processes whose programs are not readable.
  209.  
  210.  
  211. Compiling GDB in another directory
  212. ==================================
  213.  
  214.    If you want to run GDB versions for several host or target machines,
  215. you need a different `gdb' compiled for each combination of host and
  216. target.  `configure' is designed to make this easy by allowing you to
  217. generate each configuration in a separate subdirectory, rather than in
  218. the source directory.  If your `make' program handles the `VPATH'
  219. feature correctly (GNU `make' and SunOS 'make' are two that should),
  220. running `make' in each of these directories builds the `gdb' program
  221. specified there.
  222.  
  223.    To build `gdb' in a separate directory, run `configure' with the
  224. `--srcdir' option to specify where to find the source. (You also need
  225. to specify a path to find `configure' itself from your working
  226. directory.  If the path to `configure' would be the same as the
  227. argument to `--srcdir', you can leave out the `--srcdir' option; it
  228. will be assumed.)
  229.  
  230.    For example, with version 4.9, you can build GDB in a separate
  231. directory for a Sun 4 like this:
  232.  
  233.      cd gdb-4.9
  234.      mkdir ../gdb-sun4
  235.      cd ../gdb-sun4
  236.      ../gdb-4.9/configure sun4
  237.      make
  238.  
  239.    When `configure' builds a configuration using a remote source
  240. directory, it creates a tree for the binaries with the same structure
  241. (and using the same names) as the tree under the source directory.  In
  242. the example, you'd find the Sun 4 library `libiberty.a' in the
  243. directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
  244.  
  245.    One popular reason to build several GDB configurations in separate
  246. directories is to configure GDB for cross-compiling (where GDB runs on
  247. one machine--the host--while debugging programs that run on another
  248. machine--the target).  You specify a cross-debugging target by giving
  249. the `--target=TARGET' option to `configure'.
  250.  
  251.    When you run `make' to build a program or library, you must run it
  252. in a configured directory--whatever directory you were in when you
  253. called `configure' (or one of its subdirectories).
  254.  
  255.    The `Makefile' that `configure' generates in each source directory
  256. also runs recursively.  If you type `make' in a source directory such
  257. as `gdb-4.9' (or in a separate configured directory configured with
  258. `--srcdir=PATH/gdb-4.9'), you will build all the required libraries,
  259. and then build GDB.
  260.  
  261.    When you have multiple hosts or targets configured in separate
  262. directories, you can run `make' on them in parallel (for example, if
  263. they are NFS-mounted on each of the hosts); they will not interfere
  264. with each other.
  265.  
  266.  
  267. Specifying names for hosts and targets
  268. ======================================
  269.  
  270.    The specifications used for hosts and targets in the `configure'
  271. script are based on a three-part naming scheme, but some short
  272. predefined aliases are also supported.  The full naming scheme encodes
  273. three pieces of information in the following pattern:
  274.  
  275.      ARCHITECTURE-VENDOR-OS
  276.  
  277.    For example, you can use the alias `sun4' as a HOST argument or in a
  278. `--target=TARGET' option.  The equivalent full name is
  279. `sparc-sun-sunos4'.
  280.  
  281.    The `configure' script accompanying GDB does not provide any query
  282. facility to list all supported host and target names or aliases. 
  283. `configure' calls the Bourne shell script `config.sub' to map
  284. abbreviations to full names; you can read the script, if you wish, or
  285. you can use it to test your guesses on abbreviations--for example:
  286.  
  287.      % sh config.sub sun4
  288.      sparc-sun-sunos411
  289.      % sh config.sub sun3
  290.      m68k-sun-sunos411
  291.      % sh config.sub decstation
  292.      mips-dec-ultrix42
  293.      % sh config.sub hp300bsd
  294.      m68k-hp-bsd
  295.      % sh config.sub i386v
  296.      i386-unknown-sysv
  297.      % sh config.sub i786v
  298.      Invalid configuration `i786v': machine `i786v' not recognized
  299.  
  300. `config.sub' is also distributed in the GDB source directory
  301. (`gdb-4.9', for version 4.9).
  302.  
  303.  
  304. `configure' options
  305. ===================
  306.  
  307.    Here is a summary of the `configure' options and arguments that are
  308. most often useful for building GDB.  `configure' also has several other
  309. options not listed here.  *note : (configure.info)What Configure Does,
  310. for a full explanation of `configure'.
  311.  
  312.      configure [--help]
  313.                [--prefix=DIR]
  314.                [--srcdir=PATH]
  315.                [--norecursion] [--rm]
  316.                [--target=TARGET] HOST
  317.  
  318. You may introduce options with a single `-' rather than `--' if you
  319. prefer; but you may abbreviate option names if you use `--'.
  320.  
  321. `--help'
  322.      Display a quick summary of how to invoke `configure'.
  323.  
  324. `-prefix=DIR'
  325.      Configure the source to install programs and files under directory
  326.      `DIR'.
  327.  
  328. `--srcdir=PATH'
  329.      *Warning: using this option requires GNU `make', or another `make'
  330.      that compatibly implements the `VPATH' feature.*
  331.      Use this option to make configurations in directories separate
  332.      from the GDB source directories.  Among other things, you can use
  333.      this to build (or maintain) several configurations simultaneously,
  334.      in separate directories.  `configure' writes configuration
  335.      specific files in the current directory, but arranges for them to
  336.      use the source in the directory PATH.  `configure' will create
  337.      directories under the working directory in parallel to the source
  338.      directories below PATH.
  339.  
  340. `--norecursion'
  341.      Configure only the directory level where `configure' is executed;
  342.      do not propagate configuration to subdirectories.
  343.  
  344. `--rm'
  345.      Remove the configuration that the other arguments specify.
  346.  
  347. `--target=TARGET'
  348.      Configure GDB for cross-debugging programs running on the specified
  349.      TARGET.  Without this option, GDB is configured to debug programs
  350.      that run on the same machine (HOST) as GDB itself.
  351.  
  352.      There is no convenient way to generate a list of all available
  353.      targets.
  354.  
  355. `HOST ...'
  356.      Configure GDB to run on the specified HOST.
  357.  
  358.      There is no convenient way to generate a list of all available
  359.      hosts.
  360.  
  361. `configure' accepts other options, for compatibility with configuring
  362. other GNU tools recursively; but these are the only options that affect
  363. GDB or its supporting libraries.
  364.  
  365.  
  366. Languages other than C
  367. =======================
  368.  
  369. GDB provides some support for debugging C++ progams.  Partial Modula-2
  370. and Chill support is now in GDB.  GDB should work with FORTRAN programs.
  371. (If you have problems, please send a bug report; you may have to refer to
  372. some FORTRAN variables with a trailing underscore).  Pascal programs which
  373. use sets, subranges, file variables, or nested functions will not
  374. currently work.
  375.  
  376.  
  377. Kernel debugging
  378. =================
  379.  
  380. I have't done this myself so I can't really offer any advice.
  381. Remote debugging over serial lines works fine, but the kernel debugging
  382. code in here has not been tested in years.  Van Jacobson has
  383. better kernel debugging, but the UC lawyers won't let FSF have it.
  384.  
  385.  
  386. Remote debugging
  387. =================
  388.  
  389. The files m68k-stub.c, i386-stub.c, and sparc-stub.c are examples of
  390. remote stubs to be used with remote.c.  They are designed to run
  391. standalone on an m68k, i386, or SPARC cpu and communicate properly with
  392. the remote.c stub over a serial line.
  393.  
  394. The file rem-multi.shar contains a general stub that can probably
  395. run on various different flavors of unix to allow debugging over a
  396. serial line from one machine to another.
  397.  
  398. Some working remote interfaces for talking to existing ROM monitors
  399. are:
  400.     remote-adapt.c     AMD 29000 "Adapt"
  401.     remote-eb.c     AMD 29000 "EBMON"
  402.     remote-es1800.c     Ericsson 1800 monitor
  403.     remote-hms.c     Hitachi Micro Systems H8/300 monitor
  404.     remote-mips.c     MIPS remote debugging protocol
  405.     remote-mm.c     AMD 29000 "minimon"
  406.     remote-nindy.c   Intel 960 "Nindy"
  407.     remote-sim.c     Generalized simulator protocol
  408.     remote-st2000.c     Tandem ST-2000 monitor
  409.     remote-udi.c     AMD 29000 using the AMD "Universal Debug Interface"
  410.     remote-vx.c     VxWorks realtime kernel
  411.     remote-z8k.c     Zilog Z8000 simulator
  412.  
  413. Remote-vx.c and the vx-share subdirectory contain a remote interface for the
  414. VxWorks realtime kernel, which communicates over TCP using the Sun
  415. RPC library.  This would be a useful starting point for other remote-
  416. via-ethernet back ends.
  417.  
  418. Remote-udi.c and the 29k-share subdirectory contain a remote interface
  419. for AMD 29000 programs, which uses the AMD "Universal Debug Interface".
  420. This allows GDB to talk to software simulators, emulators, and/or bare
  421. hardware boards, via network or serial interfaces.  Note that GDB only
  422. provides an interface that speaks UDI, not a complete solution.  You
  423. will need something on the other end that also speaks UDI.
  424.  
  425.  
  426. Reporting Bugs
  427. ===============
  428.  
  429. The correct address for reporting bugs found in gdb is
  430. "bug-gdb@prep.ai.mit.edu".  Please email all bugs to that address.
  431. Please include the GDB version number (e.g. gdb-4.9), and how
  432. you configured it (e.g. "sun4" or "mach386 host, i586-intel-synopsys
  433. target").
  434.  
  435. Known bugs:
  436.  
  437.   * Under Ultrix 4.2 (DECstation-3100), we have seen problems with backtraces
  438.     after interrupting the inferior out of a read().  The problem is caused by
  439.     ptrace() returning an incorrect value for register 30.  As far as we can
  440.     tell, this is a kernel problem.  Any help with this would be greatly
  441.     appreciated.
  442.  
  443.   * On the SPARC GDB reports incorrect values of struct arguments to
  444.     functions, for the seventh and subsequent arguments.  We have been looking
  445.     at this but no fix is available yet.
  446.  
  447.   * On DECstations there are warnings about shift counts out of range in
  448.     various BFD modules.  None of them is a cause for alarm, they are actually
  449.     a result of bugs in the DECstation compiler.
  450.  
  451.   * On Solaris using the "run" command when the program is already running
  452.     restarts the program, but may leave a core dump from the previous
  453.     execution in the current directory.  Other SVR4 based systems don't seem
  454.     to have this problem, using the same gdb source code.
  455.  
  456. GDB can produce warnings about symbols that it does not understand.  By
  457. default, these warnings are disabled.  You can enable them by executing
  458. `set complaint 10' (which you can put in your ~/.gdbinit if you like).
  459. I recommend doing this if you are working on a compiler, assembler,
  460. linker, or gdb, since it will point out problems that you may be able
  461. to fix.  Warnings produced during symbol reading indicate some mismatch
  462. between the object file and GDB's symbol reading code.  In many cases,
  463. it's a mismatch between the specs for the object file format, and what
  464. the compiler actually outputs or the debugger actually understands.
  465.  
  466.  
  467. X Windows versus GDB
  468. =====================
  469.  
  470. There is an "xxgdb", which seems to work for simple operations,
  471. which was posted to comp.sources.x.
  472.  
  473. For those interested in auto display of source and the availability of
  474. an editor while debugging I suggest trying gdb-mode in gnu-emacs
  475. (Try typing M-x gdb RETURN).  Comments on this mode are welcome.
  476.  
  477.  
  478. Writing Code for GDB
  479. =====================
  480.  
  481. There is a lot of information about writing code for GDB in the
  482. internals manual, distributed with GDB in gdb/doc/gdbint.texinfo.  You
  483. can read it by hand, print it by using TeX and texinfo, or process it
  484. into an `info' file for use with Emacs' info mode or the standalone
  485. `info' program.  In particular, see the nodes Getting Started,
  486. Debugging GDB, New Architectures, Coding Style, Clean Design, and
  487. Submitting Patches.
  488.  
  489. If you are pondering writing anything but a short patch, especially
  490. take note of the information about copyrights in the node Submitting
  491. Patches.  It can take quite a while to get all the paperwork done, so
  492. we encourage you to start that process as soon as you decide you are
  493. planning to work on something, or at least well ahead of when you
  494. think you will be ready to submit the patches.
  495.  
  496.  
  497. GDB Testsuite
  498. =============
  499.  
  500. There is a dejagnu based testsuite available for testing your newly
  501. built gdb, or for regression testing gdb's with local modifications.
  502. The testsuite is distributed separately from the base gdb distribution
  503. for the convenience of people that wish to get either gdb or the testsuite
  504. separately.
  505.  
  506. The name of the testsuite is gdb-4.9-testsuite.tar.z.  You unpack it in the
  507. same directory in which you unpacked the base gdb distribution, and it
  508. will create and populate the directory gdb-4.9/gdb/testsuite.
  509.  
  510. Running the testsuite requires the prior installation of dejagnu, which
  511. should be available via ftp.  Once dejagnu is installed, you can run
  512. the tests in one of two ways:
  513.  
  514.   (1)    cd gdb-4.9/gdb        (assuming you also unpacked gdb)
  515.     make check
  516.  
  517. or
  518.  
  519.   (2)    cd gdb-4.9/gdb/testsuite
  520.     make        (builds the test executables)
  521.     make site.exp    (builds the site specific file)
  522.     runtest -tool gdb GDB=../gdb    (or GDB=<somepath> as appropriate)
  523.  
  524. The second method gives you slightly more control in case of problems with
  525. building one or more test executables, in case you wish to remove some
  526. test executables before running the tests, or if you are using the testsuite
  527. 'standalone', without it being part of the gdb source tree.
  528.  
  529. See the dejagnu documentation for further details.
  530.  
  531.  
  532. (this is for editing this file with GNU emacs)
  533. Local Variables:
  534. mode: text
  535. End:
  536.