mirrors/eiffel-org
1
0
Fork 0
mirror of https://github.com/EiffelSoftware/eiffel-org.git synced 2025-12-08 07:42:33 +01:00
Code Issues Packages Projects Releases Wiki Activity

Created 18.01 branch of the documentation.

Browse Source 
git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@1942 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
eiffel-org
2018-02-08 15:00:31 +00:00
parent 265a446dab
commit b5d5c80911
2923 changed files with 61520 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/breakpoints/breakpoint-commands.wiki Normal file
View File

@@ -0,0 +1,12 @@
[[Property:title|Breakpoint commands]]
[[Property:weight|2]]
[[Property:uuid|3631e866-0acd-005d-b1f5-f43377b6e27f]]
Located in the '''debug''' menu and the '''project''' toolbar, three commands allow you to change the state of set [[Breakpoints|breakpoints]] in the system.
Enable breakpoints ( [[Image:16x16--breakpoints-enable-icon]] ), disable breakpoints ( [[Image:16x16--breakpoints-disable-icon]] ) and remove breakpoints ( [[Image:breakpoints-delete-icon]] ) all have global and local actions. Left-clicking on them has a global action: all breakpoints currently set in the system will be respectively enabled, disabled, or discarded. However, it is also possible to [[Pick-and-drop mechanism|drop]] a feature or a class onto them, in which case only set breakpoints of the feature/class will be affected.
Note that these commands work only on set breakpoints (that is, enabled or disabled breakpoints). Therefore, discarded breakpoints cannot be set again with these commands.

60
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/breakpoints/breakpoint-editing.wiki Normal file
View File

@@ -0,0 +1,60 @@
[[Property:title|Breakpoint editing]]
[[Property:weight|1]]
[[Property:uuid|1ac830ab-7600-8e52-2351-c515bcc31d41]]
In all flat views ( [[Feature formatters: Flat view|feature flat view]] and [[Class formatters: Flat view|class flat view]] ), a margin is displayed on the left of the editor. [[Breakpoints|Breakpoints]] are symbolized there as circles, with different looks depending on their state: enabled ( [[Image:bp-enabled-icon]] ), disabled ( [[Image:bp-disabled-icon]] ) or not set ( [[Image:bp-slot-icon]] ). A small question mark in the circle ( [[Image:bp-enabled-conditional-icon]] , [[Image:bp-disabled-conditional-icon]] ) indicates [[Breakpoint menu|conditional breakpoints]] .
Right-clicking on any breakpoint pops up a context menu:
[[Image:breakpoint-context-menu]]
The first line provides the breakpoint slot index of the selected breakpoint (i.e: the one used in call stack or exception trace output). <br/>
Clicking one of the three first entries of the context menu changes the state of the breakpoint that was right-clicked. The last entry ('''Run to This Point''') launches the debugged application so that it will stop as soon as the selected breakpoint is encountered, as if the breakpoint had been enabled. <br/>
"Edit This Breakpoint" allows you to edit the parameters of the breakpoint (condition, hit count, when hits actions...) through the breakpoint dialog. On the first tab, '''Context''', the breakpoint dialog provides access to the associated tags, condition, and hit count control. And on the second tab, it allows you to associate '''When hits...''' action(s) with the breakpoint.
{|
|-
|
'''Context''' tab
[[Image:breakpoint-dialog-context|Context tab]]
|
'''When hits ...''' action tab
[[Image:breakpoint-dialog-when-hits-action|When hits... tab]]
|}
Tags allow you to identify a collection of breakpoints, either from the [[Breakpoint information command|breakpoints tool]] , or in the parameters of "When hits .." actions. <br/>
Any existing breakpoint can be referenced by an implicit tag with the form: ''"'''bp:'''cluster.{CLASS}.feature@index"'' (cluster is not mandatory).<br/>
{{sample|A sample breakpoint tag: "'''bp:'''elks.{LINKED_LIST}.extend@2"}}
* the "Condition" allows you to set a condition for stopping.
* the "Hit count" allows you to set a condition on hitcount for stopping.
* And the "When Hits..." allows you to associate specific actions with the breakpoint:
** Print message: display the expanded message to the output (there are predefined variables, and you can also evaluate expressions).
** Disable/Restore Assertion Checking: this might be useful to deactivate assertion checking on a specific part of the execution.
** Record Execution: start or stop the execution recording (cf: [[Execution record and replay|Execution recording and replay]] )
** Enable/Disable Breakpoints: either use tags or implicit tags (ex: ''"bp:elks.{LINKED_LIST}.extend@2"''), to reference a set of existing breakpoints. This can be pretty useful to enable a breakpoint only if the execution takes a specific execution path.
** Reset Hits count
"Edit Condition" allows you to set a condition for stopping, it opens the same dialog as "Edit This Breakpoint", but focus on the "condition" field.
[[Image:breakpoint-dialog-condition]]
"Hit count" allows you to set a condition on hitcount for stopping
[[Image:breakpoint-dialog-hit-count]]
"When hits ..." allows you to perform an action, print a message for example, when execution stops on this breakpoint.
[[Image:breakpoint-dialog-when-hits]]
{{seealso| [[Breakpoint commands|Breakpoint commands]], [[Breakpoint information command|Breakpoint information command]] }}

31
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/breakpoints/breakpoint-information-command.wiki Normal file
View File

@@ -0,0 +1,31 @@
[[Property:title|Breakpoint information command]]
[[Property:weight|3]]
[[Property:uuid|9fa30dd2-231f-c1f2-4139-f8e90df0e77f]]
The breakpoint information command, located in the '''debug''' menu and in the '''project''' toolbar ( [[Image:tool-breakpoints-icon]] ), displays the list of all set breakpoints in the system (enabled or disabled).
Display all breakpoints in a grid:<br/>
[[Image:breakpoints-list]]
{{note|<br/>
The * shows that the breakpoint has a [[Breakpoint menu|condition]] .<br/>
You can edit the selected breakpoint by double clicking on it, or pressing [enter] which show the menu.<br/>
You can disable/enable the selected breakpoint(s) by pressing [space].<br/>
You can sort by clicking the column, especially the first column which provide tree, flat or sorted view. }}
Display all breakpoints in a list:<br/>
[[Image:breakpoints-list-flat]]
Display all breakpoints in a list filtered by a tag using button [[Image:breakpoints-list-filter-button]] : <br/>
[[Image:breakpoints-list-filter]]
{{seealso|<br/>
[[Breakpoint commands|Breakpoints commands]] <br/>
[[Breakpoint information command|Breakpoint information command]] <br/>
}}

26
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/breakpoints/breakpoint-menu.wiki Normal file
View File

@@ -0,0 +1,26 @@
[[Property:title|Breakpoint menu]]
[[Property:weight|4]]
[[Property:uuid|dd68a84b-9bb7-98d5-8aa3-7e16969086f1]]
A condition breakpoint is a breakpoint in which debugger will stop if a certain condition is met. To set a conditional breakpoint use the [[Breakpoint editing|breakpoint menu]] and choose `Set conditional breakpoint':
[[Image:breakpoint-context-menu]]
Once done a dialog pops up where you can enter a condition:
[[Image:breakpoint-dialog-condition]]
The condition is a Boolean expression that follows the same rule as the expression you can enter in the [[Expression evaluation|expression evaluation tool]] . <br/>
{{caution|If you enter an expression that is not supported or which raises an error during evaluation, by default the condition is considered as True (then the debugger will stop) }}
{{seealso|<br/>
[[Breakpoint editing|Breakpoint menu]] <br/>
[[Breakpoint commands|Breakpoints commands]] <br/>
[[Breakpoint information command|Breakpoint information command]] <br/>
[[Expression evaluation|Expression evaluation tool]] <br/>
}}

32
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/breakpoints/index.wiki Normal file
View File

@@ -0,0 +1,32 @@
[[Property:title|Breakpoints]]
[[Property:weight|-14]]
[[Property:uuid|6ed5890a-9b23-210a-5640-cee348d6e27e]]
Breakpoints are entities that stop a debugged application. Breakpoints can be put at the beginning of each execution line, so that it is possible to see the context in which the line is executed before executing it.
In EiffelStudio, breakpoints are represented as circles in the left margin of flat views (both [[Feature formatters: Flat view|feature flat view]] and [[Class formatters: Flat view|class flat view]] ).
Breakpoints can be in three different states: '''enabled''' ( [[Image:bp-enabled-icon]] ), '''disabled''' ( [[Image:bp-disabled-icon]] ), or '''not set''' ( [[Image:bp-slot-icon]] ).
Only enabled breakpoints will stop the application when they are encountered. By default, breakpoints are not set.
Disabled breakpoints are useful to temporarily discard a breakpoint, while keeping the possibility to put it back quickly.
Enabled and disabled breakpoints can have an associated '''[[Breakpoint menu|condition]]''' . They are then shown as [[Image:bp-enabled-conditional-icon]] and [[Image:bp-disabled-conditional-icon]] .
Left-clicking on a breakpoint in a flat view changes the state of the breakpoint: it switches from not set to enabled, from enabled to not set, and from disabled to enabled. Removing a conditional breakpoint discards its condition.
The [[Breakpoint editing|breakpoint menu]] lets you change the state of one breakpoint, whereas the [[Breakpoint commands|breakpoint commands]] let you change the state of several breakpoints at a time. The [[Breakpoint information command|breakpoint information command]] shows the state of all set breakpoints.
{{note|You can toggle the status of a breakpoint easily using shortcuts<br/> - '''F9''': toggle between enabled/not-set. <br/> - '''Shift+F9''': toggle between enabled/disabled.<br/> - '''Ctrl+F9''': open the breakpoint dialog for [[Breakpoint editing|editing]]. }}
{{note|Breakpoints cannot be set in all features. In particular, breakpoints cannot be set in external features or attributes. <br/>
However, breakpoints can be set in assertions (require and ensure). }}
{{tip|Breakpoints can be set on-the-fly while the application is running. }}
{{tip|You can relocate a breakpoint by '''Ctrl+RightClick''' on a breakpoint [[Image:bp-enabled-conditional-icon]] and '''Ctrl+RightClick''' on an empty breakpoint location [[Image:bp-slot-icon]] }}
{{tip|to go to the line corresponding to a specific breakpoint index, just use Ctrl+G, enter the index, and the corresponding line should appear selected}}

34
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/call-stack-tool/call-stack-tool-interface.wiki Normal file
View File

@@ -0,0 +1,34 @@
[[Property:title|Call stack tool: Interface]]
[[Property:weight|1]]
[[Property:uuid|ff70f68f-31db-c5d1-4d68-7b0fc70b1dd7]]
[[Image:call-stack-tool]]
The call stack tool provides information, at a particular point during system execution, about the call stack of a system being executed under control of the debugger.
The call stack is composed of a list representing the call stack elements, in which the root procedure of the system is at the bottom of the list and the currently executing routine is at the top. <br/>
* The currently selected call stack element, to which the [[Information relative to a stack element|other debugger tools]] refer, is indicated by a green arrow [[Image:callstack-active-arrow-icon]] . <br/>
* Clicking on a call stack element represented by an empty arrow [[Image:callstack-empty-arrow-icon]] , or picking the element and dropping it onto either the call stack list or the locals view defines it as being the currently selected call stack element. <br/>
* The call stack elements with no icon are called external call stack elements, they represent a call stack out of Eiffel, for example, a true .NET call stack. <br/>
* For each feature in the call stack, the name, dynamic class, and static class are displayed. The dynamic class is the type of the object upon which the feature is called, whereas the static class is the class in which the feature was written.
* An asterisk next to the name of a feature means the feature is melted, as opposed to frozen.
At the top of the list, one line of text gives the state of the debugged application, in this case "Status = Breakpoint reached". A second line describes the exception that caused the application to stop, if any. In the case shown above, execution stopped at a breakpoint, so no exception is shown on the second line. For more information concerning exceptions, see the [[Supported exceptions|supported exceptions]].
The button [[Image:debug-exception-dialog-icon]] is used to open the Exception dialog which show the exception details. For instance a call on Void target in a .NET system would popup :
[[Image:exception-dialog]]
When more than one thread is available to the debugger, you can switch from one thread to another. To do that, click on the thread's id "0x000..." and select from the pop-up list of available threads. Or (recommended) you can use the [[Threads tool|threads tool]] (clicking on '''Show threads panel''' will show the threads tool).
[[Image:call-stack-tool-with-threads]]
In the toolbar, the button [[Image:general-save-icon]] gives you the capability to [[Save call stack|save the call stack]] to a text file. The button [[Image:general-copy-icon]] can be used to copy the call stack to the clipboard. The [[Image:debugger-callstack-depth-icon]] button makes it possible to choose a desired depth for the call stack in the list (the default is to display the 100 top stack elements).

14
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/call-stack-tool/index.wiki Normal file
View File

@@ -0,0 +1,14 @@
[[Property:title|Call stack tool]]
[[Property:weight|-13]]
[[Property:uuid|8c3cd0fe-78aa-7ec6-f36a-2233a4e26755]]
The call stack is the list of routines that have been entered during execution, but not yet exited since execution started. The list can be considered a '''stack''' structure, because before any routine, say <code>my_routine</code>, can exit, any routine that <code>my_routine</code> may have called must have exited first. Therefore the last entered feature is listed at the top of the stack and the program root feature is its bottom.
There is one level in the call stack, the currently selected element, that has a special status. It is the level to which all debugging tools refer. The currently selected element is, as you might guess, user-selectable. So it is possible to move along the call stack, changing the currently selected element, and view information in the debugging tools about any level..
To keep a record of a call stack (for example in order to indicate to other people where a problem occurred), you can [[Save call stack|save the call stack]] to a text file.
Information concerning the call stack is spread over several graphical components:
* The entire call stack, depicted as a list of elements, is displayed in the [[Call stack tool: Interface|call stack tool]] .
* [[Information relative to a stack element|Information concerning the current call stack element]] is displayed in the feature tab, the locals view, and is used to provide the expressions evaluations contained in the [[Evaluation tool or Watch tool|Expression evaluator tool]] .

12
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/call-stack-tool/information-relative-stack-element.wiki Normal file
View File

@@ -0,0 +1,12 @@
[[Property:title|Information relative to a stack element]]
[[Property:weight|2]]
[[Property:uuid|f78fca33-2e19-1021-70f4-fd262991da7a]]
In addition to the [[Call stack tool: Interface|call stack tool]] that provides global information concerning the call stack, some other debug tools give more detailed information concerning the [[Call stack tool: Interface|currently selected call stack element]] .
In debug mode, the context tool is automatically switched to the feature tab in flat view, and displays the feature which corresponds to the current call stack element. In the left margin, a yellow arrow ( [[Image:bp-current-line-icon]] ) marks the execution line where the program is currently stopped, whereas a green arrow ( [[Image:bp-slot-other-frame-icon]] ) indicates the execution line that was attained in the feature in the current call stack element. Therefore, if a feature is recursive, and appears several times in the call stack, changing the current call stack element may cause green arrows to be displayed at different places in the same feature (if the different calls did not reach the same execution point). On the other hand, the yellow arrow can only appear at one place as long as the application is not started again.
The left part of the [[Object tool|object tool]] gives valuable information concerning parameters that were passed to the feature corresponding to the current call stack, the current value of the local variables, and, if the feature is a function, the current value of its result.

8
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/call-stack-tool/save-call-stack.wiki Normal file
View File

@@ -0,0 +1,8 @@
[[Property:title|Save call stack]]
[[Property:weight|4]]
[[Property:uuid|495a2601-8e25-0b48-f86a-6cccf7099c1e]]
It is possible to copy the current call stack to the clipboard ( [[Image:general-copy-icon]] ) or to a text file ( [[Image:general-save-icon]] ). This may be useful to indicate to other members of a team where an error has occurred. After the button is clicked, a dialog is popped up that prompts for a place in which to save the [[Call stack tool: Interface|call stack]] file (if the selected file already exists, it is overwritten).

48
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/call-stack-tool/supported-exceptions.wiki Normal file
View File

@@ -0,0 +1,48 @@
[[Property:title|Supported exceptions]]
[[Property:weight|3]]
[[Property:uuid|f3b4498a-0772-32fb-041d-13428e258f52]]
Here is a list of exceptions that may appear in the [[Call stack tool: Interface|call stack tool]] . When they are raised, a tag may be there to give more information, if necessary. All these exceptions are declared in <eiffel>EXCEPT_CONST</eiffel>.
'''Feature call on Void target''': An attempt was made to call a feature on an object that is Void. The tag indicates the name of the feature of the feature that could not be called. For instance if the code line is <eiffel>a.b.c</eiffel> and the tag is "c" then <eiffel>a.b</eiffel> was Void.
'''No more memory''': A memory allocation failed.
'''Precondition violated''': One of the conditions necessary prior to entering a feature is not verified. This may indicate either that the precondition is too strong, or that the call is invalid. The tag should give the name of the violated precondition, if any.
'''Postcondition violated''': One of the conditions checked when a feature exits is not verified. This may indicate either that the postcondition is too strong, or that the feature did not behave correctly. The tag should give the name of the violated postcondition, if any.
'''Class invariant violated''': One of the conditions that checks the validity of objects is not verified. This may indicate that an object was left in an invalid state after a method call. The tag should give the name of the violated invariant, if any.
'''Assertion violated''': An assertion was not verified. The tag should give the name of the violated assertion, if any.
'''Non-decreasing loop variant''': A loop variant does not vary. This may lead to stack overflows or erroneous results.
'''Loop invariant violated''': A condition that should be checked when executing a loop is not verified. The tag should give the name of the violated invariant.
'''Floating point exception''' (signal SIGFPE): An error occurred while processing floating point numbers. This may be for example a FPU overflow, a division by zero, or an invalid operation.
'''Unmatched inspect value''': An inspect clause couldn't find the value it was passed among the `when` clauses. If any value maybe passed to the `when` clause, adding an `else` clause will solve this problem.
'''I/O error''': An error occurred while accessing a stream. Examples of this are a missing file, or insufficient rights.
'''Retrieval error''': A file could not be retrieved. This maybe caused by an invalid header, or more generally by a corrupted data file.
'''Developer exception''': Developer exceptions can be raised by calling {<eiffel>EXCEPTIONS</eiffel>}.<eiffel>raise</eiffel>. They can indicate any kind of internal error.
'''Operating system signal''': The program received a signal from the operating system.
'''Exception in rescue clause''': An exception occurred within a rescue clause.
'''Void assigned to expanded''': An attempt was made to assign a Void value to an expanded object.
'''Run-time I/O error''': Exception raised by the run-time when encountering a I/O error internally.
'''External event''': On Unix, this happens when an operating system error occurs and does not set the `errno` variable.
'''Operating system error''': On Unix, this happens when an operating system error occurs and sets the `errno` variable.
'''COM error''': Raised when EiffelCOM encounters an error.

63
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/command-line-debugger.wiki Normal file
View File

@@ -0,0 +1,63 @@
[[Property:title|Command line debugger]]
[[Property:weight|-3]]
[[Property:uuid|ad1ef861-8307-a56c-5f94-f236c520da55]]
The command line debugger is not as rich as the EiffelStudio debugger, however it provides simple debugging functionalities without any graphical user interface.
= How to enter the command line interface ? =
* ec -config your_system.ecf -debug
* Then you get the debug menu
--< Debugger main menu >--
(A) Set arguments
(E) Set environment
(D) Set working directory
(I) Display parameters
---
(R) Start and stop at breakpoints
(L) Start without stopping at breakpoints
(S) Step into
---
(H) Help
(Q) Quit
->
* Enter your choice using the letter inside parentheses
** (A) to set the arguments for the execution
** (E) to set the environment variables
** (D) for the working directory
** (R), (L) or (S) to start the execution
** When the execution is paused, you can display the menu by pressing ENTER
= To set breakpoints =
If you want to set breakpoints, you first need to step into (S) to start execution
** The execution starts, then pauses at the entry of the system
** Press ENTER to get the new "Debugger execution menu"
--< Debugger execution menu >--
(N) Step next
(I) Step into
(O) Step out
(C) Run to next stop point
(G) Run without stop point
(T) Toggle 'Ignore stop point'
(K) Kill application
(P) Pause application
---
(B) Breakpoints control
(D) Display information
(H) Help
->
** Then you choose "(B) Breakpoints control" to add, modify or list breakpoints.
--< Debugger menu :: Breakpoints >--
(A) Add breakpoint
(M) Modify existing breakpoint
(L) List breakpoints
(H) Help
(..) Back to parent menu
->
= Limitations =
* It is not possible to interrupt the execution.
* The command line debugger is not as rich as the EiffelStudio graphical debugger. As a result you may miss specific functionalities (such as conditional breakpoints, ...) available in the EiffelStudio debugger.
* The command line debugger is experimental. It would need more enhancement to satisfy advanced debugging needs, however it provides simple (and limited) debugging facilities directly from the command line.

25
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/debuggees-object-storage.wiki Normal file
View File

@@ -0,0 +1,25 @@
[[Property:title|Debuggee's Object Storage]]
[[Property:weight|-9]]
[[Property:uuid|b26fb1b0-85ef-26b5-9b9d-6e3b8ad977c2]]
This command can be accessed through the context menu, and from the objects tool, and watches tools thanks to the tool bar's button [ [[Image:execution-object-storage-icon]] ].
By Pick-and-Dropping a debuggee object onto the button [ [[Image:execution-object-storage-icon]] ], you raise the "save" dialog. Then you need to choose the name for the file into which EiffelStudio will store the debuggee object.
[[Image:debuggee-object-storage-save]]
By clicking on Evaluation tool's button [ [[Image:execution-object-storage-icon]] ], you raise the "load" dialog. Then you need to select the name of the file which contains the debuggee object's storage. If the loading is successful, the retrieved object will be added in the related Evaluation tool. <br/>
[[Image:debuggee-object-storage-load]]
{{tip|By Pick-and-Dropping an object onto the button, you can load the retrieved values into the dropped object (provided that both have the same type).}}
{{caution|For now this command implements only basic functionality, and is provided as-is. The underlying implementation uses <code>{FILE}.independent_store</code> and <code>{FILE}.retrieved</code> for save and load operations. To load the value into an existing object, it uses <code>{ANY}.standard_copy (..)</code>. For details, you can have a look at the code in class <code>RT_EXTENSION_GENERAL</code>. }}

22
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/debugging-limitations.wiki Normal file
View File

@@ -0,0 +1,22 @@
[[Property:title|Debugging limitations]]
[[Property:weight|-2]]
[[Property:uuid|4377d765-8664-ee0c-5d5b-e42fd7d172c3]]
==General limitations==
* Watch expression: Agents are not supported (for instance "agent my_function" is not supported").
* You cannot yet create an instance of SPECIAL.
* The debugger is not very helpful when the execution is stopped inside an invariant.
* Wrong assertion tag shown in debugger for precondition violation if violated during an exception rescue, indeed the tag remains the one from the exception
* If you use the "Disable Assertion Handling" functionality when the execution is stopped in a rescue, the effect might be cancelled as soon as the execution exits the rescue's associated feature.
* Evaluating an expression with a catcall might crash the debugger
==Limitations or known bugs for the Classic debugger==
* Evaluating <code>Precursor</code> will produce the current feature's <code>Result</code> (not the precursor)
* If you use any of the previous non supported expressions in a breakpoint condition, since the evaluation is failing the condition will always return True. In such case the debugger will stop.
==Limitations or known bugs for the .Net debugger==
* When stepping through disabled assertions or disabled debug clauses, the debugger may show incorrect current line.
* When stepping through an inspect code, the debugger may show incorrect current line (especially if the inspect is not ordered)
* Under dotnet v2.0, the debugger may have difficulties to fetch the stack values, especially during first chance exception events

19
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/debugging-preferences.wiki Normal file
View File

@@ -0,0 +1,19 @@
[[Property:title|Debugging preferences]]
[[Property:weight|-4]]
[[Property:uuid|05e820ff-917f-e41f-d921-990283ac886f]]
Debugger preferences are available as part of the [[EiffelStudio Preferences]].
The debugger section of the EiffelStudio preferences looks like this:
[[Image:debugging-tools-preferences]]
The EiffelStudio preference documentation contains a guide to the [[Debugger Preferences]].
Some preferences have an effect upon the speed at which the debugger can display objects:
* Enable/disable the debug_output display (see [[Debug output|debug output]])
* Enable/disable the full generic type display (for example, <eiffel>ARRAY [INTEGER]</eiffel> is displayed, instead of only <eiffel>ARRAY</eiffel>)
* To avoid infinite evaluation processing, the debugger aborts evaluation after "max evaluation duration" timeout.

15
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/debugging-tips-objects-grid-view.wiki Normal file
View File

@@ -0,0 +1,15 @@
[[Property:title|Debugging tips with the objects grid view]]
[[Property:weight|-5]]
[[Property:uuid|56b3c189-8fda-d78e-7e7c-c4cf4f786ff6]]
General behavior
* Double clicking on the grid's header separator will resize the corresponding column. If you hold the <code>SHIFT</code> key at the same time, it will resize according to the displayed cells.
* Right clicking on the header's cell will popup a menu that enable or disable the auto resizing on the selected column. This can be useful to resize automatically the "name" column when inspecting an object value.
* Pressing <code>CTRL</code>+<code>E</code> when the selected line represents a value with potential text representation (STRING, DEBUG_OUPUT ...) will open the [[Object Viewer (also known as Expanded display)|expanded view dialog]].
Evaluation tool (also known as Watch tool)
* Dropping an object value on a [[Evaluation tool or Watch tool|Evaluation tool ]] will open the [[New expression dialog|expression definition dialog]] with the object's address filled. This way you can evaluate expression directly on this object. If you hold the <code>CTRL</code> key while dropping, the dropped object will be added as expression in the Evaluation tool as itself.
* You can also drop the object on the notebook tab of the desired Evaluation tool.

44
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/exceptions-handling-tool.wiki Normal file
View File

@@ -0,0 +1,44 @@
[[Property:title|Exceptions handling tool]]
[[Property:weight|-7]]
[[Property:uuid|9a62611f-46ba-7d74-ba1c-989f6709074b]]
This Exceptions handling tool is used to specify whether the debugger stops or continues on specific exceptions.
To access this tool, follow the menu path:
<code lang=text>
Execution --> Exception handling</code>
{{note|Now that exceptions are objects in Eiffel, the mechanism is unified for classic and .NET systems, using the Eiffel exception class names. }}
==Tailoring exception handling behavior==
The image below shows the Exceptions handling tool.
[[Image:exceptions-handling-tool|Exception handling tool]]
In the top two checkboxes, the tool provides a way to enable and disable "Catcall" warnings on the console or in the debugger.
If the "filter exceptions" checkbox is enabled, for each exception you can specify the exception action as one of:
* '''Disabled''' means that filtering for this exception is not enabled. Therefore, the default behavior of '''Catch''' applies.
* '''Catch''' means stop on such an exception.
* '''Ignore''' means do not stop on such an exception.
You can double clicking an exception name to toggle its status between '''Ignore''' and '''Catch'''.
Clicking the button labeled ''Ignore External Exception?'' will set the status of a set of external exceptions to '''Ignore'''.
Click the button labeled ''Apply'' to apply your selections, or ''Reset'' to reset the tool to its default values.
{{tip|Using the "Pattern" field, you can add your own filters using regular expression.}}

32
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/attach-application.wiki Normal file
View File

@@ -0,0 +1,32 @@
[[Property:title|Attach application]]
[[Property:link_title|]]
[[Property:weight|0]]
[[Property:uuid|e369df0f-2e1f-5730-ae67-cd7b60b55c5f]]
Usually when you want to debug an application, you launch it from EiffelStudio and the debugger is automatically attached to the execution of the application.
However for specific needs (such as server development), you might want to start the execution outside EiffelStudio, and then attach EiffelStudio's debugger to it.
= Requirements: =
* The application should be compiled in workbench mode.
* EiffelStudio should be opened on the project used to compile the application.
= How to make it work? =
* The application execution will wait for the debugger to connect on a specific port number (given by the user).
== Execution ==
There are 2 ways to provide this port number:
* Setting the <code>ISE_DBG_PORTNUM</code> environment variable to a specific port number will make the execution to wait right away for EiffelStudio to attach the process.
* calling <eiffel>{RT_DEBUGGER}.wait_for_debugger (a_port_number: INTEGER)</eiffel> from the application code will wait for EiffelStudio to attach the process.
In both case, if it is unable to open the port, the execution continues, otherwise it waits until EiffelStudio get connected (i.e attach the execution).
It is possible to use any available port number, for that make sure your machine does not already use the port number you choose, and that the application is authorized to open that port (for instance try with port 50505).
Note that the port number should be greater than 1023 and available (i.e not opened by other application).
The range 49152-65535 can be used for such custom or temporary purposes, and is more likely to have available port.
== EiffelStudio ==
To attach the process from EiffelStudio, follow the menu path <code>Execution->Attach Debuggee</code> and provide the same port number as specified above.
(Note that you can add the associated command to the execution tool bar.)
If EiffelStudio is unable to "attach" the debuggee, it will timeout and report the error (this could happen if the debuggee does not open the specific port).
Once attached the execution, EiffelStudio is able to debug the application just as if the application was launched from EiffelStudio.

11
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/detach-application.wiki Normal file
View File

@@ -0,0 +1,11 @@
[[Property:title|Detach application]]
[[Property:weight|0]]
[[Property:uuid|5da63d87-107d-338e-de64-1a52912fd00c]]
When you are executing an Eiffel application within EiffelStudio (i.e you are debugging it), you may want to detach the debugger from this application without killing the application. The "Detach Execution" command will address this need.
You can find it under menu <code>Execution->Detach Execution</code>, and you can also add it to the execution tool bar items.

14
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/execute-one-line-time.wiki Normal file
View File

@@ -0,0 +1,14 @@
[[Property:title|Execute one line at a time]]
[[Property:weight|-9]]
[[Property:uuid|7d4489b4-5f29-2b1c-af83-afc2b25c8f85]]
If no application was already running, this command launches an application compiled in Work Bench mode and stops at its first line.
If an application was stopped, it attempts to execute the instruction located on the execution line where the application is stopped. If this execution line does not contain an instruction, the execution stops at the next execution line.
It is accessible through the '''project''' toolbar ( [[Image:debug-step-over-icon]] ) or through the '''debug''' menu.
{{seealso| [[Execution commands]], [[Generating executables|Compiling in Workbench mode]] }}

33
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/execution-profiles.wiki Normal file
View File

@@ -0,0 +1,33 @@
[[Property:title|Execution profiles]]
[[Property:weight|-13]]
[[Property:uuid|90e64e1c-b5fc-e150-9901-50daffaac893]]
While working on a project, you may want to launch your system with values for one or more arguments, specify a working directory, and/or change certain environment variables.
Those parameters are done by changing the execution profiles. For that you need to use the '''Execution parameters''' dialog.
* You can open this dialog in either of two ways:
** Follow the EiffelStudio menu path: <code>Execution -> Execution parameters</code> .
** Right-click any of the buttons on the debugging/execution toolbar.
==Using the Execution parameters' dialog==
[[Image:argument-dialog]]
The dialog allows you to manage different execution profiles to specify parameters to be passed to the system at execution time.
Each profile lets you set a title, the '''arguments''', the '''working directory''', as well as your own '''environment variables'''.
To use a profile, just select it by clicking the corresponding line in the grid.
Once the appropriate execution profile is selected then the system can be run with those parameters using the Run button (If "Keep Dialog Open" is selected the dialog remains opened).<br/>
To run without any particular parameters, select the '''default''' profile.
If you click on "Run Workbench" or "Run Finalized", the system will be executed outside EiffelStudio (thus debugging is unavailable).
{{tip|From version 6.5, you can unset an environment variable FOO by adding the "&-FOO" to the environment variables. By prefixing with "&-", you mark the variable "FOO" to be removed. If you use "&-*", all variables will be removed (except for any that you add to the list after the "&-*" entry). }}

28
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/index.wiki Normal file
View File

@@ -0,0 +1,28 @@
[[Property:title|Execution commands]]
[[Property:weight|-15]]
[[Property:uuid|098e4d2b-18c5-6933-fe42-2d55e427f5fa]]
While working on a project, you may want to launch it to see if it behaves as expected, and if not to find out where the problem is located.
There are several ways to launch the application you are working on from EiffelStudio:
* [[Run a finalized executable|Run a finalized executable]] [[Image:debug-run-finalized-icon]], where no debug is possible.
* Launch an application and enable its debugging
** [[Run and stop at breakpoints|Launch and stop]] [[Image:debug-run-icon]] as soon as the application encounters a [[Breakpoints|breakpoint]]
** [[Run without breakpoints|Launch and do not stop]] [[Image:debug-run-without-breakpoint-icon]] when encountering breakpoints
* Execute one step in the application
** [[Step into a feature|Step into a feature]] [[Image:debug-step-into-icon]]
** [[Execute one line at a time|Execute one line]] [[Image:debug-step-over-icon]]
** [[Step out of a feature|Exit a feature]] [[Image:debug-step-out-icon]]
Once the application is launched in debug mode, you can [[Pause an application|pause]] [[Image:debug-pause-icon]] it at any time to see its current state or you can [[Stop a debugged application|stop its execution]] [[Image:debug-stop-icon]] completely.
* In addition, you can also [[detach application|detach an application]] being debugged, and there is an experimental solution to [[attach application|attach]] the debugger to the Eiffel application launched outside EiffelStudio.
All these commands are accessible either through the '''Execution''' menu, or through the '''project''' toolbar.
{{seealso| The Eiffel [[Compiler|Compiler]] }}

12
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/pause-application.wiki Normal file
View File

@@ -0,0 +1,12 @@
[[Property:title|Pause an application]]
[[Property:weight|-7]]
[[Property:uuid|846b52cb-6654-23be-3576-cc175a6fbf04]]
This command stops the execution of a running debugged application.
This gives access to dynamic information concerning the application, such as the current [[Call stack tool|call stack]] and the [[Object tool|state of objects]] in the system.
It is accessible through the '''project''' toolbar ( [[Image:debug-pause-icon]] ) or through the '''debug''' menu.
{{seealso| [[Execution commands]] }}

11
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/run-and-stop-breakpoints.wiki Normal file
View File

@@ -0,0 +1,11 @@
[[Property:title|Run and stop at breakpoints]]
[[Property:weight|-15]]
[[Property:uuid|16310d6f-9ab8-e27c-5802-059d8fc80914]]
This command launches an application compiled in Work Bench mode. The application will stop as soon as a [[Breakpoints|breakpoint]] is encountered, or when an exception occurs.
It is accessible through the '''project''' toolbar ( [[Image:debug-run-icon]] ) or through the '''debug''' menu.
{{seealso| [[Execution commands]], [[Generating executables|Compiling in Workbench mode]] }}

12
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/run-arguments.wiki Normal file
View File

@@ -0,0 +1,12 @@
[[Property:title|Run with arguments]]
[[Property:weight|-14]]
[[Property:uuid|0c8c089c-f953-3337-87dc-09a0c8150c21]]
While working on a project, you may want to launch your system with one or more arguments.
There are two ways to access the '''Execution Parameters''' dialog which lets you specify arguments to be used by your system when launched from EiffelStudio:
* By following the EiffelStudio menu path: <code lang="text">Execution -> Execution parameters</code> .
* By right-clicking any of the buttons on the debugging toolbar.
See the [[Execution profiles|Execution parameters dialog]] for more details.

14
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/run-finalized-executable.wiki Normal file
View File

@@ -0,0 +1,14 @@
[[Property:title|Run a finalized executable]]
[[Property:weight|-11]]
[[Property:uuid|a69ab49a-2bd1-a405-837c-b3e629fa5394]]
As opposed to other execution commands, this command launches an application compiled in finalized mode. This has the same effect as running the application in the <code>EIFGENs/target_name/F_code</code> directory from a console prompt.
No debugging is possible with this command, but it lets you test the real speed of your program without any overhead.
It is accessible through the '''project''' toolbar ( [[Image:debug-run-finalized-icon]] ) or through the '''project''' menu.
{{seealso| [[Execution commands]], [[Generating executables|Compiling in finalized mode]] }}

13
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/run-without-breakpoints.wiki Normal file
View File

@@ -0,0 +1,13 @@
[[Property:title|Run without breakpoints]]
[[Property:weight|-12]]
[[Property:uuid|1f619bce-a3c7-5984-d3e6-4c5dceabf53d]]
This command launches an application compiled in Workbench mode. The application will not stop when a [[Breakpoints|breakpoint]] is encountered. However, it stops when an exception occurs.
It is accessible through the '''project''' toolbar ( [[Image:debug-run-without-breakpoint-icon]] ) or through the '''debug''' menu.
{{seealso| [[Execution commands]], [[Generating executables|Compiling in Workbench mode]] }}

14
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/step-feature.wiki Normal file
View File

@@ -0,0 +1,14 @@
[[Property:title|Step into a feature]]
[[Property:weight|-10]]
[[Property:uuid|a141505a-cc5a-afe1-6f8c-8e216bd7a232]]
If no application was already running, this command launches an application compiled in Work Bench mode and stops at its first line.
If an application was stopped, it attempts to enter the feature located on the execution line where the application is stopped. If this feature is an attribute, or another non debuggable feature, it simply executes the current execution line and stops at the next one.
It is accessible through the '''project''' toolbar ( [[Image:debug-step-into-icon]] ) or through the '''debug''' menu.
{{seealso| [[Execution commands]], [[Generating executables|Compiling in Workbench mode]] }}

13
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/step-out-feature.wiki Normal file
View File

@@ -0,0 +1,13 @@
[[Property:title|Step out of a feature]]
[[Property:weight|-8]]
[[Property:uuid|4d3b068d-cbeb-be94-94c9-f73eb12b6c0e]]
If no application was already running, this command launches an application compiled in Work Bench mode and stops at its first line.
If an application was stopped, it attempts to exit the feature where the application is stopped.
It is accessible through the '''project''' toolbar ( [[Image:debug-step-out-icon]] ) or through the '''debug''' menu.
{{seealso| [[Execution commands]], [[Generating executables|Compiling in Workbench mode]] }}

13
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-commands/stop-debugged-application.wiki Normal file
View File

@@ -0,0 +1,13 @@
[[Property:title|Stop a debugged application]]
[[Property:weight|-6]]
[[Property:uuid|648fdd76-c393-982d-5367-1e9b02669248]]
This command kills the debugged application, if any. This stops the debugging session.
It is accessible through the '''project''' toolbar ( [[Image:debug-stop-icon]] ) or through the '''debug''' menu.
{{seealso| [[Execution commands]] }}

26
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-record-and-replay/index.wiki Normal file
View File

@@ -0,0 +1,26 @@
[[Property:title|Execution record and replay]]
[[Property:weight|-12]]
[[Property:uuid|5184f354-f954-49e2-d38f-15214dcd3d6b]]
This feature allows you to record the debugger controlled execution of your system, and then replay this recording when the debugger is stopped. One could regard this feature as a rewind/forward, or undo/redo of the execution calls.<br/>
In practice,
* the debugger is [[Record execution|recording]] the effective routine calls, and the attribute assignments, as well as the local variable assignments.
* when the execution is stopped, you can [[Replay (recorded) execution|replay]] the previous execution from its recording.
* when [[Replay (recorded) execution|replaying]] a recorded execution, the debugger restores the recorded values, and changes the execution cursor to show the recorded context (values, calls) in the debugging tool.
* This way you can use the standard debugging tools to view, inspect the values, browse the calls, and even evaluate expressions on objects ( but, be careful, if you evaluate expressions to avoid side effects).
The execution record and replay functionalities are graphically available on the Call stack tool, or though the "Execution" menu (formerly the "Debug" menu).
How to use it
* Execute while [[Record execution|recording]]
* [[Replay (recorded) execution|Replay]] and use the debugging tools to browse, inspect, evaluate, ...
{{caution|There is a '''specific limitation''' that '''once''' routine's information (not yet called ...) are not recorded and thus not restored as one might expect (for instance, the debugger does not reset a once during replay). This may be changed in a later release.}}
{{caution|Be aware that there is a logical '''limitation''' concerning the world external to EiffelStudio. That is, it is not possible for EiffelStudio to record and replay external changes such as file or database modifications.<br/>
Likewise if, during an external routine call, some Eiffel values are changed, those are not recorded (and thus not replayed).}}
{{note|EiffelStudio provides record and replay '''only in classic mode'''. So the facility is not yet supported for .NET systems.}}

54
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-record-and-replay/record-execution.wiki Normal file
View File

@@ -0,0 +1,54 @@
[[Property:title|Record execution]]
[[Property:weight|1]]
[[Property:uuid|1255beef-e115-b8ae-87f6-08e267fe3d8f]]
For performance reason, the recording mechanism has a few parameters. For now there is no way to change them easily with the graphical debugger, however you can change those parameters by editing (and recompiling) <code>{RT_DBG_EXECUTION_PARAMETERS}.make</code>.
* <code>{RT_DBG_EXECUTION_PARAMETERS}.maximum_record_count</code>
** Type: <code>INTEGER</code>
** Default value: 1_000_000
** Effect: The recording keeps only the last <code>maximum_record_count</code> object's records.
* <code>{RT_DBG_EXECUTION_PARAMETERS}.flatten_when_closing</code>
** Type: <code>BOOLEAN</code>
** Default value: <code>True</code>
** Effect: When leaving a feature, the recorder flattens the associated record. This saves memory space, and optimizes the underlying mechanism. The default value of <code>True</code> is recommended.
* <code>{RT_DBG_EXECUTION_PARAMETERS}.keep_calls_records</code>
** Type: <code>BOOLEAN</code>
** Default value: <code>True</code>
** Effect: When flattening call records' values, keep the sub-call records (i.e: the execution calls history)
* <code>{RT_DBG_EXECUTION_PARAMETERS}.recording_values</code>
** Type: <code>BOOLEAN</code>
** Default value: <code>True</code>
** Effect: During execution, record attribute and locals assignment. Set to <code>False</code> if you just want to review the calls history. Values will not be recorded, but recording will be faster.
{{warning|Since there is no way to restore local values when the execution left the related call stack frame, the recording discards the recorded local values.}}
The recording functionality is graphically available on the Call stack tool, or though the "Execution" menu (formerly the "Debug" menu).
After you start debugging, if at some point you decide to start recording, click on the "record" button in the Call stack tool:
[[Image:exec-replay-00]]
or follow the menu path:
<code lang=text>
Execution --> Activate Execution Recording</code>
{{note|If you want to record from the beginning, just enable the recording before starting the debug session (the recording button is a toggle button)}}
{{tip|You can also use the "When hits.." actions of [[Breakpoint editing|breakpoints]] to start and stop the execution recording. This can be useful to record only the part of an execution that you are interested in.}}
[[Image:exec-replay-00-1]]
The execution is now recorded. Whenever the application is stopped, you can decide to [[Replay (recorded) execution|replay]] the previously recorded execution. See: [[Replay (recorded) execution]] to learn how to replay an execution.
{{note|EiffelStudio provides record and replay only in classic mode. So, it is not yet supported for .NET systems.}}

61
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/execution-record-and-replay/replay-recorded-execution.wiki Normal file
View File

@@ -0,0 +1,61 @@
[[Property:title|Replay (recorded) execution]]
[[Property:weight|2]]
[[Property:uuid|13932252-4eca-7c71-d047-b0b011e50d60]]
The replay functionality is available from a button on the Call stack tool, or though EiffelStudio's "Execution" menu.
{{note|First, you must be sure execution recording is activated ([[Record execution|read how to record execution]]).}}
Now, whenever the application is stopped in the debugger, you can replay the recorded execution by clicking on the "Replay" button:
[[Image:exec-replay-01]]
After clicking the "Replay" button, the Call stack tool enters "execution replay" mode, as shown below:
[[Image:exec-replay-02]]
In "execution replay" mode, the "Replay" button is enabled, and an additional command bar becomes visible with replay control buttons "Back", "Forth", "Previous", "Next", and "Go to". The numbers on the right end of this command bar indicate the call stack depth, the breakable index, and the nested breakable index. The buttons have following meanings:
* '''Back''': means replay back to caller, i.e., down in the call stack.
* '''Forth''': means replay to callee, i.e., up in the call stack.
* '''Previous''': means replay to previous instruction (previous call in the same stack; i.e., similar to step previous) if possible.
* '''Previous''': means replay to next instruction (next call in the same stack; i.e., similar to step next) if possible.
* '''Go to''': replay to the selected call when possible.
Below the command bar, in the first column, you will find a tree structure, which shows, on the root level, the effective call stacks, and for each root node, you can inspect the sub element to browse the call history.<br/>
The '''bold entries''' show the active call stacks (i,e., the current call stack when the debugger was stopped).<br/>
The '''red arrow''' shows the replayed call stack level, and the call stack levels which can be replayed have a light blue background. <br/>
If you expand a node, you will be able to browse the whole recorded execution history from this stack, as shown below (if you expand the bottom node, the whole recorded execution history will be available).
You can still select other call stack levels as you do in normal debugging mode to inspect them. When you do, the red arrow stick to the replayed call, and the green arrow indicates the call stack level you selected.
[[Image:exec-replay-02-1]]
In the image below, we have clicked on "Back" 3 times. You can now also replay "Forth" 3 times. When you execute a "Replay" operation, the debugger restores the related recorded values, and the various debugger tools are updated with tools values (including the watch tools)
[[Image:exec-replay-03]]
And then if you replay "previous" twice, you rewind the execution in the same call stack frame. Notice the "blue" dot that shows the replayed execution cursor.
[[Image:exec-replay-04]]
{{note|When replaying, you will notice the debugging tools are synchronized and refresh. <br/>
This means the objects tool, the watch tools, and the feature tool will display the replayed context (values, and replayed execution cursor). <br/>
If you evaluate an expression in a watch tool, it will use the recorded values. So, be careful about side effects, because you can modify those values... }}

44
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/expression-evaluation/evaluation-tool-or-watch-tool.wiki Normal file
View File

@@ -0,0 +1,44 @@
[[Property:title|Evaluation tool or Watch tool]]
[[Property:weight|1]]
[[Property:uuid|e70d5827-a00d-47ee-9e7a-b7b4bfb34ccf]]
The Evaluation (or Watch) tool displays a list of expressions and their values (provided that those values can be obtained).
[[Image:expression-evaluation-tool]]
In the display, the ''Expression'' column gives the expression's text. The ''Context'' column gives the context in which the [[New expression dialog|expression]] is evaluated. The ''Value'' column gives the result of the expression, and the ''Type'' column the type of the expression's value.
In the image above, you can see various expressions. Look at the one on the fourth line. This is an object that has been dropped on to the Evaluation tool, and the tool displayed it as itself, as shown by "As object" in the ''Context'' column, and by the italic style. The user can name the dropped object by editing the value in the ''Expression'' column for the expression. This can be useful to help you remember the origin of the value.
The expression in the fifth row has an error, the icon is different, and the ''Value'' shows there is an error, double click on it for more details.
{{tip|If the expression returns a non-Void (and non-basic type) object, then the corresponding row in the list is pickable. The object can be dropped, for example, on the Evaluation tool to inspect it or to keep the object visible while stepping through system execution. }}
{{tip|holding the mouse pointer over the expression's cell will pop up a tooltip with details on the pointed expression }}
On top of the list, four buttons can be found.
* the button [[Image:toolbar-dropdown-icon]] is used to create/close watch tools via a menu popup
* [[Image:debugger-auto-values]] Enable or disable auto expressions.
* [[Image:new-expression-icon]] pops up the [[New expression dialog|expression definition dialog]], and can be used to define new expressions. If you have selected text in the editor, this text will be used to create the expression.
* [[Image:general-edit-icon]] edits a currently selected expression (it is not possible to change the context of an expression, only the expression itself). The associated key shortcut is F2.
* [[Image:general-toogle-icon]] disable/enable the evaluation of the selected expressions from the list. <br/>
* [[Image:debugger-set-sizes-icon]] set the slice limits of dropped <eiffel>SPECIAL</eiffel> or <eiffel>NATIVE_ARRAY</eiffel> objects. <br/>
* [[Image:debugger-show-hex-value-icon]] Toggle format display of numeric between decimal and hexadecimal format. <br/>
* [[Image:debugger-expand-info-icon]] This command can give an [[Object Viewer (also known as Expanded display)|expanded display]] of the string relative to an object, by dropping the object onto the button (or pressing <code>CTRL</code>+<code>E</code> on the selected value). Use it if an object has a very long string representation or a string representation that contains carriage returns, for example. <br/>
* [[Image:execution-object-storage-icon]] This button is used to remotely store or load a "stored" object (check [[Debuggee's Object Storage|remote object storage]]). <br/>
* [[Image:general-delete-icon]] removes the selected expressions from the list. The associated key shortcut is Del.
* And the last two buttons are used to move up and down the expressions. You can also move the expressions up and down using <code>CTRL</code>+<code>-</code> or <code>CTRL</code>+<code>+</code> respectively (that is, the Control key with the ''minus'' key or the Control key with the ''plus'' key).
{{tip|Dropping an object onto this list lets you define quickly an expression whose context is the dropped object. This avoids having to type object addresses manually. <br/>
If you hold the <code>CTRL</code> key while dropping, you will add the dropped object as itself. }}

27
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/expression-evaluation/index.wiki Normal file
View File

@@ -0,0 +1,27 @@
[[Property:title|Expression evaluation]]
[[Property:weight|-10]]
[[Property:uuid|e55442ac-7861-1995-d315-baeed6c49223]]
[[Image:expression-evaluation-tool]]
The Expression evaluation tool (sometimes called the Watch tool) makes it possible to evaluate expressions while the application is stopped in the debugger. A typical use for it is the case in which you would like to know the result that an external feature would return. Since you do not have access to the C memory of the application, doing this would be impossible without the Expression evaluation tool. You might also want to know the result of an Eiffel feature whose body is too complex for you to evaluate.
In these cases (and any other that suits you), you should use the dynamic expression evaluation. Simply [[New expression dialog|define the expression]] and its result will be immediately available in the [[Evaluation tool or Watch tool|list of expressions]] .
If you keep the mouse cursor over the expression cell of line, you get a tooltip describing the expression result.
You can disable the evaluation of the selected expression by clicking on [[Image:general-toogle-icon]] . After you do, the context value will display 'disabled'.
If the expression has an error, or if the evaluation raised an exception, you can obtain a more detailed description by double-clicking on the expression row.
{{caution|During the evaluation of an expression, all features that are necessary to obtain the result are called. Therefore, you should avoid calling queries that have side-effects, since doing so may alter the program execution. The Eiffel methodology recommends against creating queries with side-effects for other important reasons, as well. }}
{{caution|Eiffel ''agents'' (for example: <code>agent my_function</code>) are not supported is not supported. }}
{{caution|The evaluation ignores void-safety checking, a side effect is that expression <code>{FOO}</code> is interpreted as <code>{detachable FOO}</code> even if your application is void-safe. Thus keep this in mind when your expression implies <code>TYPE</code> objects. }}
{{caution|Currently, for classic Eiffel systems, evaluating <code>Precursor</code> will result the current feature's result (not the precursor). }}

28
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/expression-evaluation/new-expression-dialog.wiki Normal file
View File

@@ -0,0 +1,28 @@
[[Property:title|New expression dialog]]
[[Property:weight|2]]
[[Property:uuid|95a78497-434d-759f-fdce-f9025c891495]]
Adding new expressions to the [[Evaluation tool or Watch tool|list of expressions]] that should be dynamically evaluated is performed via a dialog.
{|
|-
| [[Image:new-expression-definition-dlg]] <br/>
context: Current feature
| [[Image:new-expression-as-object-definition-dlg]] <br/>
context: As object
|}
The first part in the dialog makes it possible to select the context of the expression.
* The default context is the context of the [[Information relative to a stack element|currently selected call stack element]], as shown in the left image above. This context gives access to the locals, the arguments, the result and the enclosing object features.
* The object context, that requires a valid object address, gives access to the features of the selected object. If you select "As object", the result of the expression is the referenced object itself; and you can supply a name for the object, as depicted in the right image above.
* The last context, the class-related context, gives access to the <code>once</code> and constant features of that class. It requires a valid class name.
The second part prompts for the expression itself. This field supports arguments, dot calls and operators (to a certain extent), but does not support creation expressions, agents or non-object calls. Genericity is partially supported.
The "Keep Assertion Checking" checkbox is used to enable assertion checking during expression evaluation if desired (by default assertions won't be checked).

18
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/index.wiki Normal file
View File

@@ -0,0 +1,18 @@
[[Property:title|Debugger]]
[[Property:weight|-8]]
[[Property:uuid|31c4857e-f19e-e9e3-b7db-d6c30515277f]]
A debugger is a tool that allows you to [[Execution commands|run]] an application and view its state at any moment. This includes having information concerning the current [[Call stack tool|call stack]] and the [[Object tool|state of objects]] of the system, i.e. the values of their attributes. This kind of information can be used to spot objects that have invalid states, to see the consequences of the execution of a feature over an object state, and so on.
The features of the EiffelStudio debugger include:
* Stopping the application in frozen features as well as in melted features
* [[Step into a feature|Stepping into]] features, [[Execute one line at a time|executing them one line at a time]] , or [[Step out of a feature|stepping out]] of them
* Setting [[Breakpoints|breakpoints]] on-the-fly, while the execution is running
* [[Expression evaluation|Dynamic evaluation of expressions]]
* [[Breakpoints|Conditional breakpoints]]
* [[Stack overflow prevention|Stack overflow prevention]]
* Classes can implement the [[Debug output|debug_output interface]] and have their objects display a string in the debugger
* Execution can be recorded to be replayed when execution is paused, use the [[Execution record and replay|execution replay mechanism]] from the call stack tool interface, and have the debugging tools updated.
* Debuggee objects can be stored/retrieved from the debugger, check the [[Debuggee's Object Storage|debuggee object storage mechanism]] available from the objects tool, and watch tools' toolbar.

19
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/object-tool/attribute-symbols.wiki Normal file
View File

@@ -0,0 +1,19 @@
[[Property:title|Attribute symbols]]
[[Property:weight|1]]
[[Property:uuid|6dfbde5d-3423-4f10-6569-30af2ba00dd1]]
In both trees of the [[Object tool|object tool]], objects are displayed. The values displayed for each object fall into two categories: the object's attributes (grouped under the '''attributes''' folder [[Image:feature-attribute-icon]] ) and its once routines (grouped under the '''once routines''' folder [[Image:feature-once-icon]] ).
The following symbol scheme is used to categorize each item:
* [[Image:debugger-object-immediate-icon]] An attribute of a basic Eiffel type, such as [[ref:libraries/base/reference/kernel/integer_chart.xml|INTEGER]] or [[ref:libraries/base/reference/kernel/classic/double_chart.xml|DOUBLE]]
* [[Image:debugger-object-eiffel-icon]] An attribute that is a reference to an object
* [[Image:debugger-object-void-icon]] A Void reference
* [[Image:debugger-object-expanded-icon]] An object that is expanded
For .NET system, special symbols are used to describe :
* [[Image:debugger-object-dotnet-icon]] An object that is external (i.e., not known as an Eiffel type)
* [[Image:debugger-object-dotnet-static-icon]] A static value object that is external (i.e., not known as an Eiffel type)
* [[Image:debugger-object-static-icon]] A static value object that is known as an Eiffel type

16
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/object-tool/debug-output.wiki Normal file
View File

@@ -0,0 +1,16 @@
[[Property:title|Debug output]]
[[Property:weight|2]]
[[Property:uuid|41544c3b-e1f1-53a5-ff63-e63224c32fa3]]
For virtually any object displayed in the Object tool, it is possible for the developer to cause the Object tool to display a user-definable string value next to the object address.
In order to have the instances of a class display such a string in the object tool, make the class an heir to class <eiffel>DEBUG_OUTPUT</eiffel>. Then implement the feature <eiffel>debug_output</eiffel> to return the string to be displayed. At run-time, the debugger will automatically query this feature on all objects that define it, and then will display the results in the object tool and the [[Expression evaluation|evaluation tool]].
{{sample|The numeric *<code>_REF</code> classes inherit (through class <eiffel>NUMERIC</eiffel>) from the class <eiffel>DEBUG_OUTPUT</eiffel> so that it is possible to see immediately the value of *<code>_REF</code> objects in the Object tool. The *<code>_REF</code> classes are reference versions of the basic Eiffel classes such as [[ref:libraries/base/reference/kernel/integer_chart.xml|INTEGER]] and [[ref:libraries/base/reference/kernel/classic/double_chart.xml|DOUBLE]]. So, without <eiffel>DEBUG_OUTPUT</eiffel>, if you wanted to see, for example, the value of the [[ref:libraries/base/reference/kernel/integer_chart.xml|INTEGER]] associated with an instance of [[ref:libraries/base/reference/kernel/integer_ref_chart.xml|INTEGER_REF]] displayed in the Object tool, you would have expand the reference first.}}
{{tip|If an object has a long string output or an output with carriage returns, for instance, pick-and-drop it to the expanded display command [[Image:debugger-expand-info-icon]] in the object tool. }}

47
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/object-tool/index.wiki Normal file
View File

@@ -0,0 +1,47 @@
[[Property:title|Object tool]]
[[Property:weight|-11]]
[[Property:uuid|6b736424-1729-0b6f-6ddd-8240f9f8ffd6]]
[[Image:object-tool]]
The object tool is a debugging tool that displays extended dynamic information about runtime objects while debugging an application. This information includes the values of attributes, as well as the values of <code>once</code> functions that have already been called.
By default the Object tool display is composed of one grid, which gives information about the [[Call stack tool|current stack element]]. Specifically, it provides the Current object value, the arguments' values of the current stack element's feature call, the values of the local variables, as well as the value of the <code>Result</code> (if this feature is a function).
When an exception occurs (for instance, an assertion violation), the object tool will also display the exception information:
[[Image:objects-tool-exception]]
{{note|A specific case for .NET systems: When the system is stopped, the first item of the local view displays the module name for the feature at which execution stopped. }}
All objects can be expanded to see the values of their attributes. They are also pickable, so that it is possible to drop them onto the Object tool, an [[Expression evaluation|expression evaluator tool]] (also know as Watch tool), or an editor.
It is also possible to use the [[Set slice size command|set slice size command]] with [[ref:libraries/base/reference/special_chart|SPECIAL]] objects or [[ref:libraries/base/reference/native_array_chart|NATIVE_ARRAY]] (.NET) objects.
'''The tool bar buttons:'''<br/>
* the [[Remove object command|remove object command]] [[Image:general-delete-icon]] <br/>
* the [[Set slice size command|set slice size command]] [[Image:debugger-set-sizes-icon]] .<br/>
* the button [[Image:debugger-expand-info-icon]] can give an [[Object Viewer (also known as Expanded display)|expanded display]] of the string relative to an object, by dropping the object onto the button (or pressing Ctrl+E on the selected value). Use it if an object has a very long string representation or a string representation that contains carriage returns, for example.<br/>
* the button [[Image:debugger-show-hex-value-icon]] switches the display of integer values between decimal and hexadecimal format.<br/>
* and the button [[Image:execution-object-storage-icon]] controls the [[Debuggee's Object Storage|remote object storage]] .
{{tip|The tool's layout can be customized to have 2 side-by-side "left" and "right" grids holding the various information. This can be done using the button ( [[Image:toolbar-dropdown-icon]] ) from the tool bar which open the objects tool menu and then select "Edit Layout". Then you can use the tool layout editor as shown below to adjust which information you want displayed in each of the two sides. }}
[[Image:object-tool-layout-editor]]
{{note| By default, the object tool displays the full generating type for object, but this can be changed for speed concern in the [[Debugging preferences|preferences]] . The same way, through the [[Debugging preferences|preferences]] , the user can enable or disable the evaluation of the [[Debug output|Debug Output]] feature. }}
{{note|When a row displays a pink background, this indicates the value has changed as a result of the previous step. }}
{{tip|The [[Expression evaluation|expression evaluator tools]] (also known as Watch tools) provide many of the same features as the object tool along with even more functionality. }}

68
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/object-tool/object-viewer-also-known-expanded-display.wiki Normal file
View File

@@ -0,0 +1,68 @@
[[Property:title|Object Viewer (also known as Expanded display)]]
[[Property:weight|4]]
[[Property:uuid|62002ce3-37f9-22de-39f0-0930468a67be]]
You can either show the "Object Viewer" tool through the menu path
<code lang=text>
Execution --> Tools --> Object Viewer</code>
or pop-up the object viewer dialog by clicking the button ( [[Image:debugger-expand-info-icon]] ) located in the tool bar of the [[Object tool|objects tool]] and [[Expression evaluation|watch tool]].
This command [[Image:debugger-expand-info-icon]] opens an object viewer dialog when an object is dropped onto the button.
Depending the nature of the dropped object, you can view it with one or more of several viewers:
* '''Object dump''': dump a text representation of the value
* '''String display''': string representation
* '''XML display''': xml viewer
* '''Object browse''': browse the object, as you would do in the Object or watch tools
* '''Object internal''': display some internal data elements such as:
** <code>class_name</code>
** <code>type_name</code>
** <code>dynamic_type</code>
** <code>field_count</code>
** <code>deep_physicial_size</code>
** <code>physical_size</code>
{{note|The "string display" viewer is available for objects with a string representation, for instance objects whose types conform to [[ref:libraries/base/reference/string_8_chart|STRING_8]] or conform to [[ref:libraries/base/reference/debug_output_chart|DEBUG_OUTPUT]] (see [[Debug output|Debug Output]]. )}}
{{note|The "XML display" is available for objects eligible for "String display", and whose string representation has XML content. The viewer displays XML in a tree-enabled grid.}}
'''String display viewer:''':
[[Image:expanded-display-default]]
Displays the object as a string, by default the displayed length is 50:<br/>
If the limits are over the current slice limits, the displayed string will end by "..." to show there is more.<br/>
If you click on the auto expand button [[Image:debugger-object-expand-icon]] , the slice limits will be set to the lower and upper limits of the string value.
You can enable or disable the line wrapping by clicking onto [[Image:general-word-wrap-icon]] .
'''Object dump viewer:'''
[[Image:object-viewer-dump]]
'''Object browse viewer:'''
[[Image:object-viewer-browse]]
'''Object internal viewer:'''
[[Image:object-viewer-internal]]
'''XML viewer:'''
[[Image:object-viewer-xml]]

10
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/object-tool/remove-object-command.wiki Normal file
View File

@@ -0,0 +1,10 @@
[[Property:title|Remove object command]]
[[Property:weight|5]]
[[Property:uuid|42b5ea32-ef9c-207f-7dbe-c871a4515db3]]
Located in the [[Object tool|object tool]] toolbar, this command [[Image:general-delete-icon]] discards an object from the [[Object tool|object tool]]. All top-level objects can be removed, except the first one, which is the object relative to the [[Call stack tool|current call stack element]] .
Left-clicking on this button removes the selected object from the [[Object tool|object tool]], if possible. It is also possible to [[Pick-and-drop mechanism|drop]] an object onto the button to remove the object.

22
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/object-tool/set-slice-size-command.wiki Normal file
View File

@@ -0,0 +1,22 @@
[[Property:title|Set slice size command]]
[[Property:weight|3]]
[[Property:uuid|ce2469a3-cf00-554e-47bd-5e8b2fdbc783]]
Located in the object tool toolbar, this command [[Image:debugger-set-sizes-icon]] changes the display size of special objects (i.e. objects whose class is [[ref:libraries/base/reference/special_chart|SPECIAL]] ). Because special objects may contain thousands of attributes, only the first fifty are displayed by default. If left-clicked, a dialog is popped up that sets the exploration indices of special objects that will be loaded in the future.
This pop-up also shows the "Maximum displayed string size" in the grid ([[Object tool|object tool]], or the [[Expression evaluation|watch tools]]).
This dialog changes the settings for future special objects:
[[Image:set-slice-size-dlg]]
You can affect the display of a single special object only by [[Pick-and-drop mechanism|dropping]] the object onto this ( [[Image:debugger-set-sizes-icon]] ) command. A dialog box appears, and the special object that is dropped is shrunk or expanded in the tree according to the new exploration indices you set in the dialog box. The dropped object may be any special object, top-level or not.
This dialog changes the settings for a single special object (the dropped object) :
[[Image:set-default-slice-size-dlg]]

24
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/stack-overflow-prevention.wiki Normal file
View File

@@ -0,0 +1,24 @@
[[Property:title|Stack overflow prevention]]
[[Property:weight|-6]]
[[Property:uuid|bd988599-a444-6090-c3c4-a5c7de20b294]]
Stack overflow prevention makes it possible to have the debugger detect stack overflow situations and warn you before they occur.
You can control this option through a dialog accessible via the menu path:
<code lang=text>
Execution --> Overflow prevention...</code>
The dialog lets you decide at which call stack depth a warning should be issued.
[[Image:stack-overflow-dlg]]
By default, a warning is issued when the debugged program reaches a stack depth of 1,000 elements.
{{note|Once an application has stopped at the selected level, it will not stop again until its stack depth goes below the critical stack depth again. }}

20
documentation/18.01/eiffelstudio/eiffelstudio-reference/debugger/threads-tool.wiki Normal file
View File

@@ -0,0 +1,20 @@
[[Property:title|Threads tool]]
[[Property:weight|-8]]
[[Property:uuid|457b71dc-4609-dac1-8458-cd9b64fd5945]]
This tool displays the list of current Eiffel threads. <br/>
To show this tool, use the menu path:
<code lang=text>
Execution --> Tools --> Threads </code>
[[Image:threads-tool|Threads tool]]
By double clicking on a row, you change the current thread for the debuggee (application). If you double click on "Note" cell, you can edit a note, this can be useful to identify a thread during the debugging session.
The highlighted line shows the current thread.