| 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.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 |
| 82 | path to `djunpack.bat' in the distribution will be different for |
| 83 | versions of GDB other than 5.2.) |
| 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 | bunzip2 gdb-6.4.tar.bz2 |
| 94 | djtar -x -p -o gdb-6.4/djunpack.bat gdb-6.4.tar > djunpack.bat |
| 95 | djunpack gdb-6.4.tar |
| 96 | |
| 97 | |
| 98 | 3. How to build |
| 99 | ------------ |
| 100 | |
| 101 | If the source distribution available from DJGPP archives is already |
| 102 | configured 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 | |
| 107 | To build a package that is not yet configured, or if you downloaded |
| 108 | GDB from a GNU FTP site, you will need to configure it first. You |
| 109 | will also need to configure it if you want to change the configuration |
| 110 | options (e.g., compile without support for the GDBMI interface). To |
| 111 | configure GDB, type this command: |
| 112 | |
| 113 | sh ./gdb/config/djgpp/djconfig.sh |
| 114 | |
| 115 | This script checks the unpacked distribution, then edits the configure |
| 116 | scripts in the various subdirectories, to make them suitable for |
| 117 | DJGPP, and finally invokes the top-level configure script, which |
| 118 | recursively configures all the subdirectories. |
| 119 | |
| 120 | You may pass optional switches to djconfig.sh. It accepts all the |
| 121 | switches accepted by the original GDB configure script. These |
| 122 | switches are described in the file gdb/README, and their full list can |
| 123 | be displayed by running the following command: |
| 124 | |
| 125 | sh ./gdb/configure --help |
| 126 | |
| 127 | NOTE: if you *do* use optional command-line switches, you MUST pass |
| 128 | to the script the name of the directory where GDB sources are |
| 129 | unpacked--even if you are building GDB in-place! For example: |
| 130 | |
| 131 | sh ./gdb/config/djgpp/djconfig.sh . --disable-gdbmi |
| 132 | |
| 133 | It is also possible to build GDB in a directory that is different from |
| 134 | the one where the sources were unpacked. In that case, you have to |
| 135 | pass the source directory as the first argument to the script: |
| 136 | |
| 137 | sh ./gdb/config/djgpp/djconfig.sh d:/gnu/gdb-6.4 |
| 138 | |
| 139 | You MUST use forward slashes in the first argument. |
| 140 | |
| 141 | After the configure script finishes, run Make: |
| 142 | |
| 143 | make |
| 144 | |
| 145 | If you want to produce the documentation (for example, if you changed |
| 146 | some of the Texinfo sources), type this: |
| 147 | |
| 148 | make info |
| 149 | |
| 150 | When Make finishes, you can install the package: |
| 151 | |
| 152 | make install prefix='${DJDIR}' INSTALL='ginstall -c' |
| 153 | |
| 154 | The above doesn't install the docs; for that you will need to say |
| 155 | this: |
| 156 | |
| 157 | make install-info prefix='${DJDIR}' INSTALL='ginstall -c' |
| 158 | |
| 159 | The test suite has been made to work with DJGPP. If you make a change |
| 160 | in some of the programs, or want to be sure you have a fully |
| 161 | functional GDB executable, it is a good idea to run the test suite. |
| 162 | You cannot use "make check" for that, since it will want to run the |
| 163 | `dejagnu' utility which DJGPP doesn't support. Instead, use the special |
| 164 | script gdb/config/djgpp/djcheck.sh, like this: |
| 165 | |
| 166 | cd gdb/testsuite |
| 167 | sh ../config/djgpp/djcheck.sh |
| 168 | |
| 169 | This will run for a while and should not print anything, except the |
| 170 | messages "Running tests in DIR", where DIR is one of the |
| 171 | subdirectories of the testsuite. Any test that fails to produce the |
| 172 | expected output will cause the diffs between the expected and the |
| 173 | actual output be printed, and in addition will leave behind a file |
| 174 | SOMETHING.tst (where SOMETHING is the name of the failed test). You |
| 175 | should compare each of the *.tst files with the corresponding *.out |
| 176 | file and convince yourself that the differences do not indicate a real |
| 177 | problem. Examples of differences you can disregard are changes in the |
| 178 | copyright blurb printed by GDB, values of unitialized variables, |
| 179 | addresses of global variables like argv[] and envp[] (which depend on |
| 180 | the size of your environment), etc. |
| 181 | |
| 182 | Note that djcheck.sh only recurses into those of the subdirectories of |
| 183 | the test suite which test features supported by the DJGPP port of GDB. |
| 184 | For example, the tests in the gdb.gdbtk, gdb.threads, and gdb.hp |
| 185 | directories are not run. |
| 186 | |
| 187 | |
| 188 | Enjoy, |
| 189 | Eli Zaretskii <eliz@gnu.org> |