gdb/config/djgpp/README

   1
   2        How to build and install the DJGPP native version of GDB
   3        ********************************************************
   4
   5 General
   6 =======
   7
   8 GDB built with DJGPP supports native DJGPP debugging, whereby you run
   9 gdb.exe and the program being debugged on the same machine.  In
  10 addition, this version supports remote debugging via a serial port,
  11 provided that the target machine has a GDB-compatible debugging stub
  12 which can be linked with the target program (see the section "Remote
  13 Serial" in the GDB manual for more details).
  14
  15
  16 Installation of the binary distribution
  17 =======================================
  18
  19 Simply unzip the gdbNNNb.zip file (where NNN is the version number)
  20 from the top DJGPP installation directory.  Be sure to preserve the
  21 directory structure while you unzip (use -d switch if you do this with
  22 PKUNZIP).  On Windows 9X and Windows 2000, use an unzip program which
  23 supports long file names; one such program is unzip32.exe, available
  24 from the DJGPP sites.
  25
  26 If you need the libraries which are built as part of GDB, install the
  27 companion file gdbNNNa.zip.  This allows to develop applications which
  28 use the same functions as GDB.  For example, you can build your own
  29 front end to the debugger.
  30
  31
  32 Rebuilding GDB from sources
  33 ===========================
  34
  35 1. Prerequisites
  36    -------------
  37 To build the package, you will need the DJGPP development environment
  38 (GCC, header files, and the libraries), and also DJGPP ports of the
  39 following tools:
  40
  41         - GNU Make 3.78.1 or later
  42         - Bash 2.03 or later
  43         - GNU Sed
  44         - GNU Fileutils
  45         - GNU Textutils 2.0 or later
  46         - GNU Sh-utils
  47         - GNU Grep 2.4 or later
  48         - GNU Findutils
  49         - GNU Awk 3.04 or later
  50         - GNU Bison (only if you change one of the gdb/*.y files)
  51         - Groff (only if you need to format the man pages)
  52         - GNU Diffutils (only if you run the test suite)
  53
  54 These programs should be available from the DJGPP sites, in the v2gnu
  55 directory.  In addition, the configuration script invokes the `update'
  56 and `utod' utilities which are part of the basic DJGPP development kit
  57 (djdevNNN.zip).
  58
  59
  60 2. Unpacking the sources
  61    ---------------------
  62 If you download the source distribution from one of the DJGPP sites,
  63 just unzip it while preserving the directory structure (I suggest to
  64 use unzip32.exe available with the rest of DJGPP), and proceed to the
  65 section "How to build" below.
  66
  67 Source distributions downloaded from one of the GNU FTP sites need
  68 some more work to unpack.  First, you MUST use the `djtar' program to
  69 unzip the package.  That's because some file names in the official
  70 distributions need to be changed to avoid problems on the various
  71 platforms supported by DJGPP.  `djtar' can rename files on the fly
  72 given a file with name mappings; the distribution includes a file
  73 `gdb/config/djgpp/fnchange.lst' with the necessary mappings.  So you
  74 need first to retrieve that file, and then invoke `djtar' to unpack
  75 the distribution.  Here's how:
  76
  77
  78  djtar -x -p -o gdb-5.0/gdb/config/djgpp/fnchange.lst gdb-5.0.tar.gz > lst
  79  djtar -x -n lst gdb-5.0.tar.gz
  80
  81 (The name of the distribution archive and the top-level directory will
  82 be different for versions other than 5.0.)
  83
  84
  85 3. How to build
  86    ------------
  87
  88 The source distribution available from DJGPP archives is already
  89 configured for DJGPP v2.x, so if you only want to compile it, just
  90 invoke Make:
  91
  92                 make
  93
  94 To build a package downloaded from a GNU FTP site, you will need o
  95 configure it first.  You will also need to configure it if you want to
  96 change the configuration options (e.g., compile with support for the
  97 GDBMI interface).  To configure GDB, type this command:
  98
  99                 sh ./gdb/config/djgpp/djconfig.sh
 100
 101 This script checks the unpacked distribution, then edits the configure
 102 scripts in the various subdirectories, to make them suitable for
 103 DJGPP, and finally invokes the top-level configure script, which
 104 recursively configures all the subdirectories.
 105
 106 You may pass optional switches to djconfig.sh.  It accepts all the
 107 switches accepted by the original GDB configure script.  These
 108 switches are described in the file gdb/README, and their full list be
 109 displayed by running the following command:
 110
 111                 sh ./gdb/configure --help
 112
 113 NOTE: if you *do* use optional command-line switches, you MUST pass
 114 to the script the name of the directory where GDB sources are
 115 unpacked--even if you are building GDB in-place!  For example:
 116
 117         sh ./gdb/config/djgpp/djconfig.sh . --enable-gdbmi
 118
 119 It is also possible to build GDB in a directory that is different from
 120 the one where the sources were unpacked.  In that case, you have to
 121 pass the source directory as the first argument to the script:
 122
 123         sh ./gdb/config/djgpp/djconfig.sh d:/gnu/gdb-5.0
 124
 125 You MUST use forward slashes in the first argument.
 126
 127 After the configure script finishes, run Make:
 128
 129         make
 130
 131 When Make finishes, you can install the package:
 132
 133         make install INSTALL='/dev/env/DJDIR/bin/ginstall -c'
 134
 135 The above doesn't install the docs; for that you will need to say
 136 this:
 137
 138         make -k install-info INSTALL='/dev/env/DJDIR/bin/ginstall -c'
 139
 140 (The -k switch is required, because some unneeded targets that are
 141 part of the install process fail; -k lets Make run to completion
 142 nonetheless.)
 143
 144 The test suite has been made to work with DJGPP.  If you make a change
 145 in some of the programs, or want to be sure you have a fully
 146 functional GDB executable, it is a good idea to run the test suite.
 147 You cannot use "make check" for that, since it will want to run the
 148 `dejagnu' utility which GDB doesn't support.  Instead, use the special
 149 script gdb/config/djgpp/djcheck.sh, like this:
 150
 151                 cd gdb/testsuite
 152                 sh ../config/djgpp/djcheck.sh
 153
 154 This will run for a while and should not print anything.  Any test
 155 that fails to produce the expected output will cause the diffs between
 156 the expected and the actual output be printed, and in addition will
 157 leave behind a file SOMETHING.tst (where SOMETHING is the name of one
 158 of the tests).  You should compare each of the *.tst files with the
 159 corresponding *.out file and convince yourself that the differences do
 160 not indicate a real problem.  Examples of differences you can
 161 disregard are changes in the copyright blurb printed by GDB, values of
 162 unitialized variables, addresses of global variables like argv[] and
 163 envp[] (which depend on the size of your environment), etc.
 164
 165 Note that djcheck.sh only recurses into those of the subdirectories of
 166 the test suite which test features supported by the DJGPP port of GDB.
 167 For example, the tests in the gdb.gdbtk, gdb.threads, and gdb.hp
 168 directories are not run.
 169
 170
 171 Enjoy,
 172                                     Eli Zaretskii <eliz@is.elta.co.il>