mirror of
https://github.com/EiffelSoftware/eiffel-org.git
synced 2025-12-07 23:32:42 +01:00
Created 18.01 branch of the documentation.
git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@1942 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
eiffel-org
@@ -0,0 +1,24 @@
|
||||
[[Property:title|Error wizard]]
|
||||
[[Property:weight|2]]
|
||||
[[Property:uuid|0c9686a0-2b9b-291f-4f01-930d9017810b]]
|
||||
More often than wanted, Eiffel compilations are not successful. The good point is that when an error is detected by the compiler, it will not be a problem at run-time. The bad point is that you have to fix compilation errors before being able to launch and debug your system.
|
||||
|
||||
When an error occurs during an Eiffel compilation in EiffelStudio, the '''Output''' tab of the context tool displays a description of the error and its location, which looks more or less like this:
|
||||
|
||||
|
||||
[[Image:error-message]]
|
||||
|
||||
|
||||
In this case, the compiler tries to explain that the identifier "sessionid" is not a known identifier in the context where it was typed. This is a common error that mainly occurs when making typos in the code. Assuming the message does not make sense to you (which may happen in more complex cases), you can query more information about the encountered error.
|
||||
|
||||
To do this:
|
||||
* [[Pick-and-drop mechanism|Pick]] the code of the error, in this case VEEN.
|
||||
* [[Pick-and-drop mechanism|Drop]] it either in the editor or on the error help button [[Image:command-error-info-icon]] .
|
||||
* A dialog is then popped up that describes extended information concerning this error type:
|
||||
|
||||
|
||||
[[Image:error-description-dialog]]
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
[[Property:title|External commands editor dialog]]
|
||||
[[Property:weight|4]]
|
||||
[[Property:uuid|9f8de904-3d17-7ce2-1df8-f4824fab5ae3]]
|
||||
From EiffelStudio, you can define up to 10 external commands. Those commands will execute and display their output in the [[Console tool]]. You can execute them through the Tools menu. A typical usage is to use those external commands to integrate with your source control management solution (e.g. CVS, Visual SourceSafe,...)
|
||||
|
||||
|
||||
==Defining external commands==
|
||||
|
||||
To define your own command, select "External commands..." in the Tools menu. Then the following dialog will appear:
|
||||
|
||||
|
||||
[[Image:external-commands-dialog]]
|
||||
|
||||
|
||||
With this dialog you can:
|
||||
* add new commands
|
||||
* edit existing commands
|
||||
* delete existing commands
|
||||
|
||||
To add your first command, simply click on the "Add..." button and the following command editor will appear:
|
||||
|
||||
|
||||
[[Image:external-commands-dialog-editor]]
|
||||
|
||||
|
||||
In this dialog you can give a name to the command, this name will be displayed in the Tools menu. The index (0 thru 9) is the position among the external commands of the command in the Tools menu. The command line is the command you want to execute. In order to execute correctly, the application you will execute needs to be in your PATH environment variable or if it is not you must provide an absolute path to the external command. And you can specify the working directory for that command.
|
||||
|
||||
In addition to the external command name, you can pass as many options as you want. You can also use placeholders that will be translated before calling the external command. Some of those placeholders are:
|
||||
* $class_name: this will be replaced by the name in lower case of the targeted class in editor
|
||||
* $file_name: this will be replaced by the path to the targeted class in editor
|
||||
* $file: this will be replaced by the simple file name without the path
|
||||
* $directory_name: this will be replaced by the directory location of the targeted class in editor
|
||||
* $group_name: this will be replaced by the group name of the targeted class in editor
|
||||
* $line: this will be replaced by the line number of the cursor of the targeted class in editor
|
||||
* $w_code: this will be replaced by the W_code directory of current system, if defined
|
||||
* $f_code: this will be replaced by the F_code directory of current system, if defined
|
||||
You can see the complete [[Console tool#Placeholders|list]] in the Console tool documentation.
|
||||
|
||||
==Executing external commands==
|
||||
|
||||
When you look at the EiffelStudio '''Tools''' menu, you will see that the external commands that you have added have also been added to the bottom of the menu. In the figure below, you see the command we added at index 4:
|
||||
|
||||
|
||||
[[Image:External commands tools menu]]
|
||||
|
||||
|
||||
To execute that command, you can select it from the '''Tools''' menu, or you can use the keyboard shortcut provided. In this case the keyboard shortcut is the default value of '''Alt+4'''.
|
||||
|
||||
The shortcuts for the command indexes can be changed in the EiffelStudio preferences by following the preference path:
|
||||
<code>
|
||||
shortcuts -> external_commands
|
||||
</code>
|
||||
|
||||
External commands execute in the context of the [[Console tool]]. The Console tool should appear automatically, but you can make it visible by following the menu path:
|
||||
<code lang="text">
|
||||
View -> Tools -> Console
|
||||
</code>
|
||||
Then you can dock the console tool, if you would like to have it constantly visible.
|
||||
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
[[Property:title|Dialogs]]
|
||||
[[Property:weight|1]]
|
||||
[[Property:uuid|5d543cd3-8e54-e090-44d4-ee3b51009fe6]]
|
||||
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
[[Property:title|New feature dialog]]
|
||||
[[Property:weight|0]]
|
||||
[[Property:uuid|deb4901a-7b5a-f669-802e-de1efefcc1a0]]
|
||||
The new feature dialog window lets you create simple Eiffel features using the coding standards described in [[Object-Oriented Software Construction, 2nd Edition]]. It automates the task of writing set-procedures for attributes and it makes it easy for you to find the right feature clause for a new feature. The new feature dialog can be invoked whenever you have a class open in a development window. It is also used by the diagram tool when creating a client-supplier link.
|
||||
|
||||
==Use it when...==
|
||||
* You want to be introduced to the style rules for Eiffel code as described in [[Object-Oriented Software Construction, 2nd Edition]], chapter 26.5 (page 891).
|
||||
* You want to create an attribute and you also want an invariant and/or a set-procedure generated for it.
|
||||
* You want to add a feature in a feature clause that is not in your class yet, and you do not remember the feature clause order, or you want to add it in a feature clause that is in your class, but you cannot find it.
|
||||
|
||||
==Do not use it when...==
|
||||
* You want to edit an existing feature. This is not possible, you can only create new features with it.
|
||||
* You want to write a more advanced feature. With the feature wizard, you can enter only a single line of code.
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
[[Property:title|New attribute layout]]
|
||||
[[Property:weight|4]]
|
||||
[[Property:uuid|b13c9004-c8a0-6628-5c70-42c3e2617c10]]
|
||||
<div> [[Image:feature-wizard-attribute]] </div>
|
||||
When clicking '''Attribute''', the window changes to the attribute layout. It has the following components:
|
||||
* [[Feature clauses|Feature clause selection]]
|
||||
* [[Name field|Feature name field]]
|
||||
* [[Type selection|Type selection]]
|
||||
* [[Header comment|Header comment field]]
|
||||
* [[Invariant field|Invariant field]]
|
||||
* [[Set-procedure|Set-procedure check box]]
|
||||
|
||||
==Example==
|
||||
This dialog box:<br/>
|
||||
<div> [[Image:feature-wizard-attribute-example]] </div><br/>
|
||||
Produces this feature:<br/>
|
||||
<code>
|
||||
class
|
||||
PRODUCT
|
||||
|
||||
feature {NONE} -- Access
|
||||
|
||||
price: DOUBLE
|
||||
-- Cost in dollars.
|
||||
|
||||
feature -- Element change
|
||||
|
||||
set_price (a_price: DOUBLE)
|
||||
-- Assign `a_price' to `price'.
|
||||
require
|
||||
a_price_non_negative: a_price >= 0.0
|
||||
do
|
||||
price := a_price
|
||||
ensure
|
||||
price_assigned: price = a_price
|
||||
end
|
||||
|
||||
invariant
|
||||
price_non_negative: price >= 0.0
|
||||
|
||||
end -- class PRODUCT</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
[[Property:title|Argument list]]
|
||||
[[Property:weight|2]]
|
||||
[[Property:uuid|f2d63c29-6be2-b3d9-a735-b18e08c5a678]]
|
||||
For functions and procedures, you can build a formal argument list. You can do this by clicking on the '''New argument''' button as many times as you need arguments.
|
||||
|
||||
{{note|Even though this dialog always shows parentheses, if the list is empty, empty parentheses will not generated. In other words, the dialog will generate the correct Eiffel syntax. }}
|
||||
|
||||
|
||||
<div> [[Image:feature-wizard-3-arguments]] </div><br/>
|
||||
{{note|If you add arguments to a routine, it is not possible anymore to select routine type '''once'''. }}
|
||||
|
||||
|
||||
For every attribute you selected, enter a name in the text box and a type using the [[Type selection|type selection]] .
|
||||
<div> [[Image:feature-wizard-1-argument]] </div><br/>
|
||||
The code that is generated:
|
||||
<code>
|
||||
set_name (s: STRING)
|
||||
do
|
||||
end</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
[[Property:title|Feature body]]
|
||||
[[Property:weight|6]]
|
||||
[[Property:uuid|8f9f0b70-e884-73f1-e270-f1b51ef672c6]]
|
||||
What goes into the feature body field is dependent on what kind of feature you wish to generate.
|
||||
* '''do''': this is the normal procedure type. Enter in the field below '''do''' a body for your feature.
|
||||
<code>
|
||||
do_something
|
||||
do
|
||||
a := b
|
||||
end</code>
|
||||
|
||||
* '''once''': this is the type for a routine that is executed once per execution. As a once routine cannot have arguments, it is disabled when you added one or more arguments.
|
||||
<code>
|
||||
init
|
||||
once
|
||||
load
|
||||
end</code>
|
||||
|
||||
* '''deferred''': this creates a routine of deferred type. The local and body fields gray out as they serve no use anymore.
|
||||
<code>
|
||||
do_something
|
||||
deferred
|
||||
end</code>
|
||||
|
||||
* '''external''': this creates an Eiffel wrap routine around a routine written in another language. Use the body field to enter a string containing the necessary information about the routine using the external syntax.
|
||||
<code>
|
||||
do_something
|
||||
external
|
||||
"C | %"location.h%""
|
||||
end</code>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
[[Property:title|Feature clauses]]
|
||||
[[Property:weight|0]]
|
||||
[[Property:uuid|019ea318-e0e0-dae9-a818-e12232aa8431]]
|
||||
The feature you create will be inserted in the feature clause you specified. If the feature clause was not already in your class, or not in the right place, EiffelStudio adds the feature clause to the class text based on the feature clause order specified in the [[Preferences Reference|preferences]] . By default, this is the order used by the Eiffel Software libraries, such as EiffelBase.
|
||||
==Export status==
|
||||
The export status is the class the feature is accessible for. Usually, this is <eiffel>ANY</eiffel> for public features, or <eiffel>NONE</eiffel> for implementation features, but you can specify any class here.
|
||||
|
||||
|
||||
[[Image:feature-wizard-export]]
|
||||
|
||||
|
||||
|
||||
{{note|In the class text, you can export a feature to more than one class but (for simplicity) not with this dialog. }}
|
||||
|
||||
|
||||
|
||||
==Feature clause names==
|
||||
For feature clause names it is recommended that you pick one from the standard ones, but it is also possible to create a new one. If you have introduced a special feature clause name in your project, add it to the feature clause order list in the [[Preferences Reference|preferences]] and it will also appear in this dialog.
|
||||
|
||||
|
||||
[[Image:feature-wizard-clausenames]]
|
||||
|
||||
|
||||
==Generated code==
|
||||
The code that is inserted in your class as a result of the selections made for the feature clause, is of the form: <br/>
|
||||
<code>
|
||||
feature {EXPORT} -- Clause name</code><br/>
|
||||
except if you specified <eiffel>ANY</eiffel> as export status, which has the same meaning as not specifying class names in the export status: <br/>
|
||||
<code>
|
||||
feature --Clause name</code>
|
||||
<br/>
|
||||
|
||||
For example, if you specified a the "Initialization" feature clause name, and specified <eiffel>NONE</eiffel> as export status, you get: <br/>
|
||||
<code>
|
||||
feature {NONE} -- Initialization</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
[[Property:title|Header comment]]
|
||||
[[Property:weight|3]]
|
||||
[[Property:uuid|45ecda88-003d-fe59-5d4c-3a84d488b6a2]]
|
||||
In the header comment field you can type a description of the feature. For style guidelines in writing a header comment, see [[Object-Oriented Software Construction, 2nd Edition]], chapter 26, section 4. The description should be informative, clear and terse.
|
||||
|
||||
For example, suppose you have an attribute <eiffel>count</eiffel>. You can enter the following header comment:
|
||||
<div> [[Image:feature-wizard-comment]] </div><br/>
|
||||
When clicking '''OK''' this code is generated: <br/>
|
||||
<code>
|
||||
count: INTEGER
|
||||
-- Number of students in course</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
[[Property:title|New feature dialog: feature properties modification]]
|
||||
[[Property:weight|5]]
|
||||
[[Property:uuid|60825ef4-7bc2-d472-8b09-25769689bb34]]
|
||||
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
[[Property:title|Invariant field]]
|
||||
[[Property:weight|9]]
|
||||
[[Property:uuid|9f7ec967-0a45-4ad6-4393-521097467192]]
|
||||
When creating an attribute, you can optionally enter or select an invariant for that feature. That invariant will be added to the end of the existing invariant clause. If the invariant clause did not exist before, it is now created.
|
||||
|
||||
|
||||
[[Image:feature-wizard-invariant]]
|
||||
|
||||
|
||||
If the attribute is of a reference type, you may select the invariant that the attribute may never be void. If it is of a basic expanded type, some other standard options may be chosen. For example, for <eiffel>INTEGER</eiffel> you may select that it should always be positive.
|
||||
|
||||
|
||||
[[Image:feature-wizard-invariant-selected]]
|
||||
|
||||
|
||||
The example above will generate the code:
|
||||
<code>
|
||||
invariant
|
||||
count_positive: count > 0
|
||||
</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
[[Property:title|Local variable]]
|
||||
[[Property:weight|5]]
|
||||
[[Property:uuid|423aa67d-99f4-0f81-3709-161a6be43af9]]
|
||||
Enter a local variable in the <code>local</code> field. A local variable clause will be added to the feature:
|
||||
<code>
|
||||
...
|
||||
local
|
||||
n: INTEGER
|
||||
...</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
[[Property:title|Name field]]
|
||||
[[Property:weight|1]]
|
||||
[[Property:uuid|850bd867-5cbf-34d0-f94c-97a75bfa244b]]
|
||||
The feature name field is a text box that lets you enter a name for the feature. For help on how to choose the right name for a feature, see: [[Object-Oriented Software Construction, 2nd Edition]], chapter 26, section 2.
|
||||
|
||||
|
||||
{{warning|EiffelStudio performs no validation on the name you choose. For example if you type a space in it, it will generate the code, and detect a syntax error only when compiling. }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
[[Property:title|Postcondition]]
|
||||
[[Property:weight|7]]
|
||||
[[Property:uuid|b8196d6c-2a0f-c06e-855f-d9fe23cbe950]]
|
||||
Enter a postcondition in the <code>ensure</code> field. A postcondition clause will be added to the feature:
|
||||
<code>
|
||||
...
|
||||
ensure
|
||||
n = count</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
[[Property:title|Precondition]]
|
||||
[[Property:weight|4]]
|
||||
[[Property:uuid|29b32f9e-799d-de91-d62d-79bdb509144b]]
|
||||
Enter a precondition in the <code>require</code> field. A precondition clause will be added to the feature:
|
||||
<code>
|
||||
...
|
||||
require
|
||||
n >= 0
|
||||
...</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
[[Property:title|Set-procedure]]
|
||||
[[Property:weight|10]]
|
||||
[[Property:uuid|46b84038-099b-070c-15d7-2b7884a50e01]]
|
||||
When creating an attribute, it is common that you will also need a set-procedure for it. For example, for attribute <eiffel>property</eiffel> you need a procedure <eiffel>set_property</eiffel> to set it. This feature takes one argument of the same type as <eiffel>property</eiffel> or is anchored to it. The only thing you have to do with the feature wizard is check the button '''Generate set procedure'''.
|
||||
|
||||
|
||||
[[Image:feature-wizard-setprocedure]]
|
||||
|
||||
|
||||
The feature that is generated in addition to the attribute itself is placed in feature clause <code>Element change</code> and is exported to all classes. If you have selected or entered an invariant, the precondition will protect this invariant. Example of a generated set-procedure:
|
||||
|
||||
|
||||
[[Image:feature-wizard-setprocedure-example]]
|
||||
|
||||
|
||||
<code>
|
||||
feature -- Element change
|
||||
|
||||
set_button (a_button: EV_BUTTON)
|
||||
-- Assign `a_button' to `button'
|
||||
require
|
||||
a_button_not_void: a_button /= Void
|
||||
do
|
||||
button := a_button
|
||||
ensure
|
||||
button_assigned: button = a_button
|
||||
end
|
||||
</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
[[Property:title|Type selection]]
|
||||
[[Property:weight|8]]
|
||||
[[Property:uuid|b2bd8280-a738-dae4-73aa-c1e232245022]]
|
||||
Whenever you need to give a type of something in the dialog, the type selection component is used. The type selection lets you type any class name or you can pick one from the list.
|
||||
|
||||
|
||||
[[Image:feature-wizard-typeselection]]
|
||||
|
||||
|
||||
When you select a class that is in the system and has formal generic parameters, the type selection component lets you specify an actual generic parameter in another type selection.
|
||||
|
||||
|
||||
[[Image:feature-wizard-generictype]]
|
||||
|
||||
|
||||
{{note|The window might grow in size because of the added component. }}
|
||||
|
||||
|
||||
Since the actual generic type selection is also a type selection, you can select another class with generic parameters and nest them as deep as you need.
|
||||
|
||||
|
||||
[[Image:feature-wizard-generictyperec]]
|
||||
|
||||
|
||||
You can also select the type <eiffel>TUPLE</eiffel>, which is a special class that can have zero or more generic parameters. When you select it, it has no parameters, but you can add one by clicking on the '''Add parameter''' button. Click it as often as the number of generic parameters that you need.
|
||||
|
||||
|
||||
[[Image:feature-wizard-tupletype2]]
|
||||
|
||||
|
||||
{{warning|If you need a very complex type, it is better not to use the dialog, as the window might grow bigger than your screen. After you completed the feature, edit it manually in the class text. }}
|
||||
|
||||
|
||||
The code generated for the selected type is quite straightforward, an example:
|
||||
|
||||
|
||||
[[Image:feature-wizard-complextype]]
|
||||
|
||||
<code>
|
||||
new_feature: FUNCTION [TUPLE [INTEGER], BOOLEAN]
|
||||
</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
[[Property:title|New feature dialog overview]]
|
||||
[[Property:weight|1]]
|
||||
[[Property:uuid|c0708842-e5e0-5d5c-5746-0507d1709a3e]]
|
||||
There are two parts in the window. The upper part allows you to choose what type of feature you want to create, a procedure, a function or an attribute.
|
||||
|
||||
|
||||
[[Image:feature-wizard]]
|
||||
|
||||
|
||||
The rest of the window is used to set the characteristics of the new feature. Information you will be asked depends on the type you chose. For more information, click on one of the links below:
|
||||
* [[New procedure layout|New procedure layout]]
|
||||
* [[New function layout|New function layout]]
|
||||
* [[New attribute layout|New Attribute layout]]
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
[[Property:title|New function layout]]
|
||||
[[Property:weight|3]]
|
||||
[[Property:uuid|ae292b6e-7274-47a5-59f1-0f625493474f]]
|
||||
<div> [[Image:feature-wizard-function]] </div>
|
||||
When clicking '''Function''', the dialog changes to the function layout. It has the following components:
|
||||
* [[Feature clauses|Feature clause selection]]
|
||||
* [[Name field|Feature name field]]
|
||||
* [[Argument list|Argument list]]
|
||||
* [[Type selection|Type selection]]
|
||||
* [[Header comment|Header comment field]]
|
||||
* [[Precondition|Precondition field]]
|
||||
* [[Local variable|Local variable field]]
|
||||
* [[Feature body|Selection for: normal, once, deferred or external routine]]
|
||||
* [[Postcondition|Postcondition field]]
|
||||
|
||||
==Example==
|
||||
This dialog box:<br/>
|
||||
<div> [[Image:feature-wizard-function-example]] </div><br/>
|
||||
Produces this feature:<br/>
|
||||
<code>
|
||||
class
|
||||
PRODUCT
|
||||
|
||||
feature -- Status report
|
||||
|
||||
order_price (quantity: INTEGER): DOUBLE
|
||||
-- Total price when ordering `quantity'.
|
||||
require
|
||||
quantity_non_negative: quantity >= 0
|
||||
do
|
||||
Result := quantity * price
|
||||
ensure
|
||||
correct: Result = quantity * price
|
||||
end
|
||||
|
||||
end -- class PRODUCT</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
[[Property:title|New procedure layout]]
|
||||
[[Property:weight|2]]
|
||||
[[Property:uuid|586fd664-1be4-f588-5350-c7c703145c11]]
|
||||
<div> [[Image:feature-wizard-procedure]] </div>
|
||||
When clicking '''Procedure''', the window changes to the procedure layout. It has the following components:
|
||||
* [[Feature clauses|Feature clause selection]]
|
||||
* [[Name field|Feature name field]]
|
||||
* [[Argument list|Argument list]]
|
||||
* [[Header comment|Header comment field]]
|
||||
* [[Precondition|Precondition field]]
|
||||
* [[Local variable|Local variable field]]
|
||||
* [[Feature body|Selection for: normal, once, deferred or external routine]]
|
||||
* [[Postcondition|Postcondition field]]
|
||||
|
||||
==Example==
|
||||
|
||||
This dialog box:<br/>
|
||||
<div> [[Image:feature-wizard-procedure-example]] </div><br/>
|
||||
|
||||
Produces this feature:<br/>
|
||||
<code>
|
||||
class
|
||||
PRODUCT
|
||||
|
||||
feature {PERSON} -- Element change
|
||||
|
||||
place_order (person: PERSON; quantity: INTEGER)
|
||||
-- Mail `quantity' to `person'.
|
||||
require
|
||||
person /= Void and quantity > 0
|
||||
do
|
||||
person.mail_order (Current, quantity)
|
||||
ensure
|
||||
person.has_ordered (Current)
|
||||
end
|
||||
|
||||
end -- class PRODUCT</code>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
[[Property:title|Wizards and dialogs]]
|
||||
[[Property:weight|0]]
|
||||
[[Property:uuid|b216d12e-20a4-5479-18d2-02e622db5322]]
|
||||
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
[[Property:title|Profiler Wizard]]
|
||||
[[Property:weight|0]]
|
||||
[[Property:uuid|f3509b1b-8ff1-c385-3bc1-4e800195f8a4]]
|
||||
The profiler wizard lets you analyze the result of a profiling session. It helps you optimize your system by pointing out the features where your system spends most of its time.
|
||||
|
||||
Before using the profiler wizard you must have generated a ''Run-time information record''. A ''Run-time information record'' is generated by a profiler when a program is executed under its control. Most of the time, the ''Run-time information record'' is generated by the profiler integrated into EiffelStudio. See [[Profiling|How to profile a system]] for more information about how to generate a ''Run-time information record'' with the integrated profiler.
|
||||
|
||||
{{note|You can also use a ''Run-time information record'' generated by an external profiler such as GNU's gprof, Pure Atricia's Quantify, Visual C++ profiler, etc. }}
|
||||
<br/>
|
||||
<br/>
|
||||
|
||||
The diagram below summarizes the execution steps of the profiler wizard.
|
||||
<br/>
|
||||
[[Image:profiler-process]] <br/>
|
||||
<br/>
|
||||
|
||||
{{seealso|<br/>
|
||||
[[Profiling|How to profile a system]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
[[Property:title|How to set up a Profiler Configuration File]]
|
||||
[[Property:weight|0]]
|
||||
[[Property:uuid|0cf0f7bc-1932-fe42-e62d-b37e2e0c424e]]
|
||||
Once executing an instrumented system has generated the proper file, you must have a profile converter process it in order to produce the Execution Profile. The need for the converter comes from the various formats that profilers use to record run-time information during an execution; a simple Profiler Configuration File enables you to describe the format used by any particular profiler.
|
||||
|
||||
The Profiler Configuration File is a file found in the directory $ISE_EIFFEL/studio/profiler where $ISE_EIFFEL is the location of the Eiffel installation. The name of the Profiler Configuration File in that directory is Eiffel for internal profiling and, for external profiling, the name of the profiler tool as specified in the profiler option. EiffelStudio comes with 3 preconfigured external profilers:
|
||||
* '''gprof:''' GNU's gprof
|
||||
* '''win32_ms:''' Visual C++ 5.0 or 6.0
|
||||
* '''profiler.info:''' Pure Atria's Quantify
|
||||
|
||||
The Profiler Configuration File describes the structure of the file generated by the profiler. To create a new Profiler Configuration File for another profiler, just create a new file in the directory $ISE_EIFFEL/studio/profiler and fill it in.
|
||||
|
||||
Here is a complete example showing the various options that maybe specified:
|
||||
<code>number_of_columns: 7
|
||||
-- Number of columns in the file.
|
||||
|
||||
index_column: 1
|
||||
-- Column where the index is stored.
|
||||
|
||||
function_time_column: 3
|
||||
-- Column where the time spent in the function is stored.
|
||||
|
||||
descendent_time_column: 4
|
||||
-- Column where the time spent in the descendents of a function is stored.
|
||||
|
||||
number_of_calls_column: 5
|
||||
-- Column where the number of calls to a function is stored.
|
||||
|
||||
function_name_column: 6
|
||||
-- Column where the name of the function is stored.
|
||||
|
||||
percentage_column: 2
|
||||
-- Column where the percentage of time spent in the function is stored.
|
||||
|
||||
second_percentage_column: 0
|
||||
-- Column where the second percentage of time spent in the function is stored.
|
||||
|
||||
generates_leading_underscore: no
|
||||
-- Says whether the profiler generates leading underscores (yes) or not (no).</code>
|
||||
|
||||
As in Eiffel, -- introduces a comment, which has no effect on the specification. If one of the xxx_column options has a value of 0, this means that the files generated by the given profiler contain no such column. The order of the options is not significant.
|
||||
|
||||
<br/>
|
||||
{{seealso|<br/>
|
||||
[[Select a Run-time information record to generate the Execution Profile|Select a Run-time information record to generate the Execution Profile]] <br/>
|
||||
[[Profiling|How to profile a system]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
[[Property:title|Profiler How To's]]
|
||||
[[Property:weight|2]]
|
||||
[[Property:uuid|f488bd8f-6d05-0487-a4c6-2e26a9a185ad]]
|
||||
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
[[Property:title|Profiler wizard guided tour]]
|
||||
[[Property:weight|1]]
|
||||
[[Property:uuid|e6166282-aa91-e4a9-9951-819f32d50b88]]
|
||||
Using the Profiler Wizard consists of activities in four "states", each of which is represented by a wizard dialog box:
|
||||
|
||||
# [[Select the Compilation mode|Select which version of your system you ran using the profiler: ''Workbench'' or ''Finalized'']] .
|
||||
# [[Reuse or Generate an Execution Profile|Select an existing ''Execution Profile'' or choose to generate a new ''Execution Profile'' from a ''Run-time information record'' (This step only applies when an ''Execution Profile'' has already been generated for this system)]]
|
||||
# [[Select a Run-time information record to generate the Execution Profile|Generate a new ''Execution Profile'' from a ''Run-time information record'' (This step only applies when generating a new ''Execution Profile'')]]
|
||||
# [[Select the information you need and formulate your query|Select the information you need and formulate your query.]]
|
||||
|
||||
Results of your query are visible in the [[Profile query window|Profile query window]].
|
||||
|
||||
|
||||
{{seealso|<br/>
|
||||
[[Profiling|How to profile a system]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
[[Property:title|Profile query window]]
|
||||
[[Property:weight|4]]
|
||||
[[Property:uuid|1158eeb3-ccf5-8f29-3551-4e511258fa80]]
|
||||
The profile query window displays the results of the query you have formulated in the [[Select the information you need and formulate your query|Final state]] of the Profiler wizard. It also lets you change the sub queries of the current query.
|
||||
|
||||
To add a new sub query to the current query, fill in the text field labeled '''Define new sub query''' (type in ''calls <20'' for example) and click the '''And''' or '''Or''' button. To display the results of the new query click on the '''Update''' button.
|
||||
|
||||
To remove an existing sub query, select it in the '''Active query''' list and click on the '''Inactivate >''' button.
|
||||
|
||||
To activate an existing sub query, select it in the '''Inactive query''' list and click on the '''< Activate''' button.
|
||||
|
||||
To change the operator affecting an existing sub query, select it in either the '''Active query''' or the '''Inactive query''' list and click on the '''Or''' or '''And''' button.
|
||||
|
||||
Click on the '''Save''' button to save the currently displayed results in a text file.
|
||||
|
||||
{{tip|To visualize the result in Microsoft Excel or any other spreadsheet, select the entire text (except the first three lines where the Execution Profile file is specified), copy it and then paste it into Excel. }}
|
||||
<br/>
|
||||
[[Image:profiler-query-window]] <br/>
|
||||
|
||||
{{seealso|<br/>
|
||||
[[Profiling|How to profile a system]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
[[Property:title|Reuse or Generate an Execution Profile]]
|
||||
[[Property:weight|1]]
|
||||
[[Property:uuid|caa8ac1d-b17d-6b5b-1b16-7420a8d4404c]]
|
||||
The second screen of the wizard lets you reuse a previously generated ''Execution Profile'' or generate a new ''Execution Profile'' from a ''Run-time information record''.
|
||||
|
||||
The profiler wizard has detected that one or more ''Execution Profiles'' have already been generated for this system in this compilation mode. If you have executed your system after the generation of the existing profile, select '''Generate a profile from Run-time information record''' to create a new ''Execution Profile'' for the newly produced ''Run-time information record''.
|
||||
|
||||
{{note|If you choose '''Generate a profile from Run-time information record''' the generated ''Execution Profile'' will be written into: <br/><br/>''<project_directory>/EIFGENa/target_name/W_CODE/profinfo.pfi'' <br/><br/>if you have selected '''Workbench mode''' in the first step, or into: <br/><br/>''<project_directory>/EIFGENs/target_name/F_CODE/profinfo.pfi'' <br/><br/>if you have selected '''Finalized mode'''. If a file with the same name already exists its content will be destroyed and replaced. }}
|
||||
<br/>
|
||||
|
||||
However, if you have not executed your system since the generation of the last ''Execution Profile'', there is no need to generate a new ''Execution Profile''. If you are in the latter case, select '''Use existing profile''' and choose the last ''Execution Profile'' you have generated.
|
||||
|
||||
{{tip|If you want to archive different ''Execution Profiles'' (to compare them for example), rename the ''profinfo.pfi'' file into a new name but keep the .pfi extension. The profiler wizard detects existing Execution Profiles by checking the file extensions. }}
|
||||
<br/>
|
||||
[[Image:profiler-wizard-second-state]] <br/>
|
||||
<br/>
|
||||
|
||||
Clicking '''Next''' will lead you to the [[Select a Run-time information record to generate the Execution Profile|Third state]] if you have selected '''Generate a profile from Run-time information record'''. On the other hand if you have selected '''Use existing profile''' you will go to the [[Select the information you need and formulate your query|Final state]] .
|
||||
<br/>
|
||||
|
||||
{{seealso|<br/>
|
||||
[[Profiling|How to profile a system]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,20 @@
|
||||
[[Property:title|Select the Compilation mode]]
|
||||
[[Property:weight|0]]
|
||||
[[Property:uuid|b43f018b-b924-234b-727f-8d80c1d18fb4]]
|
||||
The first screen of the wizard lets you specify the mode in which the profiled system was compiled.
|
||||
|
||||
If you have run a finalized system under the control of the profiler then select '''Finalized mode''' and click '''Next'''. On the contrary if you have executed the system in Workbench mode then select '''Workbench mode''' and click '''Next'''.
|
||||
|
||||
|
||||
[[Image:profiler-wizard-first-state]] <br/>
|
||||
<br/>
|
||||
|
||||
Clicking '''Next''' will lead you to the [[Reuse or Generate an Execution Profile|Second state]] or to the [[Select a Run-time information record to generate the Execution Profile|Third state]] depending on whether an ''Execution Profile'' has already been generated for this compilation mode or not. If no ''Execution Profile'' has been generated so far (which happens the first time you execute this wizard for a specified project in a given compilation mode) you will go to the [[Select a Run-time information record to generate the Execution Profile|Third state]] , otherwise you will go to the [[Reuse or Generate an Execution Profile|Second state]] .
|
||||
<br/>
|
||||
|
||||
{{seealso|<br/>
|
||||
[[Profiling|How to profile a system]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
[[Property:title|Select the information you need and formulate your query]]
|
||||
[[Property:weight|3]]
|
||||
[[Property:uuid|708f745d-11af-4d3d-e857-159dad4bdeec]]
|
||||
The final screen of the wizard lets you select the information you want to be displayed in the profile query window.
|
||||
|
||||
==Select the information you need==
|
||||
|
||||
Check or uncheck any of the check buttons in '''Output switches''' to select the columns you want to be displayed. Each switch turns on or off the corresponding column output. You should toggle columns on or off depending on what you would like to see in the result of the computation. Here are the explanations of each switch:
|
||||
* '''Feature name''': Display the name of the current feature.
|
||||
* '''Number of calls''': Display the number of times the current feature was called during the instrumented execution.
|
||||
* '''Function time''': Display the time spent in the current feature (not counting the time spent in features called by the current feature).
|
||||
* '''Descendant time''': Display the time spent in all features called during the execution of the current feature.
|
||||
* '''Total time''': Display the total time spent in the feature. This value is equal to ''Function time + Descendant time''.
|
||||
* '''Percentage''': Display the percentage of time spent in the current feature. This value is equal to ''Total time / Execution time''.
|
||||
|
||||
Check or uncheck any of the check buttons in the '''Language type''' to select the type of features you want to be displayed. If you select only one language, the query result will not contain any information about routines written in the other language. The default is Eiffel only.
|
||||
* Eiffel features: Display the features written in Eiffel.
|
||||
* C functions: Display the functions written in C.
|
||||
* Recursive functions: Display recursive functions.
|
||||
|
||||
==Formulate your query==
|
||||
|
||||
When running a query, you are able to type a complete query. After pressing the '''Next''' button, a new window will be displayed to show the result of the query. The total query can be either a single one or a set of sub-queries separated by one of the two operators 'or' or 'and'. <br/>
|
||||
<br/>
|
||||
Each sub-query must have the following syntax 'attribute operator value' where:
|
||||
* 'attribute' is one of:
|
||||
** feature name
|
||||
** calls
|
||||
** total
|
||||
** self
|
||||
** descendants
|
||||
** percentage
|
||||
|
||||
* 'operator' is one of: <, >, <=, >=, =, /=, in
|
||||
* 'value' is one of:
|
||||
** An integer (for calls)
|
||||
** A string (for feature name). The string may contain wild card characters: ?, standing for arbitrary characters, and *, standing for arbitrary sub-strings.
|
||||
** A real value (for other attributes)
|
||||
** An interval, of the form a-b for two values a and b.
|
||||
** max
|
||||
** min
|
||||
** avg
|
||||
|
||||
|
||||
<br/>
|
||||
[[Image:profiler-wizard-fourth-state]] <br/>
|
||||
<br/>
|
||||
|
||||
|
||||
Clicking '''Next''' will open the [[Profile query window|Profile query window]] and display the results of the formulated query.
|
||||
<br/>
|
||||
|
||||
{{seealso|<br/>
|
||||
[[Profiling|How to profile a system]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
[[Property:title|Select a Run-time information record to generate the Execution Profile]]
|
||||
[[Property:weight|2]]
|
||||
[[Property:uuid|c3f3e068-2313-ff14-2a33-8bf5297b9779]]
|
||||
The third screen of the wizard lets you generate an ''Execution Profile'' from a ''Run-time information record''. You should provide the ''Run-time information record'' produced by the profiler in the text field labeled '''Run-time information record'''. If the file provided by default is not the desired one change it by clicking on the '''Browse''' button or by directly entering it in the text field.
|
||||
|
||||
Then, in the combo box labeled '''Profiler used to produce the above record''', select the profiler that has been used to produce the ''Run-time information record'' you have entered. If the profiler used to execute the system does not appear in the combo box, you have to add it. See [[How to set up a Profiler Configuration File|How to set up a Profiler Configuration File]] for more details on how to do so.
|
||||
|
||||
|
||||
{{note|The Run-time information record must be located in the ''EIFGENs/target_name/W_code'' directory of your project. }}
|
||||
|
||||
<br/>
|
||||
[[Image:profiler-wizard-third-state]] <br/>
|
||||
<br/>
|
||||
|
||||
|
||||
Clicking '''Next''' will lead you to the [[Select the information you need and formulate your query|Final state]] if the provided ''Run-time information record'' is valid. If the ''Run-time information record'' is not valid or is not located in the ''EIFGENs/target_name/W_code'' directory of the project, you will go to the '''Run-time Information Record Error state''' as shown below.
|
||||
|
||||
|
||||
[[Image:profiler-wizard-rtir-error-state]] <br/>
|
||||
<br/>
|
||||
|
||||
{{seealso|<br/>
|
||||
[[Profiling|How to profile a system]] <br/>
|
||||
[[How to set up a Profiler Configuration File|How to set up a Profiler Configuration File]] }}
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user