Author:halw

Date:2008-10-07T22:18:20.000000Z


git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@71 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
halw
2008-10-07 22:18:20 +00:00
parent 74a519a844
commit 39a6dd51cb
16 changed files with 143 additions and 82 deletions

View File

@@ -2,8 +2,6 @@
[[Property:link_title|Appendix: Writing Documentation Filters with EFF, the Eiffel Filter Format]]
[[Property:weight|6]]
[[Property:uuid|0d17d433-3d4f-9575-49f7-d97eccb1a5b1]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
This appendix provides reference information, not needed in simple uses of EiffelStudio.
We saw in the [[8 PRODUCING AND EXPORTING DOCUMENTATION|section on documentation]] that you can output documentation about your system in many different formats. A number of predefined formats are available, from Postscript to Microsoft's Rich Text Format, FrameMaker, HTML with and without style sheets, TEX and others. There's nothing special about these formats: they just make their conventions known to EiffelStudio through a '''filter''' expressed in a simple notation called EFF, or Eiffel Filter Format. If you have a favorite format that you'd like EiffelStudio to use for producing documentation, you can define your own filter in EFF. Applications include:
@@ -50,7 +48,7 @@ which, thanks to the asterisk, will govern all construct specimens of the <code>
The following general syntactic constructs may appear as the left-hand side, <code> Construct </code>, of an entry:
<code>
'''Class_declaration
Class_declaration
Class_end
Class_header
Class_name
@@ -69,7 +67,8 @@ New_line
Obsolete_clause
Suffix
Symbol
Tab'''</code>
Tab
</code>
Most of these denote Eiffel constructs as they appear in the official language reference, the book <span> [http://www.eiffel.com/doc/ Eiffel: The Language] </span>. Since the Eiffel construct names <code> Feature </code>, <code> Invariant </code> and <code> Obsolete </code> are also keywords and EFF, like Eiffel, is case-insensitive, the EFF construct names use the suffix <code> _clause </code>, for example <code> Feature_clause </code>.

View File

@@ -2,8 +2,6 @@
[[Property:link_title|The Command-Line Compiler]]
[[Property:weight|4]]
[[Property:uuid|62bd8d62-a734-3ec0-9533-eaa096e7b81f]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
Along with compilation from within EiffelStudio, it is possible to start compilation from a command line (shell). This is useful in particular to recompile your system automatically as part of a script.
To use the command-line compiler -- <code> ec </code> for Eiffel Compilation -- execute

View File

@@ -2,13 +2,12 @@
[[Property:link_title|Compiling and Executing a System]]
[[Property:weight|-12]]
[[Property:uuid|58494be3-f29f-3a15-a27e-e635bdc71c53]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
EiffelStudio first comes up with a window and a dialog on top of it; the dialog looks like this (from here on the look-and-feel will be different on non-Windows platform, but the contents will be the same):
[[Image:index-2]]
As this is our first project we want to <code> Add Project. </code> We could also
* " <code> Create project </code>", which would let you select one among the common schemes -- basic application, graphical Windows application, graphical multi-platform application, Microsoft .NET application -- and set up everything for you.
* " <code lang="c"> Create project </code>", which would let you select one among the common schemes -- basic application, graphical Windows application, graphical multi-platform application, Microsoft .NET application -- and set up everything for you.
* " <code> Open project </code>", which would let you open a previously added project..
In future sessions you'll probably use the first option for a new project, as it takes care of generating everything for you, and the second option for an existing project.
@@ -21,6 +20,7 @@ Right now you first have to add the project, so click on <code>Add Project</code
remember that <code> $ISE_EIFFEL </code> stands for the location of the Eiffel installation, such as <code> C:\Eiffel50 </code> ; ECF files are normally marked by the <code> .ecf </code> file extension).
Use the File Explorer to go to the directory <code> $ISE_EIFFEL/examples/studio/tour/ </code> and select the appropriate file. You will then be back on the startup dialog.
[[Image:index-3]]
Click <code> Open </code> to confirm. This starts compilation of your project.
@@ -30,7 +30,9 @@ During Eiffel compilation, a progress bar displays the successive compilation st
{{note| ''On an IBM Thinkpad, Pentium III 850 MHz, 256 MB, running Windows 2000 Professional, Eiffel compilation takes about 9 seconds for the entire Guided Tour system including non-precompiled EiffelBase. '' }}
After Eiffel compilation completes you will see the message
<code> Eiffel Compilation Succeeded</code>
<code>
Eiffel Compilation Succeeded
</code>
At this stage your project is finished compiled and you can start using EiffelStudio.

View File

@@ -2,8 +2,6 @@
[[Property:link_title|Computing Project Metrics]]
[[Property:weight|0]]
[[Property:uuid|8d1a3556-d9a2-0ac8-4d54-458f18cb56ad]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
In earlier sections we saw how EiffelStudio provides extensive documentation on your systems. That information was qualitative. Project managers and developers will also be interested in <span>quantitative</span> information about their projects. You can get such information through the <code> Metrics </code> tool, which enables you to perform a number of operations, detailed over the next few pages:
* Apply predefined metrics -- number of classes, number of invariants, number of features, number of compilations so far and many others -- to components of a system at various levels including feature, class, cluster, entire system.
* Define new metrics, through mathematical formulae or boolean selection, and apply them to your project.

View File

@@ -2,8 +2,6 @@
[[Property:link_title|Copying the Example Files]]
[[Property:weight|-14]]
[[Property:uuid|bb8ff7d7-2e93-d150-339c-d9afb967bc98]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
{{note|If you are using Eiffel on a personal computer under Windows, you can work directly on the installation directory and don't need to make copies of files as per the present section. Skip directly to the next section, 3. Do read the present section and apply its instructions if you work under Unix, or may have to share the Eiffel installation with other users, do not have write permissions on the installation, or want to keep the installation unchanged.}}
If you are going to work on a copy, choose or create a directory of your own; let's call it <code> YOURDIR </code> for the rest of the discussion.

View File

@@ -2,8 +2,6 @@
[[Property:link_title|Debugging and Run-time Monitoring]]
[[Property:weight|-2]]
[[Property:uuid|a53f6a74-7145-35ab-ed5e-2905aeb88774]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
The next set of EiffelStudio capabilities enable you to control and monitor the execution of your systems. The obvious immediate application is to debugging; but the more general goal is to let you follow the execution of your systems, explore the object structures, and gain a better understanding of the software.
<div>
==A reminder about debugging in Eiffel==
@@ -20,17 +18,25 @@ The facilities to be described now are also useful when you find such an error,
To control the execution you will set breakpoints, indicating places where you want to interrupt the execution. You may set a breakpoint on an individual instruction of a routine, on the routine's precondition or postcondition, or on the routine as a whole, meaning its first operation (precondition or instruction).
A group of icons on the Project Toolbar help control breakpoints. They are known in EiffelStudio terminology as "''buttonholes''", meaning that they can serve both as buttons (you can click them to get some functions) and holes (you can pick-and-drop into them to get some other functions).
<div> [[Image:index-82]] [[general/guided_tour/studio/index-82.png|(link)]] </div>
[[Image:index-82]]
The labels correspond to the icons' use as buttons: enable all set breakpoints, disable them all, clear all, display information on current breakpoints. The difference between "disabling" and "removing" is that disabling turns off breakpoints until further notice but remembers them, so that you can later re-enable them, whereas "removing" clears them for good.
Target a Development Window to the class <code> TESTROOT </code> and pick-and-drop the name of the procedure <code> make </code> (the first routine, after the declaration of the two attributes <code> o1 </code> and <code> o2 </code>) to the <code> Enable all </code> icon, used here as a hole. This sets and enables a breakpoint on the routine. Click the button labeled <code> Show/Hide information about breakpoints </code> above to get the list of breakpoints, as shown in the next figure.
<div> [[Image:index-83]] [[general/guided_tour/studio/index-83.png|(link)]] </div>
[[Image:index-83]]
This shows that so far you have enabled only one breakpoint. For a finer degree of control, let's look at the feature's flat form. Pick-and-drop <code> make </code> to the Context Tool -- from the Context Tool itself, since its name appears there, or the Editing Tool); this sets the Context to the <code> Feature </code> Tab. Select the <code> Flat </code> view if that wasn't the last one used:
<div> [[Image:index-84]] [[general/guided_tour/studio/index-84.png|(link)]] </div>
[[Image:index-84]]
The small circles on the left side of the Flat form indicate breakpoint positions. Empty ones are not set; enabled breakpoints are marked by a circle filled with red. At the moment only one is enabled, corresponding to the first instruction of the routine since, as noted, setting a breakpoint on a routine as a whole means setting it on its first operation.
By (left) clicking on a breakpoint mark, you toggle it between enabled and not set. You can also right-click on a mark to get a menu of possibilities. Try enabling and unsetting a few of these marks; you might get something like this:
<div> [[Image:index-85]] [[general/guided_tour/studio/index-85.png|(link)]] </div>
[[Image:index-85]]
The breakpoint mark for the routine's third instruction, <code> create </code> <code> o2 </code>, is red but not filled; this means it is set but not enabled. You can obtain this by right-clicking on the mark and choosing <code> Disable breakpoint </code> on the menu that comes up. Any potential breakpoint will be in one of three states: not set; enabled; set but disabled.
You can see the list of enabled and disabled breakpoints by clicking the <code> Output </code> Tab, or the <code> Display info </code> button in the Project Toolbar.
@@ -40,13 +46,17 @@ For the continuation of this tour it doesn't matter which exact breakpoints of <
==Executing with breakpoints==
To execute, you will use the following Run buttons in the Project toolbar, or the corresponding entries in the <code> Debug </code> menu:
<div> [[Image:index-82]] [[general/guided_tour/studio/index-82.png|(link)]] </div>
[[Image:index-82]]
The buttons are shown here in full bloom, but at any times some of them will be grayed out. <code> Terminate </code> is only active when execution has started and not terminated; <code> Interrupt </code> is only active when the execution is active (not stopped at a breakpoint).
The <code> Debug </code> menu entries will also remind you of shortcuts: F10 for <code> Step-by-step </code>, F11 for <code> Step into routine </code>, Shift-F11 for <code> Step out of routine </code>, CTRL-F5 for <code> Run without breakpoints </code>, F5 for <code> Run with breakpoints </code>, CTRL-Shift-F5 for <code> Interrupt </code>, Shift-F5 for <code> Terminate </code>.
Start execution of the compiled system by clicking <code> Run with breakpoints </code>. The display automatically switches to accommodate supplementary tools providing debugging information. Execution stops on the breakpoint that you have enabled on the first instruction of procedure <code> make </code>:
<div> [[Image:index-87]] [[general/guided_tour/studio/index-87.png|(link)]] </div>
[[Image:index-87]]
The pane at the bottom left indicates that execution has stopped in <code> make </code>. The Context shows the flat form of that routine, with a new icon to indicate the stop point which execution has reached. At the bottom right is a new tool, the '''Object Editor''', which shows the content of current object and (later) related objects. At the moment you can see that:
* The current object is an instance of class <code> TESTROOT </code>.
* The class (as you could also see from its text in a Development Window) has two attributes <code> o1 </code> and <code> o2 </code>, for which the corresponding fields in the current object are both void; this is as expected since you haven't yet executed the two creation instructions <code> create </code> <code> { </code> <code> HEIR </code> <code> } </code> <code> o1 </code> and <code> create </code> <code> o2 </code>, as they come after the breakpoint.
@@ -57,7 +67,9 @@ The execution-time objects that you may display in an Object Editor are our late
==Monitoring progress==
Click twice on <code> Step-by-step </code> (or press the function key F10 twice). Monitor, in the flat form of <code> make </code>, the marker that shows execution progress; note that the marker always points to the <span>next</span> operation to be executed. After the two steps, the Context and Object Tools look like this:
<div> [[Image:index-88]] [[general/guided_tour/studio/index-88.png|(link)]] </div>
[[Image:index-88]]
The last instruction that you executed is <code> create </code> <code> { </code> <code> HEIR </code> <code> } </code> <code> o1 </code>, meaning create an object and attach it to <code> o1 </code>, but instead of using the declared type <code> PARENT </code> of <code> o1 </code> use its proper descendant <code> HEIR </code>. As a result, the entry for <code> o1 </code> in the Object Tool no longer shows <code> Void </code> but an object of type <code> HEIR </code>. Note that all objects are identified by their addresses in hexadecimal; such an address is by itself meaningless, but enables you to see quickly whether two object references are attached to the same object. The addresses you see as you run the Guided Tour will -- except for some unlikely coincidence -- be different from the ones appearing here.
Note that since the garbage collector compacts memory and hence may move objects around, the address of a given object is not guaranteed to remain the same throughout a session.

View File

@@ -2,8 +2,6 @@
[[Property:link_title|Executing a System Within and Without EiffelStudio]]
[[Property:weight|5]]
[[Property:uuid|8256398e-d1a9-0471-664a-3225c7dfb306]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
To complete this study of the compilation process let's see a few more properties of how you can <span>execute</span> an Eiffel system, both in EiffelStudio and as a compiled system that you deliver to its users, who may need to run it without EiffelStudio.
<div>
==Arguments==

View File

@@ -2,9 +2,7 @@
[[Property:link_title|Graphics-based Design]]
[[Property:weight|1]]
[[Property:uuid|78239225-67a7-8718-857d-f2c8fb70ef18]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
So far the project modifications that we have made used the text editor in the Editing Tool. We used graphics, but as a way to reflect system structures, not to build them ( [[6 STARTING TO BROWSE|See "A Peek at Diagrams" in STARTING TO BROWSE]] , and subsequent discussions).
So far the project modifications that we have made used the text editor in the Editing Tool. We used graphics, but as a way to reflect system structures, not to build them ( [[6 STARTING TO BROWSE|See "A Peek at Diagrams" in Starting to Browse]] , and subsequent discussions).
In line with the principles of seamlessness and reversibility recalled at the beginning of this Tour, EiffelStudio's text-diagram interaction is bi-directional. When you make a textual modification, the next incremental recompilation will update the diagram; but you can also work directly from the diagram, and the text will be generated or updated after each graphical operation.
@@ -15,13 +13,19 @@ Many people like to use the graphical mechanisms at the beginning of a project,
We are going to play with the root cluster. Make sure the Cluster tree and the Context Tool are up. Also make sure that the Context tool is in Isolate rather than Linked behavior; you can see this by going to the <code> Edit menu </code>: if there is an entry <code> Unlink context tool </code>, select it; otherwise (the corresponding entry reads "Link context tool") don't do anything, you're fine. (You can also use the Link/Isolate button added earlier to the Browsing toolbar for this very purpose.)
The earlier diagrams were "class views", giving a picture of the world around a class. For a change, we are now going to start working with '''cluster views''', showing the content of a cluster. Select the Diagram Tab in the Context Tool; from the Cluster Tree, pick-and-drop <code> root_cluster </code> to the Context Tool. This displays the graphical view of the root cluster in the Context Tool:
<div> [[Image:index-113]] [[general/guided_tour/studio/index-113.png|(link)]] </div></div><div>
[[Image:index-113]]
==Hiding a class==
First we decide that we don't want to be bothered with class <code> INVALID </code>. We could delete it altogether from the system by pick-and-drop its bubble to the Delete hole. This is not what we want, but try this now to see the confirmation request:
<div> [[Image:index-114]] [[general/guided_tour/studio/index-114.png|(link)]] </div>
[[Image:index-114]]
Make sure to answer <code> Cancel </code> to that confirmation request (you want to keep the class even though it wouldn't be a catastrophe to lose it) and instead pick-and-drop the <code> INVALID </code> bubble into the <code> Hide </code> hole. This time there is no confirmation request, since the operation is reversible -- it just affects what's displayed in the cluster view -- and the class is removed from the display:
<div> [[Image:index-115]] [[general/guided_tour/studio/index-115.png|(link)]] </div>
[[Image:index-115]]
You can try undoing this change, then redoing it.
You can also click <code> History </code> which, during the rest of the session, will display the list of executed operations, and let you undo or redo many operations at once by clicking the oldest to be kept or the youngest to be redone.
@@ -35,31 +39,45 @@ We are now going to add a class graphically to our system. This means you don't
The useful button here is <code> New class </code>.
This button is a pebble, meant to be dropped into the diagram. Drop it somewhere above the bubble for <code> TESTROOT </code>; the exact place doesn't matter, but it has to be within the area of the cluster <code> root_cluster </code> because we'll want our class to part of it. You're asked to name the class:
<div> [[Image:index-118]] [[general/guided_tour/studio/index-118.png|(link)]] </div>
[[Image:index-118]]
Overwrite the default name being proposed, <code> NEW_CLASS </code>, by the name <code> HEIR2 </code>, as we are going to create a new heir of <code> PARENT </code>. Don't touch the file name in the second field; as you type the class name EiffelStudio automatically sets the file name to <code> heir2.e </code>, so you would only set it if you wanted to override the default convention for names of class files.
The new class is now in the diagram, part of <code> root_cluster </code>:
<div> [[Image:index-119]] [[general/guided_tour/studio/index-119.png|(link)]] </div>
[[Image:index-119]]
Using conventional drag-and-drop (not pick-and-drop), move the class bubbles for <code> HEIR2 </code>, <code> TESTROOT </code> and <code> PARENT </code> so that the display looks approximately like the following. The double circle around <code> TESTROOT </code> is the BON convention to identify a system's root class.
<div> [[Image:index-120]] [[general/guided_tour/studio/index-120.png|(link)]] </div></div><div>
[[Image:index-120]]
==Adding an inheritance link==
Now we are going to make <code> HEIR2 </code> an heir of <code> PARENT </code>. To create inter-class relations, you will select a relation by clicking one of the "Create link" buttons, then use pick-and-drop from the source class to the target class. There are three possibilities:
<div> [[Image:index-121]] [[general/guided_tour/studio/index-121.png|(link)]] </div></div>
[[Image:index-121]]
Click the button marked <code> heir </code> above. Now pick-and-drop from the <code> HEIR2 </code> bubble to the <code> PARENT </code> bubble. (Now you see why conventional drag-and-drop is used to move bubbles: pick-and-drop on the diagram serves to add links between classes).
<div> [[Image:index-122]] [[general/guided_tour/studio/index-122.png|(link)]] </div>
[[Image:index-122]]
To convince yourself that the new class has been made an heir of <code> PARENT </code>, in its text and not just in the diagram, pick-and-drop <code> HEIR2 </code> bubble to the Editing Tool at the top to see its text. (You could also control-right-click to the bubble to bring up a new Development Window on this class.) All the code has been generated from your graphical operations: creating the class produced a class template with all the standard style and clauses, and the reparenting operation made <code> HEIR2 </code> inherit from <code> PARENT </code>.
In a moment we'll use this Editing Tool to see how, conversely, EiffelStudio will automatically reflect in the diagram a change made to the text. For the moment go back to the Development Window.
In the Cluster Tree in the top-left pane, you will notice that the name of <code> HEIR2 </code> appears grayed out; so does the name of <code> INVALID </code>:
<div> [[Image:index-124]] [[general/guided_tour/studio/index-124.png|(link)]] </div>
[[Image:index-124]]
This is EiffelStudio's way of telling us that these two classes, listed because they appear in one of the system's clusters, are not actually in the system because the root class doesn't reference them directly or indirectly.
<div>
==Adding a client link==
Let's add <code> HEIR2 </code> to the system by making <code> TESTROOT </code> a client of this class. Click the button that selects <code> Client </code> as the next relation to make links. Pick-and-drop from the <code> TESTROOT </code> bubble to the <code> HEIR2 </code> bubble. This asks you what kind of client link you want:
<div> [[Image:index-125]] [[general/guided_tour/studio/index-125.png|(link)]] </div>
[[Image:index-125]]
This technique gives you many option and in fact is a convenient way to build your classes, whether at the analysis, design or implementation level. Here, fill the fields as follows. For the top choice, keep the default, <code> Attribute </code>; we'll give class <code> TESTROOT </code> an attribute of type <code> HEIR2 </code>. For its feature category, keep the choice currently displayed, <code> Access </code>. For its name, replace the default, <code> new_feature </code>, by the name <code> my_heir </code>. In the <code> invariant </code> clause, choose
<code>
my_heir_not_void: my_heir /= Void
@@ -68,7 +86,9 @@ This technique gives you many option and in fact is a convenient way to build yo
from the list to specify the invariant property that this attribute should never be void. Finally, to see how EiffelStudio can generate the full accompaniment to an attribute, check the box <code> Generate set procedure </code>. Click <code> OK </code>.
The diagram -- shown below after a slight move of the bubble for <code> TESTROOT </code> for more readability -- shows that <code> TESTROOT </code> is now a client of <code> HEIR2 </code>. By default it only displays inheritance links; now it has switched automatically to a mode that shows client links as well, so that we also see that <code> TESTROOT </code> is (and always was) a client of <code> PARENT </code> through attributes including <code> o2 </code>.
<div> [[Image:index-126]] [[general/guided_tour/studio/index-126.png|(link)]] </div>
[[Image:index-126]]
Now pick-and-drop the class bubble <code> TESTROOT </code> to the top Editing Tool to see how the class has been modified. The situation here is different from what we saw earlier with <code> HEIR2 </code>, which had been generated from scratch by the diagram. Here <code> TESTROOT </code> existed before, in text form; so the diagram mechanisms have had to preserve the existing feature and feature clauses, and add the elements corresponding to what you have specified through the diagram mechanisms. Here is the beginning of class <code> TESTROOT </code> in its updated form.
Note how EiffelStudio has generated both the attribute and the associated "set" procedure, <code> set_my_heir </code>, complete with a precondition -- deduced from the invariant you have specified, <code> Void /= my_heir </code> -- and a postcondition. The unlabeled Feature clause of the existing class has been kept; the new features have been entered into clauses labeled <code> Access </code> and <code> Element change </code>, observing the Eiffel standard for common feature clauses in libraries.
@@ -89,7 +109,9 @@ without further ado, as this is just a simple check.
{{note|If you are concerned about the correctness of the class, you may wish to update its creation procedure <code> make </code> to add a creation instruction <code> create </code> <code> my_heir </code>. Without it the just added invariant would be violated upon creation. }}
Nothing happens yet to the diagram. This is normal: EiffelStudio doesn't update the diagram every time you type some text (which, for one thing, might be syntactically incorrect, or invalid). You need to recompile first. Click the <code> Compile </code> button. Then on the Context Tool click <code> Diagram </code>; the new relation appears:
<div> [[Image:index-128]] [[general/guided_tour/studio/index-128.png|(link)]] </div>
[[Image:index-128]]
If the label <code> other </code> of that relation doesn't appear in the exact place shown here, try moving it using conventional drag-and-drop. You can only move such a link label within a small area on either side of the link.
</div><div>
==Creating a cluster==
@@ -97,11 +119,15 @@ If the label <code> other </code> of that relation doesn't appear in the exact p
Earlier on, we saw how to create a class from the EiffelStudio diagram, letting EiffelStudio take care of creating and initializing the file. Similarly, you can create a new cluster graphically, and let EiffelStudio create the corresponding directory.
To create a cluster, you can go through <code> Project </code> <code> --> </code> <code> Project settings </code>, or you can click the little Cluster Creation button at the top of the Cluster Tree. Click this button. The resulting dialog asks you for the cluster name, and the existing cluster (non-precompiled) of which you want to make it a subcluster, here leaving only one choice:
<div> [[Image:index-130]] [[general/guided_tour/studio/index-130.png|(link)]] </div>
[[Image:index-130]]
Instead of the <code> NEW_CLUSTER </code> default name, type <code> my_cluster </code>; select the only possible supercluster, <code> root_cluster </code>, and click <code> Create </code> at the bottom of the dialog.
Recompile the project and bring up the cluster diagram again. It shows the subcluster:
<div> [[Image:index-131]] [[general/guided_tour/studio/index-131.png|(link)]] </div>
[[Image:index-131]]
Make sure that the display looks approximately like the above; you may have to resize either or both clusters (drag a corner), and move the small cluster (drag-and-drop).
</div><div>
==Moving a class to a different cluster==
@@ -109,7 +135,9 @@ Make sure that the display looks approximately like the above; you may have to r
Among the many operations you can do graphically is to move a class from one cluster to another. Pick-and-drop the <code> HEIR2 </code> class bubble to the rounded rectangle for <code> MY_CLUSTER </code>.
This graphical manipulation has caused a structural change: class <code> HEIR2 </code> is now part of <code> MY_CLUSTER </code>. Check this by expanding the Cluster Tree on the left:
<div> [[Image:index-132]] [[general/guided_tour/studio/index-132.png|(link)]] </div>
[[Image:index-132]]
If you like, you can also look into the project directory -- using the Windows Explorer, or <code> cd </code> and <code> ls </code> on Unix/Linux -- and check that it now has a subdirectory <code> my_cluster </code> with a file <code> heir2 </code> <span>. </span> <code> e </code> containing the text of class <code> HEIR2 </code>.
Clearly, it's much more convenient to use EiffelStudio for such manipulations than to move files around manually.
@@ -135,9 +163,13 @@ You may remember that when we generated HTML documentation, the dialog asked you
==Class diagrams, cluster diagrams==
Whereas our initial encounter with diagrams at the beginning of this Tour used class diagrams, in the present discussion we have used cluster diagrams. Both are interesting. To obtain a class diagram, you will target a Context Tool to a class, and select the <code> Diagram </code> Tab. By default, this shows the parents of the class. Do this now for <code> TESTROOT </code>:
<div> [[Image:index-138]] [[general/guided_tour/studio/index-138.png|(link)]] </div>
[[Image:index-138]]
It's for class diagrams that the <code> Relation depth </code> button is most interesting. It will let you select the exact depth that you wish displayed for every relation:
<div> [[Image:index-139]] [[general/guided_tour/studio/index-139.png|(link)]] </div>
[[Image:index-139]]
This will conclude our review of the Diagram facilities of EiffelStudio, although you'll surely discover some further riches by yourself and through the rest of the documentation. We hope the complete seamlessness between text and pictures will enable you to increase the effectiveness of your analysis work, or your design work, or your programming -- whatever level of system development you need to tackle.
</div>

View File

@@ -2,8 +2,6 @@
[[Property:link_title|Handling Syntax and Validity Errors]]
[[Property:weight|-3]]
[[Property:uuid|c2be8123-b793-f8ce-e082-d4fdacc6bbe6]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
So far we have tried to make sure that everything went smoothly. But in actual software development you may encounter error situations, and it is useful to know what can happen then.
<div>
==Levels of language description==
@@ -23,7 +21,9 @@ Syntax and validity errors will be detected by the compilation process. For sema
==A syntax error==
To see what happens for a syntax error, replace the keyword <code> is </code> by <code> ist </code> in the first line of routine <code> display </code> of class <code> PARENT </code> (click the position immediately after the <code> s </code> and type a <code> t </code>.). Save the file by clicking the Save button or using CTRL- <code> S </code> and then compile the system.
<div> [[Image:index-75]] [[general/guided_tour/studio/index-75.png|(link)]] </div>
[[Image:index-75]]
To correct the error, just bring the mouse back to its location, remove the spurious <code> t </code>, and click Save again; also click Compile to make sure that the project is recompiled up-to-date.
You may wonder why the syntax error messages are not a little more verbose than just <code> Syntax error </code>. The reason is merely that Eiffel's syntax, being simple and regular, does not require sophisticated error messages; syntax errors usually result from trivial oversights. If you make a syntax error and the reason is not immediately clear, check the syntax summary in the appendix of <span> [http://www.eiffel.com/doc/ Eiffel: The Language] </span>.
@@ -39,23 +39,35 @@ To see this mechanism at work, let us introduce a validity error. There is in fa
-- inv: INVALID;</code>
If uncommented, this is a declaration of a feature of type <code> INVALID </code>. A class called <code> INVALID </code> indeed exists in file <code> invalid.e </code> of the root cluster, but it contains a validity error. To see what it is, remove the initial double-dash <code> -- </code> in the above line from class <code> TESTROOT </code> so that it is not a comment any more.
<div> [[Image:index-76]] [[general/guided_tour/studio/index-76.png|(link)]] </div>
Click <code> Save </code>, then <code> Compile </code>. Compilation starts but after a few degrees it stops with an error message that appears in the bottom Context Tool (you may have to do some resizing to see it in its entirety):
<div> [[Image:index-77]] [[general/guided_tour/studio/index-77.png|(link)]] </div>
[[Image:index-76]]
Click <code> Save </code>, then <code> Compile </code>. Compilation starts but after a few degrees it stops with an error message that appears in the bottom Context Tool (you may have to do some resizing to see it in its entirety):
[[Image:index-77]]
As the error message indicates, you have (shame on you) violated the validity rule <code> VUAR </code>, which requires the number and types of actual arguments in a routine call to match the number and types of formal arguments declared in the routine.
One of the interesting properties of the error message is that everything in color is '''clickable''' : class name, feature name, but also the error code. This means that you can start a Pick-and-Drop on any of these elements to find out more.
For example, to see the exact context of the error, pick-and-drop the name of the affected feature, <code> display </code> -- appearing on the fifth non-blank line, after <code> Feature: </code> -- and pick-and-drop it to the top Text window. (As you remember this means: right-click on it and release; move the mouse to the text window, without clicking any button; right-click again. During the move the cursor shows a cross, the symbol for features.) This displays the erroneous feature:
<div> [[Image:index-78]] [[general/guided_tour/studio/index-78.png|(link)]] </div>
[[Image:index-78]]
Note on this display a special property of Pick-and-Drop when its source is a feature name appearing in a validity error message: the instruction that causes the error is highlighted.
In the error message in the Context Tool, the error code itself, <code> VUAR </code>, is also clickable. Assuming the message was not sufficient to understand the error, you can use it to start a Pick-and-Drop. Do this now, by picking that code and starting to move the mouse, but not dropping yet:
<div> [[Image:index-79]] [[general/guided_tour/studio/index-79.png|(link)]] </div>
[[Image:index-79]]
The icon shape for such information elements is a question mark <code> ? </code>. If it is not on a droppable target, as in the bottom Context Tool, that icon will be crossed. In principle the place to drop is the Explanation hole in the Project toolbar, the only one that remains highlighted during the Move step of Pick-and-Drop:
<div> [[Image:index-80]] [[general/guided_tour/studio/index-80.png|(link)]] </div>
[[Image:index-80]]
As is often the case when dropping into a specific hole, you don't need to shoot straight; dropping the pebble anywhere in the Editing Tool has the same effect as dropping it into the Explanation hole:
<div> [[Image:index-81]] [[general/guided_tour/studio/index-81.png|(link)]] </div>
[[Image:index-81]]
The result is to display the complete text of the violated rule, straight from the pages of <span> [http://www.eiffel.com/doc/ Eiffel: The Language] </span>.
The rule has several clauses, numbered. Since the error message showed the error code as <code> VUAR(1) </code>, the violated clause is the first; this convention of showing the clause number in parentheses applies to all multi-clause validity constraints.

View File

@@ -2,8 +2,6 @@
[[Property:link_title|How EiffelStudio Compiles]]
[[Property:weight|3]]
[[Property:uuid|6fc86303-8afe-78af-6ca7-2853e8bfcbc3]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
So far we have relied on the compiling capabilities of EiffelStudio without exploring them in any detail. We must now understand the principles behind EiffelStudio's compiling strategy, in particular how it reconciles fast turnaround, efficient generated code, and strong typing.
<div>
==Compilation is automatic==
@@ -157,7 +155,9 @@ Only two operations, noted above, <span>require</span> freezing: the addition of
Except for the addition of external routines or agents, freezing is never strictly necessary. It is indeed possible to use melting throughout a development, never requesting a freeze after the first compilation. But as the melted-to-frozen ratio grows, you may detect a certain degradation in the performance of the system (determined by how big a share of your system is melted, not how many times you melt it). After a while, then, you may want to refreeze. Like melting, freezing is incremental: only those parts of a system that have been logically changed will be recompiled; as with melting, the determination of what needs to be recompiled is entirely performed by the environment, without any manual intervention on the developer's part.
The principal difference is that freezing takes longer than melting. Because of this you are requested to confirm the first time you freeze. Freeze the example system by choosing the menu entry <code> Project </code> <code> --> </code> <code> Freeze </code>. You get the following dialog:
<div> [[Image:index-142]] [[general/guided_tour/studio/index-142.png|(link)]] </div>
[[Image:index-142]]
Note the <code> No </code> option: by default, freezing will start a C compilation, but you can stop after C generation if you wish. This is useful for example if you want to generate a C package for cross-development, C-compiling the result on a different platform.
Click <code> Yes </code> to confirm freeze and C-compilation. Once the Eiffel compilation is complete, a message in the Development Window ( <code> C compilation launched in background </code>) tells you when that C-compilation has started. C-compilation does not block EiffelStudio: at this point you can continue working with the environment. Any messages from C compiler will appear:

View File

@@ -2,8 +2,6 @@
[[Property:link_title|A Look at the Project Directory]]
[[Property:weight|-11]]
[[Property:uuid|d82eae3f-fe0d-3e27-008e-61afd05f8cb0]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
Before we proceed with the facilities of the environment, let's take a look at the way EiffelStudio organizes project files.
With EiffelStudio, you build projects. Most projects yield an executable system, although you can also build a project just to define a library for use by such systems.
@@ -13,7 +11,9 @@ Every session is relative to a project; you can start a new project from within
Every project has a '''project directory''' which will contain the files generated and managed by EiffelStudio. The project directory may also host some of the source files containing your Eiffel classes, the ECF (eiffel configurationl file), and external software written in other languages, but that is not required; the source files and ecf may reside anywhere. Some users, in fact, like to put nothing else than the EiffelStudio-generated files in the project directory; this separates user-managed and system-managed files, and can facilitate configuration management, backups and porting.
In this simple Tour, things have been set up so that all the files of interest, source texts as well as generated ones, will appear in the project directory <code> YOURDIR </code> (either <code> $ISE_EIFFEL\examples\studio\tour </code> or the copy that you have made). Go to that project directory using the Windows explorer or a <code> cd </code> command, and look at its contents (using <code> ls </code> on Unix/Linux):
<div> [[Image:index-7]] [[general/guided_tour/studio/index-7.png|(link)]] </div>
[[Image:index-7]]
The contents of this <code> YOURDIR </code> directory include the following:
* First you see a number of files with the extension <span>.</span> <code> e </code>, for "Eiffel": <code> heir.e </code>, <code> invalid.e </code> and others. These are the Eiffel source files, each containing one class. The recommended convention is to store a class of name <code> CLASS_NAME </code> into a file of name <code> class_name </code> <code> .e </code>, where <code> class_name </code> is the lower-case version of <code> CLASS_NAME </code> ; here, file <code> heir.e </code> contains the class <code> HEIR </code> and so on. As you may remember, Eiffel is case-insensitive, but the standard convention for class names is to write them in all upper case. Calling the file <code> class_name </code> <code> .e </code> is only a recommendation, not an obligation; but you <span>are</span> required to store one class per file. This keeps things simple and facilitates project and configuration management.
* You also notice a file with an <code> ecf </code> extension. This is the configuration file that specifies this project. As you remember, the ECF file for this example was available as part of the delivery; we used it to compile the project. In most practical cases, however, you won't need to build an ECF; if you use the " <code> Create project </code>" option of EiffelStudio, EiffelStudio will build the ECF for you; if you change the Project Settings during a session, EiffelStudio will update the ECF. ECF are written in a xml notation.

View File

@@ -2,8 +2,6 @@
[[Property:link_title|Producing and Exporting Documentation]]
[[Property:weight|-7]]
[[Property:uuid|ca43a3c2-9e1a-a69f-81cf-55d0b12294ea]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
Software development is, most of the time, cooperative work. You must tell the rest of the team what you're up to, and find out what they can offer you. Bring in distributed development -- increasingly common these days, with some people working at headquarters, others at home, others traveling, an offshore team half a world away <span>...</span> -- and the problem becomes even more critical.
EiffelStudio provides unique facilities to make such distributed development possible in a safe, effective, harmonious way. Some of the key criteria are:
@@ -21,7 +19,9 @@ EiffelStudio's documentation generation satisfies all these requirements.
Let's see how documentation works by starting to generate it for our Guided Tour system -- which really means for EiffelBase, since that's what it mostly consists of. The HTML result is available as part of the present documentation (we'll tell you where in just a minute), so you don't have to regenerate it unless you want to. Indeed we'll show you when to click <code> Cancel </code> if you are happy with the pre-generated version. But let's get started anyway to understand the principles and possibilities.
Click the following menu entry, used to generate documentation:
<code>Project --> Generate documentation...</code>
<code lang="text">
Project --> Generate documentation...
</code>
This is the next-to-last entry in the <code> Project </code> menu. The last one, by the way, <code> XMI Export </code> <span>...</span>, is directly relevant too: it will make it possible to export information in the standard XML representation for UML, for consumption by third-party products such as Rational Rose. But for the moment we choose the <code> Documentation </code> entry to start the Eiffel Documentation Wizard.

View File

@@ -2,8 +2,6 @@
[[Property:link_title|Recompiling and Editing]]
[[Property:weight|-4]]
[[Property:uuid|6574a573-48b9-6088-aa98-53d7119d7c5c]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
So far we have relied on existing class texts. Fascinating as it may be to explore excellent software such as EiffelBase, you probably want to write your own too (with the help of the reusable components in the Eiffel libraries). EiffelStudio provides a built-in editor -- as well as the ability to use some other editor if you prefer -- and sophisticated compilation mechanisms.
==Recompiling==
@@ -15,7 +13,9 @@ When we started, we compiled the example system. Let's recompile it, just to see
We don't want to touch EiffelBase classes (and in fact can't, since it is used in precompiled form), so let's focus on classes of our small root cluster. In the Cluster tree on the left, expand cluster <code> root_cluster </code> and click class <code> PARENT </code> to retarget the Development Window to it.
Make sure that the Editing Tool is big enough to display the text of the class:
<div> [[Image:index-66]] [[general/guided_tour/studio/index-66.png|(link)]] </div>
[[Image:index-66]]
The Editing Tool hosts a text editor which you can use to change the class text. Here the routine <code> display </code> starts by outputting a simple message; let's precede it by another line of display to check that we affected the outcome. We'll want to add the following two lines just after the <code> do </code>, before the first two instructions of the routine:
<code>
io.put_string ("This is some more added text")
@@ -23,7 +23,9 @@ The Editing Tool hosts a text editor which you can use to change the class text.
</code>
They are very similar to the current first two lines of the routine, so you can just use copy-paste: select the first two lines with the mouse, copy them using CTRL- <code> C </code> (or <code> Copy </code> from the <code> Edit </code> menu), then paste them just after the <code> do </code> using CTRL- <code> V </code> (or <code> Paste </code> from the <code> Edit </code> menu). Add or remove tabs to align with the rest of the routine, and change the string to <code> THIS IS SOME MORE ADDED TEXT </code> so that the result will look like what's shown on the next figure. This is all there is to change; the second line remains untouched. Please check the result and be careful not to introduce any mistakes; in the next section we'll study how EiffelStudio will report syntax and other errors, but right now we want to see what happens when everything is right!
<div> [[Image:index-67]] [[general/guided_tour/studio/index-67.png|(link)]] </div>
[[Image:index-67]]
Now save your changes; you may indifferently use CTRL- <code> S </code>, the <code> Save </code> entry from the <code> Edit </code> menu, or the Save button highlighted on the figure. (If you forget to save, the next compilation will tell you so, and ask you if from now on you want all non-saved class edits to be saved automatically.)
</div><div>
==Recompiling and executing after a change==
@@ -71,7 +73,9 @@ To start a search, make sure the Search Tool is active by clicking the Search bu
{{note|If you press CTRL - <code>F</code> in a tool you will get a quick search bar that quickly allows to search for something in the current text.}}
The Search Tool presents a number of self-explanatory options:
<div> [[Image:index-69]] [[general/guided_tour/studio/index-69.png|(link)]] </div>
[[Image:index-69]]
You can enter a term to replace your search term in the <code> Replace with </code> box.
Having filled the two fields, you can elect to replace the last found occurrence, or all occurrences at once.
@@ -85,11 +89,15 @@ Particularly interesting are the editor's '''automatic completion''' facilities.
The EiffelStudio Editor knows about Eiffel syntax and will recognize syntactic elements as you type them. It will color them according to standard conventions: basic elements in black, keywords in blue, comments in dark red. You can change these conventions through Preferences.
If you start typing a control structure through its opening keyword, such as <code> if </code>, or <code> from </code> for a loop, the editor will automatically display the structure of the whole construct. Here for example is the result if you type the <code> from </code> followed by Return/Enter at the beginning of our example routine:
<div> [[Image:index-71]] [[general/guided_tour/studio/index-71.png|(link)]] </div>
[[Image:index-71]]
This has produced the structure of an Eiffel loop: <code> from </code> <span>...</span> <code> until </code> <span>...</span> <code> loop </code> <span>...</span> <code> end </code>. You can then fill in the blanks with the appropriate expression and instructions. The generated lines start with the appropriate number of Tab characters to support the standard Eiffel indenting conventions. If you want a more compact style, follow the <code> from </code> with a space rather than Return. Typing <code> if </code> followed by Return or a space will similarly produce the outline of a conditional instruction.
To start a routine, type the routine name followed by the keyword <code> is </code> and a Return. The editor generates the basic structure of a routine text:
<div> [[Image:index-72]] [[general/guided_tour/studio/index-72.png|(link)]] </div>
[[Image:index-72]]
This prompts you to enter the header comment (no self-respecting Eiffel developer even <span>thinks</span> of writing a feature without a header comment). At the end of the header comment, type Return if the header comment continues, otherwise type a down arrow to continue with the indentation for the beginning of the routine, with one of the keywords <code> require </code>, <code> local </code>, <code> do </code>, <code> external </code>, <code> once </code>. Once you type <code> do </code>, followed by a Return or space, the completion mechanism will insert the appropriate <code> end </code>, but other than that it doesn't try to produce an entire routine structure because there are too many syntactical choices (precondition or not, postcondition or not, locals or not etc.).
Also interesting is '''feature completion''', using the '''CTRL-SPACE''' key. It works at two levels:
@@ -99,7 +107,9 @@ Also interesting is '''feature completion''', using the '''CTRL-SPACE''' key. It
In both cases, if more than one completion is possible, you will get a menu of the possibilities. You can scroll through it with the up and down arrow keys, or the mouse, and select one through Enter or double-click. You can also or give up through the Escape key.
Here for example is the menu you will see in the body of our example routine if you type <code> io </code> <span>. </span> followed by CTRL-SPACE, where <code> io </code> is the feature, coming from class <code> ANY </code>, that provides access to standard input and output facilities:
<div> [[Image:index-73]] [[general/guided_tour/studio/index-73.png|(link)]] </div>
[[Image:index-73]]
The following properties enhance the convenience of the completion mechanisms:
* If only one completion is possible, no menu appears; the completion is selected.
* If the cursor is just after the name of a query (which you have fully typed, or obtained through completion), typing CTRL-SPACE once more will produce a period, as if you had typed it.

View File

@@ -2,8 +2,6 @@
[[Property:link_title|Starting To Browse]]
[[Property:weight|-10]]
[[Property:uuid|cb6c2e52-d238-9b55-0b78-ab3af9568550]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
It was important to take a look at how EiffelStudio stores your project, but unless your idea of fun is to poke around directories to look at compiler-generated files that's not really the exciting part yet. Among the most innovative aspects of EiffelStudio is a unique set of facilities to <span>browse</span> through a software system.
==Browsing style==
@@ -17,7 +15,9 @@ Browsing -- traversing the structure -- is particularly important in object-orie
==A Development Window==
Let's see how this works. First, take a look at the EiffelStudio window:
<div> [[Image:index-8]] [[general/guided_tour/studio/index-8.png|(link)]] </div>
<div> [[Image:index-8]] </div>
{{note| ''If some parts are too small, just resize the window to arrive at something like what's on the figure. When it first comes up, EiffelStudio initially uses a fairly small window, because it's designed to run on a 800x600 display, although of course a bigger display is recommended. But as soon as you have resized it, EiffelStudio will come up, in the next session, with the size you've set.'' }}
You can see five panes, marked on the figure: <code> Features </code>, <code> Class </code>, <code> Properties </code>, <code> Clusters </code>, <code> Context </code>. There will be others, such as <code> Search </code>, and you can remove any of them, except <code> Class </code>, at any time to make room for the others.

View File

@@ -2,14 +2,14 @@
[[Property:link_title|Starting EiffelStudio and Opening a Project]]
[[Property:weight|-13]]
[[Property:uuid|676cf329-5640-69c4-d10b-b56fcd3f2ff9]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
In the rest of this Tour <code> YOURDIR </code> denotes the directory where the example resides (the original, <code> $ISE_EIFFEL/examples/studio/tour </code>, or a copy). Launching will use the operating system's mechanism for starting a program, so we look separately at Windows and at Unix/OpenVMS.
==Launching EiffelStudio under Window==
On Windows, you can launch EiffelStudio from the Start Menu under
<code> Programs --> EiffelStudio Version --> EiffelStudio</code>
<code lang="c">
Programs --> EiffelStudio Version --> EiffelStudio
</code>
where <span>Version</span> is the version number, e.g. 6.0. Alternatively, you can double-click the icon that the installation procedure will have added to your desktop (if you have selected that option during installation).
@@ -18,7 +18,9 @@ If this is the first time you are using EiffelStudio, you may get a dialog askin
==Launching EiffelStudio under Unix or OpenVMS==
To launch EiffelStudio on Unix or OpenVMS, change directory to <code> YOURDIR </code> and, from the command line, type
<code> estudio</code>
<code>
estudio
</code>
In general you can start EiffelStudio from any directory, but to make things simple for this Tour '''please make sure''' indeed to execute the <code> estudio </code> command from <code> YOURDIR </code>. (This will allow us to use relative rather than absolute names for some of the files involved.)

View File

@@ -2,8 +2,6 @@
[[Property:link_title|Viewing Classes]]
[[Property:weight|-9]]
[[Property:uuid|78136af1-5d7a-f3d2-9619-17f4c0541f1e]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
We haven't even looked at a class text yet, but it's important anyway to see how EiffelStudio provides you with numerous, complementary <span>views</span> of your software. The Context Tool is the primary place to look for such views.
We'll need just one Development Window for the moment, the one that was targeted to <code> LIST </code>. You can get rid of the others by closing their windows (through the top right cross mark on Windows and the equivalent in other window managers), or through <code> File </code> <code> --> </code> <code> Close </code> -- but don't select "Exit" which would take you out of EiffelStudio altogether!
@@ -82,7 +80,9 @@ The only two classes that <code> LIST </code> needs for its own algorithms are b
==Feature information in the Class View==
Let's resist the natural urge to go see now what the classes <code> INTEGER_32 </code> and <code> BOOLEAN </code> look like, and instead continue our survey of views. The remaining views will all display information about the '''features''' of the class. The first of them, <code> Attributes </code>, lists the attributes. It's not very interesting for <code> LIST </code>, a deferred class with only one attribute -- you can check this for yourself by clicking the <code> Attributes </code> button -- so let's look at the next one. Click the <code> Routines </code> button now to display information about the routines of class <code> LIST </code> :
<div> [[Image:index-36]] [[general/guided_tour/studio/index-36.png|(link)]] </div>
[[Image:index-36]]
The sections of this display group routines according to the ancestors of <code> LIST </code> -- including <code> LIST </code> itself -- that first introduced them; for example (second and third sections) <code> extendible </code> originally comes from <code> COLLECTION </code> and <code> extend </code> from <code> BAG </code>. Much of the benefit of this display comes from its support for browsing: all the colored elements, representing classes and features, will be "clickable" hyperlinks.
The remaining Class View buttons all display information in the same format. Each selects a specific subset of the target class's features. The last two selected attributes and routines. You can now try any of the others by clicking the corresponding button: