Commit | Line | Data |
---|---|---|
ee7270cd JG |
1 | README for gdb-4.4 release |
2 | John Gilmore & Stu Grossman 31 Jan 1992 | |
c45c19f8 | 3 | |
846058ed | 4 | This is GDB, the GNU source-level debugger, presently running under un*x. |
ee7270cd | 5 | A summary of new features is in the file `WHATS.NEW'. |
c45c19f8 | 6 | |
bd5635a1 | 7 | |
846058ed JG |
8 | Unpacking and Installation -- quick overview |
9 | ========================== | |
bd5635a1 | 10 | |
fbda4193 JG |
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 a miscellaneous library all have directories of their own underneath | |
ee7270cd | 14 | the gdb-4.4 directory. The idea is that a variety of GNU tools can |
fbda4193 JG |
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. | |
bd5635a1 | 18 | |
ee7270cd JG |
19 | When you unpack the gdb-4.4.tar.Z file, you'll get a directory called |
20 | `gdb-4.4', which contains: | |
bd5635a1 | 21 | |
ee7270cd JG |
22 | DOC.configure bfd/ configure* glob/ readline/ |
23 | Makefile.in config/ configure.in include/ texinfo/ | |
24 | README config.sub* gdb/ libiberty/ | |
170d0c85 | 25 | |
846058ed | 26 | To build GDB, you can just do: |
170d0c85 | 27 | |
ee7270cd | 28 | cd gdb-4.4 |
fbda4193 | 29 | ./configure HOSTTYPE (e.g. sun4, decstation) |
170d0c85 | 30 | make |
846058ed | 31 | cp gdb/gdb /usr/local/bin/gdb (or wherever you want) |
170d0c85 | 32 | |
846058ed | 33 | This will configure and build all the libraries as well as GDB. |
c45c19f8 JG |
34 | If you get compiler warnings during this stage, see the `Reporting Bugs' |
35 | section below; there are a few known problems. | |
361cc81a | 36 | |
c45c19f8 | 37 | GDB can be used as a cross-debugger, running on a machine of one type |
846058ed JG |
38 | while debugging a program running on a machine of another type. See below. |
39 | ||
40 | ||
41 | More Documentation | |
42 | ================== | |
43 | ||
ee7270cd | 44 | The GDB 4.4 release includes an already-formatted reference card, |
fbda4193 | 45 | ready for printing on a PostScript printer, as |
ee7270cd | 46 | `gdb-4.4/gdb/refcard.ps'. It uses the most common PostScript fonts: |
fbda4193 JG |
47 | the Times family, Courier, and Symbol. If you have a PostScript |
48 | printer, you can print the reference card by just sending `refcard.ps' | |
49 | to the printer. | |
846058ed | 50 | |
fbda4193 | 51 | The release also includes the online Info version of this manual |
ee7270cd | 52 | already formatted: the main Info file is `gdb-4.4/gdb/gdb.info', and it |
fbda4193 | 53 | refers to subordinate files matching `gdb.info*' in the same directory. |
846058ed | 54 | |
fbda4193 JG |
55 | If you want to make these Info files yourself from the GDB manual's |
56 | source, you need the GNU `makeinfo' program. Once you have it, you | |
57 | can type | |
846058ed | 58 | |
ee7270cd | 59 | cd gdb-4.4/gdb |
846058ed JG |
60 | make gdb.info |
61 | ||
62 | to make the Info file. | |
63 | ||
fbda4193 | 64 | If you want to format and print copies of the manual, you need |
846058ed JG |
65 | several things: |
66 | ||
67 | * TeX, the public domain typesetting program written by Donald | |
68 | Knuth, must be installed on your system and available through | |
69 | your execution path. | |
70 | ||
ee7270cd | 71 | * `gdb-4.4/texinfo': TeX macros defining the GNU Documentation |
846058ed JG |
72 | Format. |
73 | ||
fbda4193 JG |
74 | * *A DVI output program.* TeX does not actually make marks on |
75 | paper; it produces output files called DVI files. If your system | |
76 | has TeX installed, chances are it has a program for printing out | |
77 | these files; one popular example is `dvips', which can print DVI | |
78 | files on PostScript printers. | |
846058ed JG |
79 | |
80 | Once you have these things, you can type | |
170d0c85 | 81 | |
ee7270cd | 82 | cd gdb-4.4/gdb |
846058ed | 83 | make gdb.dvi |
170d0c85 | 84 | |
846058ed JG |
85 | to format the text of this manual, and print it with the usual output |
86 | method for TeX DVI files at your site. | |
bd5635a1 | 87 | |
fbda4193 JG |
88 | If you want to print the reference card, but do not have a |
89 | PostScript printer, or you want to use Computer Modern fonts instead, | |
90 | you can still print it if you have TeX. Format the reference card by | |
91 | typing | |
bd5635a1 | 92 | |
ee7270cd | 93 | cd gdb-4.4/gdb |
846058ed | 94 | make refcard.dvi |
c45c19f8 | 95 | |
846058ed | 96 | The GDB reference card is designed to print in landscape mode on US |
fbda4193 JG |
97 | "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches |
98 | high. You will need to specify this form of printing as an option to | |
99 | your DVI output program. | |
c45c19f8 JG |
100 | |
101 | ||
846058ed JG |
102 | Installing GDB |
103 | ============== | |
c45c19f8 | 104 | |
846058ed JG |
105 | GDB comes with a `configure' script that automates the process of |
106 | preparing GDB for installation; you can then use `make' to build the | |
107 | `gdb' program. | |
c45c19f8 | 108 | |
846058ed | 109 | The gdb distribution includes all the source code you need for gdb |
ee7270cd | 110 | in a single directory `gdb-4.4'. That directory in turn contains: |
c45c19f8 | 111 | |
ee7270cd | 112 | `gdb-4.4/configure (and supporting files)' |
fbda4193 | 113 | script for configuring GDB and all its supporting libraries. |
c45c19f8 | 114 | |
ee7270cd | 115 | `gdb-4.4/gdb' |
c45c19f8 JG |
116 | the source specific to GDB itself |
117 | ||
ee7270cd | 118 | `gdb-4.4/bfd' |
c45c19f8 JG |
119 | source for the Binary File Descriptor Library |
120 | ||
ee7270cd | 121 | `gdb-4.4/include' |
c45c19f8 JG |
122 | GNU include files |
123 | ||
ee7270cd | 124 | `gdb-4.4/libiberty' |
c45c19f8 JG |
125 | source for the `-liberty' free software library |
126 | ||
ee7270cd | 127 | `gdb-4.4/readline' |
c45c19f8 JG |
128 | source for the GNU command-line interface |
129 | ||
ee7270cd | 130 | It is most convenient to run `configure' from the `gdb-4.4' directory. |
fbda4193 | 131 | The simplest way to configure and build GDB is the following: |
c45c19f8 | 132 | |
ee7270cd | 133 | cd gdb-4.4 |
c45c19f8 JG |
134 | ./configure HOST |
135 | make | |
136 | ||
846058ed JG |
137 | where HOST is something like `sun4' or `decstation', that identifies |
138 | the platform where GDB will run. This builds the three libraries | |
fbda4193 JG |
139 | `bfd', `readline', and `libiberty', then `gdb' itself. The configured |
140 | source files, and the binaries, are left in the corresponding source | |
141 | directories. | |
142 | ||
143 | `configure' is a Bourne-shell (`/bin/sh') script; if your system | |
144 | does not recognize this automatically when you run a different shell, | |
145 | you may need to run `sh' on it explicitly: `sh configure HOST'. | |
146 | ||
147 | You can *run* the `configure' script from any of the subordinate | |
148 | directories in the GDB distribution (if you only want to configure | |
149 | that subdirectory); but be sure to specify a path to it. For example, | |
150 | to configure only the `bfd' subdirectory, | |
151 | ||
ee7270cd | 152 | cd gdb-4.4/bfd |
fbda4193 JG |
153 | ../configure HOST |
154 | ||
155 | You can install `gdb' anywhere; it has no hardwired paths. Simply | |
156 | copy `gdb/gdb' to the desired directory. | |
c45c19f8 | 157 | |
fbda4193 | 158 | However, you should make sure that the shell on your path (named by |
c45c19f8 JG |
159 | the `SHELL' environment variable) is publicly readable; some systems |
160 | refuse to let GDB debug child processes whose programs are not | |
161 | readable, and GDB uses the shell to start your program. | |
162 | ||
fbda4193 | 163 | |
846058ed JG |
164 | Configuration Subdirectories |
165 | ============================ | |
166 | ||
fbda4193 JG |
167 | If you want to run GDB versions for several host or target machines, |
168 | you'll need a different gdb compiled for each combination of host and | |
169 | target. `configure' is designed to make this easy by allowing you to | |
170 | generate each configuration in a separate subdirectory. If your | |
171 | `make' program handles the `VPATH' feature (GNU `make' does), running | |
172 | `make' in each of these directories then builds the gdb program | |
173 | specified there. | |
846058ed JG |
174 | |
175 | `configure' creates these subdirectories for you when you | |
fbda4193 | 176 | simultaneously specify several configurations; but it is a good habit |
846058ed | 177 | even for a single configuration. You can specify the use of |
fbda4193 JG |
178 | subdirectories using the `+subdirs' option (abbreviated `+sub'). For |
179 | example, you can build GDB this way on a Sun 4 as follows: | |
846058ed | 180 | |
ee7270cd | 181 | cd gdb-4.4 |
846058ed | 182 | ./configure +sub sun4 |
fbda4193 | 183 | cd H-sun4/T-sun4 |
c45c19f8 JG |
184 | make |
185 | ||
186 | When `configure' uses subdirectories to build programs or | |
fbda4193 | 187 | libraries, it creates nested directories `H-HOST/T-TARGET'. |
846058ed | 188 | `configure' uses these two directory levels because GDB can be |
fbda4193 JG |
189 | configured for cross-compiling: GDB can run on one machine (the host) |
190 | while debugging programs that run on another machine (the target). | |
191 | You specify cross-debugging targets by giving the `+target=TARGET' | |
192 | option to `configure'. Specifying only hosts still gives you two | |
193 | levels of subdirectory for each host, with the same configuration | |
194 | suffix on both; that is, if you give any number of hosts but no | |
195 | targets, GDB will be configured for native debugging on each host. On | |
196 | the other hand, whenever you specify both hosts and targets on the | |
197 | same command line, `configure' creates all combinations of the hosts | |
198 | and targets you list. | |
199 | ||
ee7270cd | 200 | If you run `configure' from a directory (notably, `gdb-4.4') that |
c45c19f8 | 201 | contains source directories for multiple libraries or programs, |
fbda4193 JG |
202 | `configure' creates the `H-HOST/T-TARGET' subdirectories in each |
203 | library or program's source directory. For example, typing: | |
c45c19f8 | 204 | |
ee7270cd | 205 | cd gdb-4.4 |
846058ed | 206 | configure sun4 +target=vxworks960 |
c45c19f8 JG |
207 | |
208 | creates the following directories: | |
209 | ||
ee7270cd JG |
210 | gdb-4.4/H-sun4/T-vxworks960 |
211 | gdb-4.4/bfd/H-sun4/T-vxworks960 | |
212 | gdb-4.4/gdb/H-sun4/T-vxworks960 | |
213 | gdb-4.4/libiberty/H-sun4/T-vxworks960 | |
214 | gdb-4.4/readline/H-sun4/T-vxworks960 | |
846058ed | 215 | |
fbda4193 JG |
216 | When you run `make' to build a program or library, you must run it |
217 | in a configured directory. If you made a single configuration, | |
218 | without subdirectories, run `make' in the source directory. If you | |
219 | have `H-HOST/T-TARGET' subdirectories, run `make' in those | |
220 | subdirectories. | |
846058ed | 221 | |
fbda4193 | 222 | The `Makefile' generated by `configure' for each source directory |
ee7270cd JG |
223 | runs recursively, so that typing `make' in `gdb-4.4' (or in a |
224 | `gdb-4.4/H-HOST/T-TARGET' subdirectory) builds all the required | |
fbda4193 | 225 | libraries, then GDB. |
c45c19f8 JG |
226 | |
227 | When you have multiple hosts or targets configured, you can run | |
228 | `make' on them in parallel (for example, if they are NFS-mounted on | |
229 | each of the hosts); they will not interfere with each other. | |
230 | ||
fbda4193 JG |
231 | You can also use the `+objdir=ALTROOT' option to have the |
232 | configured files placed in a parallel directory structure rather than | |
233 | alongside the source files; *note configure Options::.. | |
234 | ||
235 | ||
846058ed JG |
236 | Specifying Names for Hosts and Targets |
237 | ====================================== | |
238 | ||
239 | The specifications used for hosts and targets in the `configure' | |
240 | script are based on a three-part naming scheme, but some short | |
fbda4193 JG |
241 | predefined aliases are also supported. The full naming scheme encodes |
242 | three pieces of information in the following pattern: | |
846058ed JG |
243 | |
244 | ARCHITECTURE-VENDOR-OS | |
245 | ||
246 | For example, you can use the alias `sun4' as a HOST argument or in | |
fbda4193 JG |
247 | a `+target=TARGET' option, but the equivalent full name is |
248 | `sparc-sun-sunos4'. | |
846058ed JG |
249 | |
250 | The following table shows all the architectures, hosts, and OS | |
ee7270cd | 251 | prefixes that `configure' recognizes in GDB 4.4. Entries in the "OS |
fbda4193 JG |
252 | prefix" column ending in a `*' may be followed by a release number. |
253 | ||
254 | ||
255 | ARCHITECTURE VENDOR OS prefix | |
256 | ------------+--------------------------+--------------------------- | |
257 | | | | |
258 | 580 | altos hp | aix* msdos* | |
259 | a29k | amd ibm | amigados newsos* | |
260 | alliant | amdahl intel | aout nindy* | |
261 | arm | aout isi | bout osf* | |
262 | c1 | apollo little | bsd* sco* | |
263 | c2 | att mips | coff sunos* | |
264 | cray2 | bcs motorola | ctix* svr4 | |
265 | h8300 | bout ncr | dgux* sym* | |
266 | i386 | bull next | dynix* sysv* | |
267 | i860 | cbm nyu | ebmon ultrix* | |
268 | i960 | coff sco | esix* unicos* | |
269 | m68000 | convergent sequent | hds unos* | |
270 | m68k | convex sgi | hpux* uts | |
271 | m88k | cray sony | irix* v88r* | |
272 | mips | dec sun | isc* vms* | |
273 | ns32k | encore unicom | kern vxworks* | |
274 | pyramid | gould utek | mach* | |
275 | romp | hitachi wrs | | |
276 | rs6000 | | | |
277 | sparc | | | |
278 | tahoe | | | |
279 | tron | | | |
280 | vax | | | |
281 | xmp | | | |
282 | ymp | | | |
283 | ||
284 | *Warning:* `configure' can represent a very large number of | |
285 | combinations of architecture, vendor, and OS. There is by no | |
286 | means support available for all possible combinations! | |
287 | ||
ee7270cd | 288 | The `configure' script accompanying GDB 4.4 does not provide any |
fbda4193 JG |
289 | query facility to list all supported host and target names or aliases. |
290 | `configure' calls the Bourne shell script `config.sub' to map | |
291 | abbreviations to full names; you can read the script, if you wish, or | |
292 | you can use it to test your guesses on abbreviations--for example: | |
846058ed JG |
293 | |
294 | % sh config.sub sun4 | |
295 | sparc-sun-sunos4 | |
296 | % sh config.sub sun3 | |
297 | m68k-sun-sunos4 | |
298 | % sh config.sub decstation | |
299 | mips-dec-ultrix | |
300 | % sh config.sub hp300bsd | |
301 | m68k-hp-bsd | |
302 | % sh config.sub i386v | |
303 | i386-none-sysv | |
304 | % sh config.sub i486v | |
fbda4193 JG |
305 | *** Configuration "i486v" not recognized |
306 | ||
ee7270cd | 307 | `config.sub' is also distributed in the directory `gdb-4.4'. |
fbda4193 | 308 | |
846058ed JG |
309 | |
310 | `configure' Options | |
311 | =================== | |
c45c19f8 | 312 | |
fbda4193 JG |
313 | Here is a summary of all the `configure' options and arguments that |
314 | you might use for building GDB: | |
c45c19f8 | 315 | |
fbda4193 JG |
316 | configure [+destdir=DIR] [+subdirs] |
317 | [+objdir=ALTROOT] [+norecursion] [+rm] | |
846058ed | 318 | [+target=TARGET...] HOST... |
c45c19f8 JG |
319 | |
320 | You may introduce options with the character `-' rather than `+' if | |
846058ed | 321 | you prefer; but you may abbreviate option names if you use `+'. |
c45c19f8 JG |
322 | |
323 | `+destdir=DIR' | |
324 | DIR is an installation directory *path prefix*. After you | |
325 | configure with this option, `make install' will install GDB as | |
326 | `DIR/bin/gdb', and the libraries in `DIR/lib'. If you specify | |
c45c19f8 JG |
327 | `+destdir=/usr/local', for example, `make install' creates |
328 | `/usr/local/bin/gdb'. | |
329 | ||
846058ed | 330 | `+subdirs' |
c45c19f8 JG |
331 | Write configuration specific files in subdirectories of the form |
332 | ||
fbda4193 | 333 | H-HOST/T-TARGET |
c45c19f8 | 334 | |
fbda4193 JG |
335 | (and configure the `Makefile' to generate object code in |
336 | subdirectories of this form as well). Without this option, if you | |
337 | specify only one configuration for GDB, `configure' will use the | |
338 | same directory for source, configured files, and binaries. This | |
339 | option is used automatically if you specify more than one HOST or | |
340 | more than one `+target=TARGET' option on the `configure' command | |
341 | line. | |
c45c19f8 | 342 | |
fbda4193 JG |
343 | `+norecursion' |
344 | Configure only the directory where `configure' is executed; do not | |
345 | propagate configuration to subdirectories. | |
346 | ||
347 | `+objdir=ALTROOT' | |
348 | ALTROOT is an alternative directory used as the root for | |
349 | configured files. `configure' will create directories under | |
350 | ALTROOT in parallel to the source directories. If you use | |
351 | `+objdir=ALTROOT' with `+subdirs', `configure' also builds the | |
352 | `H-HOST/T-TARGET' subdirectories in the directory tree rooted in | |
353 | ALTROOT. | |
c45c19f8 JG |
354 | |
355 | `+rm' | |
846058ed | 356 | Remove the configuration that the other arguments specify. |
c45c19f8 | 357 | |
846058ed | 358 | `+target=TARGET ...' |
c45c19f8 | 359 | Configure GDB for cross-debugging programs running on each |
846058ed JG |
360 | specified TARGET. You may specify as many `+target' options as |
361 | you wish. Without this option, GDB is configured to debug | |
362 | programs that run on the same machine (HOST) as GDB itself. | |
363 | ||
364 | There is no convenient way to generate a list of all available | |
365 | targets. | |
c45c19f8 JG |
366 | |
367 | `HOST ...' | |
368 | Configure GDB to run on each specified HOST. You may specify as | |
846058ed JG |
369 | many host names as you wish. |
370 | ||
371 | There is no convenient way to generate a list of all available | |
372 | hosts. | |
c45c19f8 JG |
373 | |
374 | `configure' accepts other options, for compatibility with configuring | |
375 | other GNU tools recursively; but these are the only options that | |
376 | affect GDB or its supporting libraries. | |
bd5635a1 | 377 | |
bd5635a1 | 378 | |
c45c19f8 | 379 | Languages other than C |
bd5635a1 | 380 | |
fbda4193 JG |
381 | C++ support has been integrated into gdb. Partial Modula-2 support is |
382 | now in GDB. GDB should work with FORTRAN programs. (If you have | |
383 | problems, please send a bug report; you may have to refer to some | |
384 | FORTRAN variables with a trailing underscore). I am not aware of | |
385 | anyone who is working on getting gdb to use the syntax of any other | |
386 | language. Pascal programs which use sets, subranges, file variables, | |
387 | or nested functions will not currently work. | |
bd5635a1 | 388 | |
bd5635a1 | 389 | |
c45c19f8 | 390 | Kernel debugging |
bd5635a1 | 391 | |
c45c19f8 JG |
392 | I have't done this myself so I can't really offer any advice. |
393 | Remote debugging over serial lines works fine, but the kernel debugging | |
394 | code in here has not been tested in years. Van Jacobson claims to have | |
ee7270cd | 395 | better kernel debugging. |
bd5635a1 | 396 | |
bd5635a1 | 397 | |
c45c19f8 | 398 | Remote debugging |
bd5635a1 | 399 | |
361cc81a JG |
400 | The files m68k-stub.c and i386-stub.c contain two examples of remote |
401 | stubs to be used with remote.c. They are designeded to run standalone | |
402 | on a 68k or 386 cpu and communicate properly with the remote.c stub | |
403 | over a serial line. | |
404 | ||
170d0c85 RP |
405 | The file rem-multi.shar contains a general stub that can probably |
406 | run on various different flavors of unix to allow debugging over a | |
361cc81a | 407 | serial line from one machine to another. |
bd5635a1 | 408 | |
fbda4193 JG |
409 | Some working remote interfaces for talking to existing ROM monitors |
410 | are: | |
411 | remote-eb.c AMD 29000 "EBMON" | |
412 | remote-nindy.c Intel 960 "Nindy" | |
413 | remote-adapt.c AMD 29000 "Adapt" | |
414 | remote-mm.c AMD 29000 "minimon" | |
170d0c85 RP |
415 | |
416 | Remote-vx.c and the vx-share subdirectory contain a remote interface for the | |
417 | VxWorks realtime kernel, which communicates over TCP using the Sun | |
418 | RPC library. This would be a useful starting point for other remote- | |
419 | via-ethernet back ends. | |
bd5635a1 | 420 | |
c45c19f8 JG |
421 | |
422 | Reporting Bugs | |
423 | ||
424 | The correct address for reporting bugs found in gdb is | |
bd5635a1 | 425 | "bug-gdb@prep.ai.mit.edu". Please email all bugs to that address. |
ee7270cd | 426 | Please include the GDB version number (e.g. gdb-4.4), and how |
fbda4193 JG |
427 | you configured it (e.g. "sun4" or "mach386 host, i586-intel-synopsys |
428 | target"). | |
429 | ||
430 | A known bug: | |
431 | ||
432 | * If you run with a watchpoint enabled, breakpoints will become | |
433 | erratic and might not stop the program. Disabling or deleting the | |
434 | watchpoint will fix the problem. | |
bd5635a1 | 435 | |
846058ed JG |
436 | GDB can produce warnings about symbols that it does not understand. By |
437 | default, these warnings are disabled. You can enable them by executing | |
438 | `set complaint 10' (which you can put in your ~/.gdbinit if you like). | |
439 | I recommend doing this if you are working on a compiler, assembler, | |
440 | linker, or gdb, since it will point out problems that you may be able | |
441 | to fix. Warnings produced during symbol reading indicate some mismatch | |
fbda4193 | 442 | between the object file and GDB's symbol reading code. In many cases, |
846058ed | 443 | it's a mismatch between the specs for the object file format, and what |
fbda4193 | 444 | the compiler actually outputs or the debugger actually understands. |
c45c19f8 | 445 | |
fbda4193 JG |
446 | If you port gdb to a new machine, please send the required changes to |
447 | bug-gdb@prep.ai.mit.edu. There's lots of information about doing your | |
ee7270cd | 448 | own port in the file gdb-4.4/gdb/doc/gdbint.texinfo, which you can |
fbda4193 JG |
449 | print out, or read with `info' (see the Makefile.in there). If your |
450 | changes are more than a few lines, obtain and send in a copyright | |
451 | assignment from gnu@prep.ai.mit.edu, as described in the section | |
452 | `Writing Code for GDB'. | |
c45c19f8 JG |
453 | |
454 | ||
455 | X Windows versus GDB | |
bd5635a1 | 456 | |
361cc81a | 457 | xgdb is obsolete. We are not doing any development or support of it. |
bd5635a1 | 458 | |
c45c19f8 JG |
459 | There is an "xxgdb", which shows more promise, which was posted to |
460 | comp.sources.x. | |
bd5635a1 RP |
461 | |
462 | For those intersted in auto display of source and the availability of | |
463 | an editor while debugging I suggest trying gdb-mode in gnu-emacs | |
464 | (Try typing M-x gdb RETURN). Comments on this mode are welcome. | |
465 | ||
c45c19f8 | 466 | |
c45c19f8 | 467 | Writing Code for GDB |
bd5635a1 RP |
468 | |
469 | We appreciate having users contribute code that is of general use, but | |
470 | for it to be included in future GDB releases it must be cleanly | |
471 | written. We do not want to include changes that will needlessly make | |
472 | future maintainance difficult. It is not much harder to do things | |
473 | right, and in the long term it is worth it to the GNU project, and | |
474 | probably to you individually as well. | |
475 | ||
bd5635a1 RP |
476 | If you make substantial changes, you'll have to file a copyright |
477 | assignment with the Free Software Foundation before we can produce a | |
478 | release that includes your changes. Send mail requesting the copyright | |
479 | assignment to gnu@prep.ai.mit.edu. Do this early, like before the | |
480 | changes actually work, or even before you start them, because a manager | |
481 | or lawyer on your end will probably make this a slow process. | |
482 | ||
fbda4193 JG |
483 | Please code according to the GNU coding standards. If you do not have |
484 | a copy, you can request one by sending mail to gnu@prep.ai.mit.edu. | |
485 | ||
bd5635a1 RP |
486 | Please try to avoid making machine-specific changes to |
487 | machine-independent files. If this is unavoidable, put a hook in the | |
488 | machine-independent file which calls a (possibly) machine-dependent | |
489 | macro (for example, the IGNORE_SYMBOL macro can be used for any | |
490 | symbols which need to be ignored on a specific machine. Calling | |
491 | IGNORE_SYMBOL in dbxread.c is a lot cleaner than a maze of #if | |
492 | defined's). The machine-independent code should do whatever "most" | |
493 | machines want if the macro is not defined in param.h. Using #if | |
361cc81a | 494 | defined can sometimes be OK (e.g. SET_STACK_LIMIT_HUGE) but should be |
bd5635a1 RP |
495 | conditionalized on a specific feature of an operating system (set in |
496 | tm.h or xm.h) rather than something like #if defined(vax) or #if | |
497 | defined(SYSV). If you use an #ifdef on some symbol that is defined | |
498 | in a header file (e.g. #ifdef TIOCSETP), *please* make sure that you | |
499 | have #include'd the relevant header file in that module! | |
500 | ||
501 | It is better to replace entire routines which may be system-specific, | |
502 | rather than put in a whole bunch of hooks which are probably not going | |
503 | to be helpful for any purpose other than your changes. For example, | |
504 | if you want to modify dbxread.c to deal with DBX debugging symbols | |
505 | which are in COFF files rather than BSD a.out files, do something | |
506 | along the lines of a macro GET_NEXT_SYMBOL, which could have | |
507 | different definitions for COFF and a.out, rather than trying to put | |
508 | the necessary changes throughout all the code in dbxread.c that | |
509 | currently assumes BSD format. | |
510 | ||
fbda4193 JG |
511 | When generalizing GDB along a particular interface, please use an |
512 | attribute-struct rather than inserting tests or switch statements | |
513 | everywhere. For example, GDB has been generalized to handle multiple | |
514 | kinds of remote interfaces -- not by #ifdef's everywhere, but by | |
515 | defining the "target_ops" structure and having a current target (as | |
516 | well as a stack of targets below it, for memory references). Whenever | |
517 | something needs to be done that depends on which remote interface we | |
518 | are using, a flag in the current target_ops structure is tested (e.g. | |
519 | `target_has_stack'), or a function is called through a pointer in the | |
520 | current target_ops structure. In this way, when a new remote interface | |
521 | is added, only one module needs to be touched -- the one that actually | |
522 | implements the new remote interface. Other examples of | |
523 | attribute-structs are BFD access to multiple kinds of object file | |
524 | formats, or GDB's access to multiple source languages. | |
525 | ||
bd5635a1 RP |
526 | Please avoid duplicating code. For example, in GDB 3.x all the stuff |
527 | in infptrace.c was duplicated in *-dep.c, and so changing something | |
c45c19f8 | 528 | was very painful. In GDB 4.x, these have all been consolidated |
bd5635a1 RP |
529 | into infptrace.c. infptrace.c can deal with variations between |
530 | systems the same way any system-independent file would (hooks, #if | |
531 | defined, etc.), and machines which are radically different don't need | |
532 | to use infptrace.c at all. The same was true of core_file_command | |
533 | and exec_file_command. | |
534 | ||
bd5635a1 | 535 | |
c45c19f8 | 536 | Debugging gdb with itself |
bd5635a1 | 537 | |
c45c19f8 JG |
538 | If gdb is limping on your machine, this is the preferred way to get it |
539 | fully functional. Be warned that in some ancient Unix systems, like | |
540 | Ultrix 4.0, a program can't be running in one process while it is being | |
541 | debugged in another. Rather than doing "./gdb ./gdb", which works on | |
542 | Suns and such, you can copy gdb to gdb2 and then do "./gdb ./gdb2". | |
bd5635a1 | 543 | |
fbda4193 JG |
544 | When you run gdb in the gdb source directory, it will read a ".gdbinit" |
545 | file that sets up some simple things to make debugging gdb easier. The | |
546 | "info" command, when executed without a subcommand in a gdb being | |
547 | debugged by gdb, will pop you back up to the top level gdb. See | |
548 | .gdbinit for details. | |
c45c19f8 | 549 | |
846058ed JG |
550 | I strongly recommend printing out the reference card and using it. |
551 | Send reference-card suggestions to bug-gdb@prep.ai.mit.edu, just like bugs. | |
552 | ||
c45c19f8 JG |
553 | If you use emacs, you will probably want to do a "make TAGS" after you |
554 | configure your distribution; this will put the machine dependent | |
555 | routines for your local machine where they will be accessed first by a | |
556 | M-period. | |
557 | ||
fbda4193 JG |
558 | Also, make sure that you've either compiled gdb with your local cc, or |
559 | have run `fixincludes' if you are compiling with gcc. | |
bd5635a1 RP |
560 | \f |
561 | (this is for editing this file with GNU emacs) | |
562 | Local Variables: | |
563 | mode: text | |
564 | End: |