diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 4 | ||||
| -rw-r--r-- | doc/gawk.info | 441 | ||||
| -rw-r--r-- | doc/gawk.texi | 46 | ||||
| -rw-r--r-- | doc/gawktexi.in | 46 |
4 files changed, 316 insertions, 221 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 3320cff8..6af2d876 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2018-12-18 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in: Added more indexing to the debugger chapter. + 2018-11-27 Arnold D. Robbins <arnold@skeeve.com> * gawktexi.in (Other Versions): Document GoAWK, an awk interpreter diff --git a/doc/gawk.info b/doc/gawk.info index 889a2a86..9fba2e1f 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -21584,12 +21584,12 @@ File: gawk.info, Node: Debugger, Next: Arbitrary Precision Arithmetic, Prev: It would be nice if computer programs worked perfectly the first time they were run, but in real life, this rarely happens for programs of any complexity. Thus, most programming languages have facilities available -for "debugging" programs, and now 'awk' is no exception. +for "debugging" programs, and 'awk' is no exception. The 'gawk' debugger is purposely modeled after the GNU Debugger (GDB) (https://www.gnu.org/software/gdb/) command-line debugger. If you are -familiar with GDB, learning how to use 'gawk' for debugging your program -is easy. +familiar with GDB, learning how to use 'gawk' for debugging your +programs is easy. * Menu: @@ -21726,7 +21726,12 @@ instructions. is easy to lose sight of everything that is going on "inside" each line of 'awk' code. The debugger provides the opportunity to look at the individual primitive instructions carried out by the higher-level 'awk' -commands. +commands.(1) + + ---------- Footnotes ---------- + + (1) The "primitive instructions" are defined by 'gawk' itself; the +debugger does not work at the level of machine instructions. File: gawk.info, Node: Sample Debugging Session, Next: List of Debugger Commands, Prev: Debugging, Up: Debugger @@ -21736,7 +21741,7 @@ File: gawk.info, Node: Sample Debugging Session, Next: List of Debugger Comman In order to illustrate the use of 'gawk' as a debugger, let's look at a sample debugging session. We will use the 'awk' implementation of the -POSIX 'uniq' command described earlier (*note Uniq Program::) as our +POSIX 'uniq' command presented earlier (*note Uniq Program::) as our example. * Menu: @@ -21783,9 +21788,8 @@ File: gawk.info, Node: Finding The Bug, Prev: Debugger Invocation, Up: Sample ---------------------- Let's say that we are having a problem using (a faulty version of) -'uniq.awk' in the "field-skipping" mode, and it doesn't seem to be -catching lines which should be identical when skipping the first field, -such as: +'uniq.awk' in "field-skipping" mode, and it doesn't seem to be catching +lines which should be identical when skipping the first field, such as: awk is a wonderful program! gawk is a wonderful program! @@ -33625,7 +33629,7 @@ Index (line 6) * break debugger command: Breakpoint Control. (line 11) * break statement: Break Statement. (line 6) -* breakpoint: Debugging Terms. (line 33) +* breakpoint (debugger): Debugging Terms. (line 33) * breakpoint at location, how to delete: Breakpoint Control. (line 36) * breakpoint commands: Debugger Execution Control. (line 10) @@ -33684,6 +33688,7 @@ Index (line 44) * call by value: Pass By Value/Reference. (line 15) +* call stack (debugger): Debugging Terms. (line 10) * call stack, display in debugger: Execution Stack. (line 13) * caret (^), in bracket expressions: Bracket Expressions. (line 25) * caret (^), regexp operator: Regexp Operators. (line 22) @@ -33942,6 +33947,7 @@ Index * dcngettext() function (gawk), portability and: I18N Portability. (line 33) * deadlocks: Two-way I/O. (line 53) +* debugger capabilities: Debugging Concepts. (line 16) * debugger commands, b (break): Breakpoint Control. (line 11) * debugger commands, backtrace: Execution Stack. (line 13) * debugger commands, break: Breakpoint Control. (line 11) @@ -34039,15 +34045,41 @@ Index * debugger commands, watch: Viewing And Changing Data. (line 66) * debugger commands, where (backtrace): Execution Stack. (line 13) +* debugger concepts: Debugging Terms. (line 6) * debugger default list amount: Debugger Info. (line 69) * debugger history file: Debugger Info. (line 81) * debugger history size: Debugger Info. (line 65) * debugger options: Debugger Info. (line 57) * debugger prompt: Debugger Info. (line 78) +* debugger, b command: Finding The Bug. (line 32) +* debugger, backtrace command: Finding The Bug. (line 52) +* debugger, break command: Finding The Bug. (line 32) +* debugger, breakpoint command: Finding The Bug. (line 32) +* debugger, bt command: Finding The Bug. (line 52) +* debugger, command completion: Readline Support. (line 6) +* debugger, history expansion: Readline Support. (line 6) * debugger, how to start: Debugger Invocation. (line 6) +* debugger, instruction tracing: Debugger Info. (line 90) +* debugger, limitations: Limitations. (line 6) +* debugger, n command: Finding The Bug. (line 105) +* debugger, next command: Finding The Bug. (line 105) +* debugger, p command: Finding The Bug. (line 68) +* debugger, print command: Finding The Bug. (line 68) +* debugger, printing all array elements: Finding The Bug. (line 154) +* debugger, printing single array elements: Finding The Bug. (line 140) +* debugger, prompt: Debugger Invocation. (line 23) * debugger, read commands from a file: Debugger Info. (line 97) +* debugger, repeating commands: List of Debugger Commands. + (line 21) +* debugger, run command: Finding The Bug. (line 39) +* debugger, running the program: Finding The Bug. (line 39) +* debugger, save commands to a file: Debugger Info. (line 92) +* debugger, setting a breakpoint: Finding The Bug. (line 32) +* debugger, show stack frames: Finding The Bug. (line 52) * debugging awk programs: Debugger. (line 6) * debugging gawk, bug reports: Bugs. (line 9) +* debugging, example session: Sample Debugging Session. + (line 6) * decimal point character, locale specific: Options. (line 282) * decrement operators: Increment Ops. (line 35) * default keyword: Switch Statement. (line 6) @@ -34254,6 +34286,8 @@ Index * evaluation order, concatenation: Concatenation. (line 41) * evaluation order, functions: Calling Built-in. (line 30) * examining fields: Fields. (line 6) +* example debugging session: Sample Debugging Session. + (line 6) * exclamation point (!), ! operator: Boolean Ops. (line 69) * exclamation point (!), ! operator <1>: Precedence. (line 51) * exclamation point (!), ! operator <2>: Egrep Program. (line 174) @@ -35817,7 +35851,7 @@ Index * square brackets ([]), regexp operator: Regexp Operators. (line 56) * square root: Numeric Functions. (line 78) * srand: Numeric Functions. (line 82) -* stack frame: Debugging Terms. (line 10) +* stack frame (debugger): Debugging Terms. (line 10) * Stallman, Richard: Manual History. (line 6) * Stallman, Richard <1>: Acknowledgments. (line 18) * Stallman, Richard <2>: Contributors. (line 24) @@ -36100,7 +36134,7 @@ Index * warnings, issuing: Options. (line 198) * watch debugger command: Viewing And Changing Data. (line 66) -* watchpoint: Debugging Terms. (line 42) +* watchpoint (debugger): Debugging Terms. (line 42) * wc utility: Wc Program. (line 6) * wc.awk program: Wc Program. (line 46) * Weinberger, Peter: History. (line 17) @@ -36527,197 +36561,198 @@ Ref: I18N Example-Footnote-1873616 Node: Gawk I18N873689 Node: I18N Summary874334 Node: Debugger875675 -Node: Debugging876698 -Node: Debugging Concepts877139 -Node: Debugging Terms878948 -Node: Awk Debugging881523 -Node: Sample Debugging Session882429 -Node: Debugger Invocation882963 -Node: Finding The Bug884349 -Node: List of Debugger Commands890827 -Node: Breakpoint Control892160 -Node: Debugger Execution Control895854 -Node: Viewing And Changing Data899216 -Node: Execution Stack902590 -Node: Debugger Info904227 -Node: Miscellaneous Debugger Commands908298 -Node: Readline Support913360 -Node: Limitations914256 -Node: Debugging Summary916365 -Node: Arbitrary Precision Arithmetic917644 -Node: Computer Arithmetic919129 -Ref: table-numeric-ranges922895 -Ref: table-floating-point-ranges923388 -Ref: Computer Arithmetic-Footnote-1924046 -Node: Math Definitions924103 -Ref: table-ieee-formats927419 -Ref: Math Definitions-Footnote-1928022 -Node: MPFR features928127 -Node: FP Math Caution929845 -Ref: FP Math Caution-Footnote-1930917 -Node: Inexactness of computations931286 -Node: Inexact representation932246 -Node: Comparing FP Values933606 -Node: Errors accumulate934847 -Node: Getting Accuracy936280 -Node: Try To Round938990 -Node: Setting precision939889 -Ref: table-predefined-precision-strings940586 -Node: Setting the rounding mode942416 -Ref: table-gawk-rounding-modes942790 -Ref: Setting the rounding mode-Footnote-1946721 -Node: Arbitrary Precision Integers946900 -Ref: Arbitrary Precision Integers-Footnote-1950075 -Node: Checking for MPFR950224 -Node: POSIX Floating Point Problems951698 -Ref: POSIX Floating Point Problems-Footnote-1955983 -Node: Floating point summary956021 -Node: Dynamic Extensions958211 -Node: Extension Intro959764 -Node: Plugin License961030 -Node: Extension Mechanism Outline961827 -Ref: figure-load-extension962266 -Ref: figure-register-new-function963831 -Ref: figure-call-new-function964923 -Node: Extension API Description966985 -Node: Extension API Functions Introduction968627 -Node: General Data Types974167 -Ref: General Data Types-Footnote-1982528 -Node: Memory Allocation Functions982827 -Ref: Memory Allocation Functions-Footnote-1987037 -Node: Constructor Functions987136 -Node: Registration Functions990722 -Node: Extension Functions991407 -Node: Exit Callback Functions996622 -Node: Extension Version String997872 -Node: Input Parsers998535 -Node: Output Wrappers1011256 -Node: Two-way processors1015768 -Node: Printing Messages1018033 -Ref: Printing Messages-Footnote-11019204 -Node: Updating ERRNO1019357 -Node: Requesting Values1020096 -Ref: table-value-types-returned1020833 -Node: Accessing Parameters1021769 -Node: Symbol Table Access1023004 -Node: Symbol table by name1023516 -Node: Symbol table by cookie1025305 -Ref: Symbol table by cookie-Footnote-11029490 -Node: Cached values1029554 -Ref: Cached values-Footnote-11033090 -Node: Array Manipulation1033243 -Ref: Array Manipulation-Footnote-11034334 -Node: Array Data Types1034371 -Ref: Array Data Types-Footnote-11037029 -Node: Array Functions1037121 -Node: Flattening Arrays1041619 -Node: Creating Arrays1048595 -Node: Redirection API1053362 -Node: Extension API Variables1056195 -Node: Extension Versioning1056906 -Ref: gawk-api-version1057335 -Node: Extension GMP/MPFR Versioning1059066 -Node: Extension API Informational Variables1060694 -Node: Extension API Boilerplate1061767 -Node: Changes from API V11065741 -Node: Finding Extensions1067313 -Node: Extension Example1067872 -Node: Internal File Description1068670 -Node: Internal File Ops1072750 -Ref: Internal File Ops-Footnote-11084100 -Node: Using Internal File Ops1084240 -Ref: Using Internal File Ops-Footnote-11086623 -Node: Extension Samples1086897 -Node: Extension Sample File Functions1088426 -Node: Extension Sample Fnmatch1096075 -Node: Extension Sample Fork1097562 -Node: Extension Sample Inplace1098780 -Node: Extension Sample Ord1101997 -Node: Extension Sample Readdir1102833 -Ref: table-readdir-file-types1103722 -Node: Extension Sample Revout1104527 -Node: Extension Sample Rev2way1105116 -Node: Extension Sample Read write array1105856 -Node: Extension Sample Readfile1107798 -Node: Extension Sample Time1108893 -Node: Extension Sample API Tests1110241 -Node: gawkextlib1110733 -Node: Extension summary1113651 -Node: Extension Exercises1117353 -Node: Language History1118851 -Node: V7/SVR3.11120507 -Node: SVR41122659 -Node: POSIX1124093 -Node: BTL1125473 -Node: POSIX/GNU1126202 -Node: Feature History1131980 -Node: Common Extensions1147839 -Node: Ranges and Locales1149122 -Ref: Ranges and Locales-Footnote-11153738 -Ref: Ranges and Locales-Footnote-21153765 -Ref: Ranges and Locales-Footnote-31154000 -Node: Contributors1154221 -Node: History summary1160166 -Node: Installation1161546 -Node: Gawk Distribution1162490 -Node: Getting1162974 -Node: Extracting1163937 -Node: Distribution contents1165575 -Node: Unix Installation1172055 -Node: Quick Installation1172737 -Node: Shell Startup Files1175151 -Node: Additional Configuration Options1176240 -Node: Configuration Philosophy1178533 -Node: Non-Unix Installation1180902 -Node: PC Installation1181362 -Node: PC Binary Installation1182200 -Node: PC Compiling1182635 -Node: PC Using1183752 -Node: Cygwin1186967 -Node: MSYS1188066 -Node: VMS Installation1188567 -Node: VMS Compilation1189358 -Ref: VMS Compilation-Footnote-11190587 -Node: VMS Dynamic Extensions1190645 -Node: VMS Installation Details1192330 -Node: VMS Running1194583 -Node: VMS GNV1198862 -Node: VMS Old Gawk1199597 -Node: Bugs1200068 -Node: Bug address1200731 -Node: Usenet1203713 -Node: Maintainers1204717 -Node: Other Versions1205978 -Node: Installation summary1212892 -Node: Notes1214094 -Node: Compatibility Mode1214888 -Node: Additions1215670 -Node: Accessing The Source1216595 -Node: Adding Code1218032 -Node: New Ports1224251 -Node: Derived Files1228739 -Ref: Derived Files-Footnote-11234385 -Ref: Derived Files-Footnote-21234420 -Ref: Derived Files-Footnote-31235018 -Node: Future Extensions1235132 -Node: Implementation Limitations1235790 -Node: Extension Design1236973 -Node: Old Extension Problems1238117 -Ref: Old Extension Problems-Footnote-11239635 -Node: Extension New Mechanism Goals1239692 -Ref: Extension New Mechanism Goals-Footnote-11243056 -Node: Extension Other Design Decisions1243245 -Node: Extension Future Growth1245358 -Node: Notes summary1246194 -Node: Basic Concepts1247369 -Node: Basic High Level1248050 -Ref: figure-general-flow1248332 -Ref: figure-process-flow1249017 -Ref: Basic High Level-Footnote-11252318 -Node: Basic Data Typing1252503 -Node: Glossary1255831 -Node: Copying1287669 -Node: GNU Free Documentation License1325212 -Node: Index1350332 +Node: Debugging876695 +Node: Debugging Concepts877136 +Node: Debugging Terms878945 +Node: Awk Debugging881520 +Ref: Awk Debugging-Footnote-1882465 +Node: Sample Debugging Session882597 +Node: Debugger Invocation883131 +Node: Finding The Bug884517 +Node: List of Debugger Commands890991 +Node: Breakpoint Control892324 +Node: Debugger Execution Control896018 +Node: Viewing And Changing Data899380 +Node: Execution Stack902754 +Node: Debugger Info904391 +Node: Miscellaneous Debugger Commands908462 +Node: Readline Support913524 +Node: Limitations914420 +Node: Debugging Summary916529 +Node: Arbitrary Precision Arithmetic917808 +Node: Computer Arithmetic919293 +Ref: table-numeric-ranges923059 +Ref: table-floating-point-ranges923552 +Ref: Computer Arithmetic-Footnote-1924210 +Node: Math Definitions924267 +Ref: table-ieee-formats927583 +Ref: Math Definitions-Footnote-1928186 +Node: MPFR features928291 +Node: FP Math Caution930009 +Ref: FP Math Caution-Footnote-1931081 +Node: Inexactness of computations931450 +Node: Inexact representation932410 +Node: Comparing FP Values933770 +Node: Errors accumulate935011 +Node: Getting Accuracy936444 +Node: Try To Round939154 +Node: Setting precision940053 +Ref: table-predefined-precision-strings940750 +Node: Setting the rounding mode942580 +Ref: table-gawk-rounding-modes942954 +Ref: Setting the rounding mode-Footnote-1946885 +Node: Arbitrary Precision Integers947064 +Ref: Arbitrary Precision Integers-Footnote-1950239 +Node: Checking for MPFR950388 +Node: POSIX Floating Point Problems951862 +Ref: POSIX Floating Point Problems-Footnote-1956147 +Node: Floating point summary956185 +Node: Dynamic Extensions958375 +Node: Extension Intro959928 +Node: Plugin License961194 +Node: Extension Mechanism Outline961991 +Ref: figure-load-extension962430 +Ref: figure-register-new-function963995 +Ref: figure-call-new-function965087 +Node: Extension API Description967149 +Node: Extension API Functions Introduction968791 +Node: General Data Types974331 +Ref: General Data Types-Footnote-1982692 +Node: Memory Allocation Functions982991 +Ref: Memory Allocation Functions-Footnote-1987201 +Node: Constructor Functions987300 +Node: Registration Functions990886 +Node: Extension Functions991571 +Node: Exit Callback Functions996786 +Node: Extension Version String998036 +Node: Input Parsers998699 +Node: Output Wrappers1011420 +Node: Two-way processors1015932 +Node: Printing Messages1018197 +Ref: Printing Messages-Footnote-11019368 +Node: Updating ERRNO1019521 +Node: Requesting Values1020260 +Ref: table-value-types-returned1020997 +Node: Accessing Parameters1021933 +Node: Symbol Table Access1023168 +Node: Symbol table by name1023680 +Node: Symbol table by cookie1025469 +Ref: Symbol table by cookie-Footnote-11029654 +Node: Cached values1029718 +Ref: Cached values-Footnote-11033254 +Node: Array Manipulation1033407 +Ref: Array Manipulation-Footnote-11034498 +Node: Array Data Types1034535 +Ref: Array Data Types-Footnote-11037193 +Node: Array Functions1037285 +Node: Flattening Arrays1041783 +Node: Creating Arrays1048759 +Node: Redirection API1053526 +Node: Extension API Variables1056359 +Node: Extension Versioning1057070 +Ref: gawk-api-version1057499 +Node: Extension GMP/MPFR Versioning1059230 +Node: Extension API Informational Variables1060858 +Node: Extension API Boilerplate1061931 +Node: Changes from API V11065905 +Node: Finding Extensions1067477 +Node: Extension Example1068036 +Node: Internal File Description1068834 +Node: Internal File Ops1072914 +Ref: Internal File Ops-Footnote-11084264 +Node: Using Internal File Ops1084404 +Ref: Using Internal File Ops-Footnote-11086787 +Node: Extension Samples1087061 +Node: Extension Sample File Functions1088590 +Node: Extension Sample Fnmatch1096239 +Node: Extension Sample Fork1097726 +Node: Extension Sample Inplace1098944 +Node: Extension Sample Ord1102161 +Node: Extension Sample Readdir1102997 +Ref: table-readdir-file-types1103886 +Node: Extension Sample Revout1104691 +Node: Extension Sample Rev2way1105280 +Node: Extension Sample Read write array1106020 +Node: Extension Sample Readfile1107962 +Node: Extension Sample Time1109057 +Node: Extension Sample API Tests1110405 +Node: gawkextlib1110897 +Node: Extension summary1113815 +Node: Extension Exercises1117517 +Node: Language History1119015 +Node: V7/SVR3.11120671 +Node: SVR41122823 +Node: POSIX1124257 +Node: BTL1125637 +Node: POSIX/GNU1126366 +Node: Feature History1132144 +Node: Common Extensions1148003 +Node: Ranges and Locales1149286 +Ref: Ranges and Locales-Footnote-11153902 +Ref: Ranges and Locales-Footnote-21153929 +Ref: Ranges and Locales-Footnote-31154164 +Node: Contributors1154385 +Node: History summary1160330 +Node: Installation1161710 +Node: Gawk Distribution1162654 +Node: Getting1163138 +Node: Extracting1164101 +Node: Distribution contents1165739 +Node: Unix Installation1172219 +Node: Quick Installation1172901 +Node: Shell Startup Files1175315 +Node: Additional Configuration Options1176404 +Node: Configuration Philosophy1178697 +Node: Non-Unix Installation1181066 +Node: PC Installation1181526 +Node: PC Binary Installation1182364 +Node: PC Compiling1182799 +Node: PC Using1183916 +Node: Cygwin1187131 +Node: MSYS1188230 +Node: VMS Installation1188731 +Node: VMS Compilation1189522 +Ref: VMS Compilation-Footnote-11190751 +Node: VMS Dynamic Extensions1190809 +Node: VMS Installation Details1192494 +Node: VMS Running1194747 +Node: VMS GNV1199026 +Node: VMS Old Gawk1199761 +Node: Bugs1200232 +Node: Bug address1200895 +Node: Usenet1203877 +Node: Maintainers1204881 +Node: Other Versions1206142 +Node: Installation summary1213056 +Node: Notes1214258 +Node: Compatibility Mode1215052 +Node: Additions1215834 +Node: Accessing The Source1216759 +Node: Adding Code1218196 +Node: New Ports1224415 +Node: Derived Files1228903 +Ref: Derived Files-Footnote-11234549 +Ref: Derived Files-Footnote-21234584 +Ref: Derived Files-Footnote-31235182 +Node: Future Extensions1235296 +Node: Implementation Limitations1235954 +Node: Extension Design1237137 +Node: Old Extension Problems1238281 +Ref: Old Extension Problems-Footnote-11239799 +Node: Extension New Mechanism Goals1239856 +Ref: Extension New Mechanism Goals-Footnote-11243220 +Node: Extension Other Design Decisions1243409 +Node: Extension Future Growth1245522 +Node: Notes summary1246358 +Node: Basic Concepts1247533 +Node: Basic High Level1248214 +Ref: figure-general-flow1248496 +Ref: figure-process-flow1249181 +Ref: Basic High Level-Footnote-11252482 +Node: Basic Data Typing1252667 +Node: Glossary1255995 +Node: Copying1287833 +Node: GNU Free Documentation License1325376 +Node: Index1350496 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 445ef9c1..4928769d 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -30172,17 +30172,16 @@ a number of translations for its messages. @cindex debugging @command{awk} programs @c The original text for this chapter was contributed by Efraim Yawitz. -@c FIXME: Add more indexing. It would be nice if computer programs worked perfectly the first time they were run, but in real life, this rarely happens for programs of any complexity. Thus, most programming languages have facilities available -for ``debugging'' programs, and now @command{awk} is no exception. +for ``debugging'' programs, and @command{awk} is no exception. The @command{gawk} debugger is purposely modeled after @uref{https://www.gnu.org/software/gdb/, the GNU Debugger (GDB)} command-line debugger. If you are familiar with GDB, learning -how to use @command{gawk} for debugging your program is easy. +how to use @command{gawk} for debugging your programs is easy. @menu * Debugging:: Introduction to @command{gawk} debugger. @@ -30218,6 +30217,7 @@ In that case, what can you expect from such a tool? The answer to that depends on the language being debugged, but in general, you can expect at least the following: +@cindex debugger capabilities @itemize @value{BULLET} @item The ability to watch a program execute its instructions one by one, @@ -30250,13 +30250,15 @@ functional program that you or someone else wrote). @node Debugging Terms @subsection Debugging Concepts +@cindex debugger concepts Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. The following list defines terms used throughout the rest of this @value{CHAPTER}: @table @dfn -@cindex stack frame +@cindex call stack (debugger) +@cindex stack frame (debugger) @item Stack frame Programs generally call functions during the course of their execution. One function can call another, or a function can call itself (recursion). @@ -30278,7 +30280,7 @@ invoked. Commands that print the call stack print information about each stack frame (as detailed later on). @item Breakpoint -@cindex breakpoint +@cindex breakpoint (debugger) During debugging, you often wish to let the program run until it reaches a certain point, and then continue execution from there one statement (or instruction) at a time. The way to do this is to set @@ -30288,7 +30290,7 @@ take over control of the program's execution. You can add and remove as many breakpoints as you like. @item Watchpoint -@cindex watchpoint +@cindex watchpoint (debugger) A watchpoint is similar to a breakpoint. The difference is that breakpoints are oriented around the code: stop when a certain point in the code is reached. A watchpoint, however, specifies that program execution @@ -30316,15 +30318,19 @@ In addition, because @command{awk} is by design a very concise language, it is easy to lose sight of everything that is going on ``inside'' each line of @command{awk} code. The debugger provides the opportunity to look at the individual primitive instructions carried out -by the higher-level @command{awk} commands. +by the higher-level @command{awk} commands.@footnote{The ``primitive +instructions'' are defined by @command{gawk} itself; the debugger +does not work at the level of machine instructions.} @node Sample Debugging Session @section Sample @command{gawk} Debugging Session @cindex sample debugging session +@cindex example debugging session +@cindex debugging, example session In order to illustrate the use of @command{gawk} as a debugger, let's look at a sample debugging session. We will use the @command{awk} implementation of the -POSIX @command{uniq} command described earlier (@pxref{Uniq Program}) +POSIX @command{uniq} command presented earlier (@pxref{Uniq Program}) as our example. @menu @@ -30358,6 +30364,7 @@ in the command line to the debugger rather than as part of the @code{run} command at the debugger prompt.) The @option{-1} is an option to @file{uniq.awk}. +@cindex debugger, prompt Instead of immediately running the program on @file{inputfile}, as @command{gawk} would ordinarily do, the debugger merely loads all the program source files, compiles them internally, and then gives @@ -30375,7 +30382,7 @@ code has been executed. @subsection Finding the Bug Let's say that we are having a problem using (a faulty version of) -@file{uniq.awk} in the ``field-skipping'' mode, and it doesn't seem to be +@file{uniq.awk} in ``field-skipping'' mode, and it doesn't seem to be catching lines which should be identical when skipping the first field, such as: @@ -30407,6 +30414,10 @@ a breakpoint in @file{uniq.awk} is at the beginning of the function @code{are_equal()}, which compares the current line with the previous one. To set the breakpoint, use the @code{b} (breakpoint) command: +@cindex debugger, setting a breakpoint +@cindex debugger, @code{breakpoint} command +@cindex debugger, @code{break} command +@cindex debugger, @code{b} command @example gawk> @kbd{b are_equal} @print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 63 @@ -30416,6 +30427,8 @@ The debugger tells us the file and line number where the breakpoint is. Now type @samp{r} or @samp{run} and the program runs until it hits the breakpoint for the first time: +@cindex debugger, running the program +@cindex debugger, @code{run} command @example gawk> @kbd{r} @print{} Starting program: @@ -30431,6 +30444,9 @@ let's see how we got to where we are. At the prompt, we type @samp{bt} (short for ``backtrace''), and the debugger responds with a listing of the current stack frames: +@cindex debugger, show stack frames +@cindex debugger, @code{bt} command +@cindex debugger, @code{backtrace} command @example gawk> @kbd{bt} @print{} #0 are_equal(n, m, clast, cline, alast, aline) @@ -30450,6 +30466,8 @@ of some variables. Let's say we type @samp{p n} @code{n}, a parameter to @code{are_equal()}. Actually, the debugger gives us: +@cindex debugger, @code{print} command +@cindex debugger, @code{p} command @example gawk> @kbd{p n} @print{} n = untyped variable @@ -30500,6 +30518,8 @@ be inside this function. To investigate further, we must begin ``stepping through'' the lines of @code{are_equal()}. We start by typing @samp{n} (for ``next''): +@cindex debugger, @code{n} command +@cindex debugger, @code{next} command @example @group gawk> @kbd{n} @@ -30545,6 +30565,7 @@ This information is useful enough (we now know that none of the words were accidentally left out), but what if we want to see inside the array? +@cindex debugger, printing single array elements The first choice would be to use subscripts: @example @@ -30564,6 +30585,7 @@ This would be kind of slow for a 100-member array, though, so @command{gawk} provides a shortcut (reminiscent of another language not to be mentioned): +@cindex debugger, printing all array elements @example gawk> @kbd{p @@alast} @print{} alast["1"] = "awk" @@ -30643,6 +30665,7 @@ Getting information Miscellaneous @end itemize +@cindex debugger, repeating commands Each of these are discussed in the following subsections. In the following descriptions, commands that may be abbreviated show the abbreviation on a second description line. @@ -31229,9 +31252,11 @@ Options are read back into the next session upon startup. @item @code{trace} [@code{on} | @code{off}] @cindex instruction tracing, in debugger +@cindex debugger, instruction tracing Turn instruction tracing on or off. The default is @code{off}. @end table +@cindex debugger, save commands to a file @item @code{save} @var{filename} Save the commands from the current session to the given @value{FN}, so that they can be replayed using the @command{source} command. @@ -31404,7 +31429,9 @@ fairly self-explanatory, and using @code{stepi} and @code{nexti} while @node Readline Support @section Readline Support @cindex command completion, in debugger +@cindex debugger, command completion @cindex history expansion, in debugger +@cindex debugger, history expansion If @command{gawk} is compiled with @uref{http://cnswww.cns.cwru.edu/php/chet/readline/readline.html, @@ -31443,6 +31470,7 @@ and @node Limitations @section Limitations +@cindex debugger, limitations We hope you find the @command{gawk} debugger useful and enjoyable to work with, but as with any program, especially in its early releases, it still has some limitations. A few that it's worth being aware of are: diff --git a/doc/gawktexi.in b/doc/gawktexi.in index cd989a54..f7540936 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -29185,17 +29185,16 @@ a number of translations for its messages. @cindex debugging @command{awk} programs @c The original text for this chapter was contributed by Efraim Yawitz. -@c FIXME: Add more indexing. It would be nice if computer programs worked perfectly the first time they were run, but in real life, this rarely happens for programs of any complexity. Thus, most programming languages have facilities available -for ``debugging'' programs, and now @command{awk} is no exception. +for ``debugging'' programs, and @command{awk} is no exception. The @command{gawk} debugger is purposely modeled after @uref{https://www.gnu.org/software/gdb/, the GNU Debugger (GDB)} command-line debugger. If you are familiar with GDB, learning -how to use @command{gawk} for debugging your program is easy. +how to use @command{gawk} for debugging your programs is easy. @menu * Debugging:: Introduction to @command{gawk} debugger. @@ -29231,6 +29230,7 @@ In that case, what can you expect from such a tool? The answer to that depends on the language being debugged, but in general, you can expect at least the following: +@cindex debugger capabilities @itemize @value{BULLET} @item The ability to watch a program execute its instructions one by one, @@ -29263,13 +29263,15 @@ functional program that you or someone else wrote). @node Debugging Terms @subsection Debugging Concepts +@cindex debugger concepts Before diving in to the details, we need to introduce several important concepts that apply to just about all debuggers. The following list defines terms used throughout the rest of this @value{CHAPTER}: @table @dfn -@cindex stack frame +@cindex call stack (debugger) +@cindex stack frame (debugger) @item Stack frame Programs generally call functions during the course of their execution. One function can call another, or a function can call itself (recursion). @@ -29291,7 +29293,7 @@ invoked. Commands that print the call stack print information about each stack frame (as detailed later on). @item Breakpoint -@cindex breakpoint +@cindex breakpoint (debugger) During debugging, you often wish to let the program run until it reaches a certain point, and then continue execution from there one statement (or instruction) at a time. The way to do this is to set @@ -29301,7 +29303,7 @@ take over control of the program's execution. You can add and remove as many breakpoints as you like. @item Watchpoint -@cindex watchpoint +@cindex watchpoint (debugger) A watchpoint is similar to a breakpoint. The difference is that breakpoints are oriented around the code: stop when a certain point in the code is reached. A watchpoint, however, specifies that program execution @@ -29329,15 +29331,19 @@ In addition, because @command{awk} is by design a very concise language, it is easy to lose sight of everything that is going on ``inside'' each line of @command{awk} code. The debugger provides the opportunity to look at the individual primitive instructions carried out -by the higher-level @command{awk} commands. +by the higher-level @command{awk} commands.@footnote{The ``primitive +instructions'' are defined by @command{gawk} itself; the debugger +does not work at the level of machine instructions.} @node Sample Debugging Session @section Sample @command{gawk} Debugging Session @cindex sample debugging session +@cindex example debugging session +@cindex debugging, example session In order to illustrate the use of @command{gawk} as a debugger, let's look at a sample debugging session. We will use the @command{awk} implementation of the -POSIX @command{uniq} command described earlier (@pxref{Uniq Program}) +POSIX @command{uniq} command presented earlier (@pxref{Uniq Program}) as our example. @menu @@ -29371,6 +29377,7 @@ in the command line to the debugger rather than as part of the @code{run} command at the debugger prompt.) The @option{-1} is an option to @file{uniq.awk}. +@cindex debugger, prompt Instead of immediately running the program on @file{inputfile}, as @command{gawk} would ordinarily do, the debugger merely loads all the program source files, compiles them internally, and then gives @@ -29388,7 +29395,7 @@ code has been executed. @subsection Finding the Bug Let's say that we are having a problem using (a faulty version of) -@file{uniq.awk} in the ``field-skipping'' mode, and it doesn't seem to be +@file{uniq.awk} in ``field-skipping'' mode, and it doesn't seem to be catching lines which should be identical when skipping the first field, such as: @@ -29420,6 +29427,10 @@ a breakpoint in @file{uniq.awk} is at the beginning of the function @code{are_equal()}, which compares the current line with the previous one. To set the breakpoint, use the @code{b} (breakpoint) command: +@cindex debugger, setting a breakpoint +@cindex debugger, @code{breakpoint} command +@cindex debugger, @code{break} command +@cindex debugger, @code{b} command @example gawk> @kbd{b are_equal} @print{} Breakpoint 1 set at file `awklib/eg/prog/uniq.awk', line 63 @@ -29429,6 +29440,8 @@ The debugger tells us the file and line number where the breakpoint is. Now type @samp{r} or @samp{run} and the program runs until it hits the breakpoint for the first time: +@cindex debugger, running the program +@cindex debugger, @code{run} command @example gawk> @kbd{r} @print{} Starting program: @@ -29444,6 +29457,9 @@ let's see how we got to where we are. At the prompt, we type @samp{bt} (short for ``backtrace''), and the debugger responds with a listing of the current stack frames: +@cindex debugger, show stack frames +@cindex debugger, @code{bt} command +@cindex debugger, @code{backtrace} command @example gawk> @kbd{bt} @print{} #0 are_equal(n, m, clast, cline, alast, aline) @@ -29463,6 +29479,8 @@ of some variables. Let's say we type @samp{p n} @code{n}, a parameter to @code{are_equal()}. Actually, the debugger gives us: +@cindex debugger, @code{print} command +@cindex debugger, @code{p} command @example gawk> @kbd{p n} @print{} n = untyped variable @@ -29513,6 +29531,8 @@ be inside this function. To investigate further, we must begin ``stepping through'' the lines of @code{are_equal()}. We start by typing @samp{n} (for ``next''): +@cindex debugger, @code{n} command +@cindex debugger, @code{next} command @example @group gawk> @kbd{n} @@ -29558,6 +29578,7 @@ This information is useful enough (we now know that none of the words were accidentally left out), but what if we want to see inside the array? +@cindex debugger, printing single array elements The first choice would be to use subscripts: @example @@ -29577,6 +29598,7 @@ This would be kind of slow for a 100-member array, though, so @command{gawk} provides a shortcut (reminiscent of another language not to be mentioned): +@cindex debugger, printing all array elements @example gawk> @kbd{p @@alast} @print{} alast["1"] = "awk" @@ -29656,6 +29678,7 @@ Getting information Miscellaneous @end itemize +@cindex debugger, repeating commands Each of these are discussed in the following subsections. In the following descriptions, commands that may be abbreviated show the abbreviation on a second description line. @@ -30242,9 +30265,11 @@ Options are read back into the next session upon startup. @item @code{trace} [@code{on} | @code{off}] @cindex instruction tracing, in debugger +@cindex debugger, instruction tracing Turn instruction tracing on or off. The default is @code{off}. @end table +@cindex debugger, save commands to a file @item @code{save} @var{filename} Save the commands from the current session to the given @value{FN}, so that they can be replayed using the @command{source} command. @@ -30417,7 +30442,9 @@ fairly self-explanatory, and using @code{stepi} and @code{nexti} while @node Readline Support @section Readline Support @cindex command completion, in debugger +@cindex debugger, command completion @cindex history expansion, in debugger +@cindex debugger, history expansion If @command{gawk} is compiled with @uref{http://cnswww.cns.cwru.edu/php/chet/readline/readline.html, @@ -30456,6 +30483,7 @@ and @node Limitations @section Limitations +@cindex debugger, limitations We hope you find the @command{gawk} debugger useful and enjoyable to work with, but as with any program, especially in its early releases, it still has some limitations. A few that it's worth being aware of are: |