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.79.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 `djunpack' batch
  69 file to unzip the package.  That's because some file names in the
  70 official distributions need to be changed to avoid problems on the
  71 various platforms supported by DJGPP.  `djunpack' invokes the `djtar'
  72 program (that is part of the basic DJGPP development kit) to rename
  73 these files on the fly given a file with name mappings; the
  74 distribution includes a file `gdb/config/djgpp/fnchange.lst' with the
  75 necessary mappings.  So you need first to retrieve that batch file,
  76 and then invoke it to unpack the distribution.  Here's how:
  77
  78  djtar -x -p -o gdb-5.1/djunpack.bat gdb-5.1.tar.gz > djunpack.bat
  79  djunpack gdb-5.1.tar.gz
  80
  81 (The name of the distribution archive and the leading directory of the
  82 path to `djunpack.bat' in the distribution will be different for
  83 versions of GDB other than 5.1.)
  84
  85 If the argument to `djunpack.bat' include leading directories, it MUST
  86 be given with the DOS-style backslashes; Unix-style forward slashes
  87 will NOT work.
  88
  89 If the distribution comes as a .tar.bz2 archive, and your version of
  90 `djtar' doesn't support bzip2 decompression, you need to unpack it as
  91 follows:
  92
  93  bnzip2 gdb-5.1.tar.bz2
  94  djtar -x -p -o gdb-5.1/djunpack.bat gdb-5.1.tar > djunpack.bat
  95  djunpack gdb-5.1.tar
  96
  97
  98 3. How to build
  99    ------------
 100
 101 The source distribution available from DJGPP archives is already
 102 configured for DJGPP v2.x, so if you only want to compile it, just
 103 invoke Make:
 104
 105                 make
 106
 107 To build a package downloaded from a GNU FTP site, you will need o
 108 configure it first.  You will also need to configure it if you want to
 109 change the configuration options (e.g., compile without support for the
 110 GDBMI interface).  To configure GDB, type this command:
 111
 112                 sh ./gdb/config/djgpp/djconfig.sh
 113
 114 This script checks the unpacked distribution, then edits the configure
 115 scripts in the various subdirectories, to make them suitable for
 116 DJGPP, and finally invokes the top-level configure script, which
 117 recursively configures all the subdirectories.
 118
 119 You may pass optional switches to djconfig.sh.  It accepts all the
 120 switches accepted by the original GDB configure script.  These
 121 switches are described in the file gdb/README, and their full list can
 122 be displayed by running the following command:
 123
 124                 sh ./gdb/configure --help
 125
 126 NOTE: if you *do* use optional command-line switches, you MUST pass
 127 to the script the name of the directory where GDB sources are
 128 unpacked--even if you are building GDB in-place!  For example:
 129
 130         sh ./gdb/config/djgpp/djconfig.sh . --disable-gdbmi
 131
 132 It is also possible to build GDB in a directory that is different from
 133 the one where the sources were unpacked.  In that case, you have to
 134 pass the source directory as the first argument to the script:
 135
 136         sh ./gdb/config/djgpp/djconfig.sh d:/gnu/gdb-5.1
 137
 138 You MUST use forward slashes in the first argument.
 139
 140 After the configure script finishes, run Make:
 141
 142         make
 143
 144 If you want to produce the documentation (for example, if you changed
 145 some of the Texinfo sources), type this:
 146
 147         make info
 148
 149 When Make finishes, you can install the package:
 150
 151         make -k install prefix='${DJDIR}' INSTALL='ginstall -c'
 152
 153 The above doesn't install the docs; for that you will need to say
 154 this:
 155
 156         make -k install-info prefix='${DJDIR}' INSTALL='ginstall -c'
 157
 158 (The -k switch is required, because some unneeded targets that are
 159 part of the install process fail; -k lets Make run to completion
 160 nonetheless.)
 161
 162 The test suite has been made to work with DJGPP.  If you make a change
 163 in some of the programs, or want to be sure you have a fully
 164 functional GDB executable, it is a good idea to run the test suite.
 165 You cannot use "make check" for that, since it will want to run the
 166 `dejagnu' utility which GDB doesn't support.  Instead, use the special
 167 script gdb/config/djgpp/djcheck.sh, like this:
 168
 169                 cd gdb/testsuite
 170                 sh ../config/djgpp/djcheck.sh
 171
 172 This will run for a while and should not print anything, except the
 173 messages "Running tests in DIR", where DIR is one of the
 174 subdirectories of the testsuite.  Any test that fails to produce the
 175 expected output will cause the diffs between the expected and the
 176 actual output be printed, and in addition will leave behind a file
 177 SOMETHING.tst (where SOMETHING is the name of the failed test).  You
 178 should compare each of the *.tst files with the corresponding *.out
 179 file and convince yourself that the differences do not indicate a real
 180 problem.  Examples of differences you can disregard are changes in the
 181 copyright blurb printed by GDB, values of unitialized variables,
 182 addresses of global variables like argv[] and envp[] (which depend on
 183 the size of your environment), etc.
 184
 185 Note that djcheck.sh only recurses into those of the subdirectories of
 186 the test suite which test features supported by the DJGPP port of GDB.
 187 For example, the tests in the gdb.gdbtk, gdb.threads, and gdb.hp
 188 directories are not run.
 189
 190
 191 Enjoy,
 192                                     Eli Zaretskii <eliz@is.elta.co.il>