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