From ad382ce072c321ee5f5e46dabc2a0c3a9d4baef5 Mon Sep 17 00:00:00 2001 From: sgranjoux Date: Sun, 3 Feb 2008 14:54:20 +0000 Subject: [PATCH] * manuals/anjuta-manual/C/debugger.xml: Update debugger documentation git-svn-id: http://svn.gnome.org/svn/anjuta/trunk@3586 1dbfb86a-d425-0410-a06b-cb591aac69f6 --- ChangeLog | 5 + manuals/anjuta-manual/C/debugger.xml | 416 +++++++++++++++++++++++------------ 2 files changed, 281 insertions(+), 140 deletions(-) diff --git a/ChangeLog b/ChangeLog index d6ae8ca3..6d8b3bb7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,10 @@ 2008-02-03 Sébastien Granjoux + * manuals/anjuta-manual/C/debugger.xml: + Update debugger documentation + +2008-02-03 Sébastien Granjoux + * plugins/debug-manager/sharedlib.c, plugins/debug-manager/anjuta-debug-manager.glade, plugins/debug-manager/queue.c, diff --git a/manuals/anjuta-manual/C/debugger.xml b/manuals/anjuta-manual/C/debugger.xml index 5f72e721..8aa5f21f 100644 --- a/manuals/anjuta-manual/C/debugger.xml +++ b/manuals/anjuta-manual/C/debugger.xml @@ -29,12 +29,12 @@ views of information needed to study the execution of the program. - + The debugger has been heavily changed since anjuta 2.0.2. Some features have - been dropped but will be reenabled, a few have been added. + been dropped but will be re enabled, a few have been added. - + @@ -42,7 +42,7 @@ Start and stop - There are two ways to start the debugger: + The debugger is always started with a program loaded. There are two ways to do this: Running an executable Attaching to a process @@ -54,28 +54,38 @@ Choose the menu item DebugRun Target… - to display a dialog box where you can select - the executable that you want to debug, the command line parameters - and if you want a terminal or not. The popup menu of the target combo box - is already filled with all executables of the current project, so you can easily - select one of them. But it is not mandatory, you can select any other executable. - The debugger accepts libtool executable, I mean script wrapping the real - executable generated by libtool. When you have set everything you can click on - Execute - to start the debugger, load your program and stop at its beginning. + to display a dialog box where you can select: + + The program that you want to debug + The command line parameters + If you want a terminal or not (the Anjuta terminal plugin is used) + If you want to stop the program at the beginning or not + - + + The drop-down menu of the target drop-down combination box + is already filled with all executables of the current project. But you + can select another executable not part of the project. The debugger accepts libtool + executable, it means script,generated by libtool, wrapping the real executable. + Note that an URI is expected here, not a file path even if the debugger currently + supports only local files. + + + When you have set everything you can click on Execute + to start the debugger, load your program and stop at its beginning if requested. + + - In order to better user the debugger, it is recommended to debug program + In order to better user the debugger, it is strongly recommended to debug program with debugging information (-g for gcc) and no optimization (-O0 for gcc). - + Attaching to a Process - It is also possible to attach to a running process for debugging. Choose the menu item + It is also possible to attach to a running process and debugging it by choosing the menu item Debug Attach to Process …. A list of all the process running on the system will appear. @@ -88,12 +98,13 @@ - Select the process to attach to and click OK. + Select the process to attach to and click OK to start the debugger, + attach to the selected process and stop it. - It is currently not possible to load symbol information for the attached - process. + It is currently not possible to load symbol informations for the attached + process. They should be included in the process. @@ -101,11 +112,11 @@ Restarting an executable - After running a executable at least one time, you can + After running an executable at least one time, you can choose the menu item Debug Restart Target to restart your program. It is just a shortcut that will stop the debugger if it is currently running - and restart it with the last executable. + and restart it with the last executable without displaying the start dialog. @@ -120,6 +131,24 @@ + + Adding source directories + + Choose the menu item Debug + Add source paths… to display a dialog + box allowing you to add and remove source directories. + + + Most executables include full file paths, so defining the directories where are the source files + is not useful. But some executables include only file names without paths, in this case, + the source files will be searched in all these directories by the debugger. + The directories order can be important if several files have the same name, so + you can change it using the Up and Down buttons. + The directories list is send to the debugger when it is started. After changing it, + you need to restart the debugger to take it in account. + + + @@ -129,18 +158,25 @@ Execution of a program in the debugger can be finely controlled. The program can be executed in single steps, or allowed to continue until it encounters a breakpoint. - Executing like this is essential for tracking program behaviour. Like a video editing + Executing like this is essential for tracking program behavior. Like a video editing session, the program can be executed in slow motion - with the ability to go forward, pause, stop, and so on. + with the ability to go forward, pause, stop, and so on. You cannot go backward yet though. - The methods that can be used to execute a program in the debugger are described in - the next few sections. + The methods those can be used to execute a program in the debugger are described in + the next sections. These commands are available only when the program is already + started. Single stepping (step in) + Choose the menu item Debug + Step In + or click on the Step In icon in the + Debug toolbar to step into a program. + + Single stepping executes only one statement of the program (from the place where it has stopped) and then returns control. If the statement that is executed contains one or more functions, the debugger tries to step inside the functions (in the sequence in @@ -148,28 +184,28 @@ control is passed back, it is possible to study the various program parameters. - If the program need to been started to use single stepping. - - - Choose the menu item Debug - Step In - or click on the Step In icon in the - Debug toolbar to step into a program. + If the Disassembly window has the focus when this command is selected, + it executes only one assembler instruction. Single stepping (step over) + Choose the menu item Debug + Step Over + or click on the Step Over icon in the + Debug toolbar to step over statements in a program. + + Step over is similar to step in, except that it does not step inside any function in the statement being executed. The statement will be executed in one go. - Choose the menu item Debug - Step Over - or click on the Step Over icon in the - Debug toolbar to step over statements in a program. + If the Disassembly window has the focus when this command is selected, + it executes one assembler instruction but does not stop inside if this instruction is a call + to a subroutine. @@ -183,46 +219,47 @@ Single stepping (step out) + Choose the menu item Debug + Step Out + or click on the Step Out icon in the + Debug toolbar to step out in a program. + + Step out will execute the current function until it returns. The program will be stopped once it exits from the function. Step out is not really single stepping, because it does not only execute a single statement — it executes the whole function until that function returns to the calling function. - - Choose the menu item Debug - Step Out - or click on the Step Out icon in the - Debug toolbar to step out in a program. - Run/Continue - This option will continue the execution of the program until a breakpoint is - encountered, or the program exits. - - Choose the menu item Debug Run/Continue or click on the Run/Continue icon in the Debug toolbar to continue the execution of a program. + + This option continues the execution of the program until a breakpoint is + encountered, or the program exits. + Run To - This option will continue the execution of the program until the line where - cursor is is reached. - - Choose the menu item Debug Run to Cursor or click on the Run to Cursor icon in the Debug toolbar to run until the line at cursor is reached. - + + + This option continues the execution of the program until the line or the + address (if the Disassembly window has the focus) where + the cursor is is reached. + @@ -247,7 +284,7 @@ When debugging a program, it is useful to be able to stop the execution of the program at a particular point, so that the state of the program can be examined at that location. Breakpoints enable this to happen. Breakpoints can be set at different locations in a - source file, and then the program is allowed to run. When a breakpoint is encountered, + source file and then the program is allowed to run. When a breakpoint is encountered, the execution of the program is suspended, enabling expressions to be evaluated, variables to be inspected, the stack trace to be studied, and so on. @@ -269,71 +306,78 @@ - Location, refers to the location of the code in the source - file. Location can be specified in any of the following - formats: - - - - File_name:Line_number - Function_name - File:Function_name - - - - The first one is obvious — The location refers to the line number - Line_number in the source file File. - The second refers to the first line of the function - Function_name. The third is similar to the second, except that - this notation is used where there is more than one function with the name - Function_name in the program. It is possible to - differentiate between them by providing the File, so the - notation refers to the function Function_name in the - file File. - - - Two parameters can be associated with each breakpoint: - - Break condition - Pass count - - - - The Break condition is a valid C - expression which should evaluate to a Boolean value — that is, the - evaluation of the expression should result in either TRUE(1) or FALSE(0). - If the final evaluation value is not a Boolean value, then it will be - appropriately type casted to a Boolean. - - - Every time the breakpoint is encountered during the execution, the break - condition will be evaluated. The debugger will break the execution only if - the evaluation results in a TRUE value, otherwise it will continue the - execution as though there had been no breakpoint. - - - The default value of Break condition is always TRUE. - The debugger will break the execution at the breakpoint location. - - - The Pass count is an integer (unsigned) value which - tells the debugger to skip the breakpoint that number of times before it - is considered. Pass count has a higher priority than - the Break condition. Only when the - Pass count reaches zero will the debugger evaluate the - Break condition (if any condition is present). If there - is no condition, the debugger will break the execution once the - Pass count counts down to zero. - - - The default value of the Pass count is zero. The - breakpoint will be considered when it is first encountered. + The view has the following columns: + + + Location + + + This is the position of the breakpoint in the source file. When the breakpoint + is set by the debugger, you can get additional information like the function + where is the breakpoint. + + + + + Address + + + This field is filled with the + address of the breakpoint when it is set by the debugger. + + + + + Type + + + This displays always "breakpoint". It will be used + in a next version supporting different kind of breakpoints. + + + + + Condition + + + This is the breakpoint condition, it is empty if no condition is defined. + + + + + Pass count + + + When the debugger is not running, this column displays the pass count of the breakpoint, + zero if it is not defined. + + + When the debugger is running, if pass count is zero, this column displays + the number of time this breakpoint has been triggered. If pass count is not + zero, both numbers are displayed. The pass count is the second number. + + + + + State + + + This is the state of the breakpoint. You could have. + + Pending: breakpoint is not set in your program. + Permanent: breakpoint is set (id number in given inside the parenthesis). + Temporary: breakpoint is set but will be deleted if reached. + + + + + All breakpoints are kept across anjuta session even if they correspond to - a non existing place. The interface try to set them each time the program - is started or a new dynamic library is loaded. + a non existing place. In this case their state are set as pending.The interface + try to set them each time the program is started or a new dynamic library is loaded. @@ -356,18 +400,86 @@ - Enter the location at which to set the breakpoint. Optionally, enter - the Break condition and the Pass count - in the appropriate entry boxes. Click OK to set the - breakpoint. - - - A breakpoint may also be by selecting a line in the editor + You need to enter the location and optionally, the + break condition and the pass count then click OK to set the + breakpoint. + + + Location + + + Enter the location at which to set the breakpoint. It has to be specified in one of + the following formats: + + + File_name:Line_number + Function_name + File:Function_name + + + + + The first one is obvious — The location refers to the line number + Line_number in the source file File. + The second refers to the first line of the function + Function_name. The third is similar to the second, except that + this notation is used where there is more than one function with the name + Function_name in the program. It is possible to + differentiate between them by providing the File, so the + notation refers to the function Function_name in the + file File. + + + + + Condition + + + The Condition parameter displays a associated expression + which should evaluate to a Boolean value — that is, the + evaluation of the expression should result in either TRUE(1) or FALSE(0). + If the final evaluation value is not a Boolean value, then it will be + appropriately type casted to a Boolean. + + + Every time the breakpoint is encountered during the execution, the break + condition will be evaluated. The debugger will break the execution only if + the evaluation results in a TRUE value, otherwise it will continue the + execution as though there had been no breakpoint. + + + The default value, if you left this field blank, of Break condition + is TRUE. The debugger will always break the execution at the breakpoint location. + + + + + Pass Count + + + The Pass count is an integer (unsigned) value which + tells the debugger to skip the breakpoint that number of times before it + is considered. Pass count has a higher priority than + the Break condition. Only when the + Pass count reaches zero will the debugger evaluate the + Break condition (if any condition is present). If there + is no condition, the debugger will break the execution once the + Pass count counts down to zero. + + + The default value, if you left this field blank, of the Pass count + is zero. The breakpoint will be considered when it is first encountered. + + + + + + + A breakpoint may also be set by selecting a line in the editor and choosing the menu item Debug - Toggle Breakpoint, the editor popup + Toggle Breakpoint in the editor popup menu item - Toggle Breakpoint - or the Toggle Breakpoint icon in the + or the Toggle Breakpoint icon in the Debug toolbar. @@ -382,8 +494,8 @@ Editing Breakpoints - It is possible to change the condition of a breakpoint of the pass count by - selecting the breakpoint to edit in the breakpoint list and click in the + It is possible to change the condition and the pass count by + selecting the breakpoint in the breakpoint list and click in the popup menu item Edit Breakpoint. @@ -395,8 +507,8 @@ Deleting Breakpoints - Select the breakpoint to delete in the breakpoint list view and click on - Remove Breakpoint. + Select the breakpoint in the breakpoint list view and click on + Remove Breakpoint to delete it. A existing breakpoint may also be deleted by selecting the line in the editor @@ -407,6 +519,12 @@ or the Toggle Breakpoint icon in the Debug toolbar. + + It is possible to remove all breakpoints by clicking on Debug + Remove All Breakpoints or on + Remove All Breakpoints in + the breakpoint list popup menu. + @@ -415,7 +533,7 @@ Click on the Enable column of the Breakpoint list window or in the menu item Enable Breakpoint to enable or disable the selected breakpoint. - The breakpoint will be enabled or disabled, depending on the current state. + The breakpoint will be enabled or disabled, depending on its current state. To disable all breakpoints, click on Debug @@ -439,10 +557,10 @@ Locals - Local variables of the current frame (the current funtion in which the program control + Local variables of the current frame (the current function in which the program control is present) are displayed in the Locals list window. During execution of the program (eg. during single stepping), local - variables will be updated. If any varialble value was changed in the last debugging step, its + variables will be updated. If any variable value was changed in the last debugging step, its value will be highlight in red. The variables are presented in a tree form for easy view.
@@ -460,7 +578,7 @@ Gdb is more and more often used as a back end for a graphical front end. It - has been improved recently in this area. It is recommanded to use the latest + has been improved recently in this area. It is recommended to use the latest version (6.6) of gdb. On older version, gdb can crash when the front end ask for an pointer with an invalid (but not used) value. @@ -546,11 +664,24 @@ + + Inspecting expressions in editor window + + When the debugger is active with the program stopped, you can get the value of an + expression just by putting the pointer over it and stay here for a few time. + If the expression is already present in the local or watch window, its value is + displayed in a tool tips window. + + + It is currently working only for simple variable, not for structures or arrays. + + + - Stack Trace and Thread + Stack Trace Stack Window @@ -588,7 +719,7 @@ Setting the current frame - Double-clicking on any frame in the stack trace will set that frame as the + Double-clicking on any frame in the stack trace set that frame as the currently selected frame (the arrow will point to the frame, indicating that it has been selected as the current frame). Alternatively, open the Operation menu by right-clicking on the @@ -596,11 +727,16 @@ Set frame to set the frame. - Changing the stack frame will change the Locals list window + Changing the stack frame changes the Locals list window content, but not the expression watch window as each expression is evaluated in the frame used when it was defined. + + + + + Thread Thread Window @@ -611,8 +747,8 @@ A small arrow points to the current thread. When the - programm is stopped, it correspond to the thread which has been interrupted. - Each thread has its own stack frame,so changing the current thread will change + program is stopped, it correspond to the thread which has been interrupted. + Each thread has its own stack frame,so changing the current thread change the current stack frame. @@ -628,8 +764,8 @@ Set current thread to set the thread. - Changing the thread will change the value of CPU registers and the current - stack frame, so the Locals list window will change too. + Changing the thread changes the value of CPU registers and the current + stack frame, so the Locals list window change too. @@ -663,7 +799,7 @@ The first is the memory address in hexadecimal, the second is the memory content - in hexadecimal too and the last column is the memory content in ascii. + in hexadecimal too and the last column is the memory content in ASCII. The addressing space of even a 32 bits microprocessor is quite big(4 Giga bytes), -- 2.11.4.GIT