==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).
-
[[Image:index-82]] [[general/guided_tour/studio/index-82.png|(link)]]
+
+[[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
TESTROOT and pick-and-drop the name of the procedure
make (the first routine, after the declaration of the two attributes
o1 and
o2 ) to the
Enable all icon, used here as a hole. This sets and enables a breakpoint on the routine. Click the button labeled
Show/Hide information about breakpoints above to get the list of breakpoints, as shown in the next figure.
-
[[Image:index-83]] [[general/guided_tour/studio/index-83.png|(link)]]
+
+[[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
make to the Context Tool -- from the Context Tool itself, since its name appears there, or the Editing Tool); this sets the Context to the
Feature Tab. Select the
Flat view if that wasn't the last one used:
-
[[Image:index-84]] [[general/guided_tour/studio/index-84.png|(link)]]
+
+[[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:
-
[[Image:index-85]] [[general/guided_tour/studio/index-85.png|(link)]]
+
+[[Image:index-85]]
+
The breakpoint mark for the routine's third instruction,
create o2 , 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
Disable breakpoint 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
Output Tab, or the
Display info 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
Debug menu:
-
[[Image:index-82]] [[general/guided_tour/studio/index-82.png|(link)]]
+
+[[Image:index-82]]
+
The buttons are shown here in full bloom, but at any times some of them will be grayed out.
Terminate is only active when execution has started and not terminated;
Interrupt is only active when the execution is active (not stopped at a breakpoint).
The
Debug menu entries will also remind you of shortcuts: F10 for
Step-by-step , F11 for
Step into routine , Shift-F11 for
Step out of routine , CTRL-F5 for
Run without breakpoints , F5 for
Run with breakpoints , CTRL-Shift-F5 for
Interrupt , Shift-F5 for
Terminate .
Start execution of the compiled system by clicking
Run with breakpoints . 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
make :
-
[[Image:index-87]] [[general/guided_tour/studio/index-87.png|(link)]]
+
+[[Image:index-87]]
+
The pane at the bottom left indicates that execution has stopped in
make . 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
TESTROOT .
* The class (as you could also see from its text in a Development Window) has two attributes
o1 and
o2 , 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
create { HEIR } o1 and
create o2 , 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
Step-by-step (or press the function key F10 twice). Monitor, in the flat form of
make , the marker that shows execution progress; note that the marker always points to the
next operation to be executed. After the two steps, the Context and Object Tools look like this:
-
[[Image:index-88]] [[general/guided_tour/studio/index-88.png|(link)]]
+
+[[Image:index-88]]
+
The last instruction that you executed is
create { HEIR } o1 , meaning create an object and attach it to
o1 , but instead of using the declared type
PARENT of
o1 use its proper descendant
HEIR . As a result, the entry for
o1 in the Object Tool no longer shows
Void but an object of type
HEIR . 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.
diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/executing-system-within-and-without-eiffelstudio.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/executing-system-within-and-without-eiffelstudio.wiki
index 90193876..d61a9275 100644
--- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/executing-system-within-and-without-eiffelstudio.wiki
+++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/executing-system-within-and-without-eiffelstudio.wiki
@@ -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
execute 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.
==Arguments==
diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/graphics-based-design.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/graphics-based-design.wiki
index af9c4d75..a23fa698 100644
--- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/graphics-based-design.wiki
+++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/graphics-based-design.wiki
@@ -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
Edit menu : if there is an entry
Unlink context tool , 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
root_cluster to the Context Tool. This displays the graphical view of the root cluster in the Context Tool:
-
[[Image:index-113]] [[general/guided_tour/studio/index-113.png|(link)]]
+
+[[Image:index-113]]
+
==Hiding a class==
First we decide that we don't want to be bothered with class
INVALID . 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:
-
[[Image:index-114]] [[general/guided_tour/studio/index-114.png|(link)]]
+
+[[Image:index-114]]
+
Make sure to answer
Cancel 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
INVALID bubble into the
Hide 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:
-
[[Image:index-115]] [[general/guided_tour/studio/index-115.png|(link)]]
+
+[[Image:index-115]]
+
You can try undoing this change, then redoing it.
You can also click
History 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
New class .
This button is a pebble, meant to be dropped into the diagram. Drop it somewhere above the bubble for
TESTROOT ; the exact place doesn't matter, but it has to be within the area of the cluster
root_cluster because we'll want our class to part of it. You're asked to name the class:
-
[[Image:index-118]] [[general/guided_tour/studio/index-118.png|(link)]]
+
+[[Image:index-118]]
+
Overwrite the default name being proposed,
NEW_CLASS , by the name
HEIR2 , as we are going to create a new heir of
PARENT . Don't touch the file name in the second field; as you type the class name EiffelStudio automatically sets the file name to
heir2.e , 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
root_cluster :
-
[[Image:index-119]] [[general/guided_tour/studio/index-119.png|(link)]]
+
+[[Image:index-119]]
+
Using conventional drag-and-drop (not pick-and-drop), move the class bubbles for
HEIR2 ,
TESTROOT and
PARENT so that the display looks approximately like the following. The double circle around
TESTROOT is the BON convention to identify a system's root class.
-
[[Image:index-120]] [[general/guided_tour/studio/index-120.png|(link)]]
+
+[[Image:index-120]]
+
==Adding an inheritance link==
Now we are going to make
HEIR2 an heir of
PARENT . 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:
-
[[Image:index-121]] [[general/guided_tour/studio/index-121.png|(link)]]
+
+[[Image:index-121]]
+
Click the button marked
heir above. Now pick-and-drop from the
HEIR2 bubble to the
PARENT 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).
-
[[Image:index-122]] [[general/guided_tour/studio/index-122.png|(link)]]
+
+[[Image:index-122]]
+
To convince yourself that the new class has been made an heir of
PARENT , in its text and not just in the diagram, pick-and-drop
HEIR2 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
HEIR2 inherit from
PARENT .
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
HEIR2 appears grayed out; so does the name of
INVALID :
-
[[Image:index-124]] [[general/guided_tour/studio/index-124.png|(link)]]
+
+[[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.
==Adding a client link==
Let's add
HEIR2 to the system by making
TESTROOT a client of this class. Click the button that selects
Client as the next relation to make links. Pick-and-drop from the
TESTROOT bubble to the
HEIR2 bubble. This asks you what kind of client link you want:
-
[[Image:index-125]] [[general/guided_tour/studio/index-125.png|(link)]]
+
+[[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,
Attribute ; we'll give class
TESTROOT an attribute of type
HEIR2 . For its feature category, keep the choice currently displayed,
Access . For its name, replace the default,
new_feature , by the name
my_heir . In the
invariant clause, choose
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 Generate set procedure . Click OK .
The diagram -- shown below after a slight move of the bubble for TESTROOT for more readability -- shows that TESTROOT is now a client of HEIR2 . 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 TESTROOT is (and always was) a client of PARENT through attributes including o2 .
- [[Image:index-126]] [[general/guided_tour/studio/index-126.png|(link)]]
+
+[[Image:index-126]]
+
Now pick-and-drop the class bubble TESTROOT to the top Editing Tool to see how the class has been modified. The situation here is different from what we saw earlier with HEIR2 , which had been generated from scratch by the diagram. Here TESTROOT 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 TESTROOT in its updated form.
Note how EiffelStudio has generated both the attribute and the associated "set" procedure, set_my_heir , complete with a precondition -- deduced from the invariant you have specified, Void /= my_heir -- and a postcondition. The unlabeled Feature clause of the existing class has been kept; the new features have been entered into clauses labeled Access and Element change , 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 make to add a creation instruction create my_heir . 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 Compile button. Then on the Context Tool click Diagram ; the new relation appears:
- [[Image:index-128]] [[general/guided_tour/studio/index-128.png|(link)]]
+
+[[Image:index-128]]
+
If the label other 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.
==Creating a cluster==
@@ -97,11 +119,15 @@ If the label
other 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
Project --> Project settings , 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:
-
[[Image:index-130]] [[general/guided_tour/studio/index-130.png|(link)]]
+
+[[Image:index-130]]
+
Instead of the
NEW_CLUSTER default name, type
my_cluster ; select the only possible supercluster,
root_cluster , and click
Create at the bottom of the dialog.
Recompile the project and bring up the cluster diagram again. It shows the subcluster:
-
[[Image:index-131]] [[general/guided_tour/studio/index-131.png|(link)]]
+
+[[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).
==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
HEIR2 class bubble to the rounded rectangle for
MY_CLUSTER .
This graphical manipulation has caused a structural change: class
HEIR2 is now part of
MY_CLUSTER . Check this by expanding the Cluster Tree on the left:
-
[[Image:index-132]] [[general/guided_tour/studio/index-132.png|(link)]]
+
+[[Image:index-132]]
+
If you like, you can also look into the project directory -- using the Windows Explorer, or
cd and
ls on Unix/Linux -- and check that it now has a subdirectory
my_cluster with a file
heir2 . e containing the text of class
HEIR2 .
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
Diagram Tab. By default, this shows the parents of the class. Do this now for
TESTROOT :
-
[[Image:index-138]] [[general/guided_tour/studio/index-138.png|(link)]]
+
+[[Image:index-138]]
+
It's for class diagrams that the
Relation depth button is most interesting. It will let you select the exact depth that you wish displayed for every relation:
-
[[Image:index-139]] [[general/guided_tour/studio/index-139.png|(link)]]
+
+[[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.
diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/handling-syntax-and-validity-errors.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/handling-syntax-and-validity-errors.wiki
index 771dcf8f..035d5752 100644
--- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/handling-syntax-and-validity-errors.wiki
+++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/handling-syntax-and-validity-errors.wiki
@@ -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.
==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
is by
ist in the first line of routine
display of class
PARENT (click the position immediately after the
s and type a
t .). Save the file by clicking the Save button or using CTRL-
S and then compile the system.
-
[[Image:index-75]] [[general/guided_tour/studio/index-75.png|(link)]]
+
+[[Image:index-75]]
+
To correct the error, just bring the mouse back to its location, remove the spurious
t , 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
Syntax error . 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
[http://www.eiffel.com/doc/ Eiffel: The Language] .
@@ -39,23 +39,35 @@ To see this mechanism at work, let us introduce a validity error. There is in fa
-- inv: INVALID;
If uncommented, this is a declaration of a feature of type
INVALID . A class called
INVALID indeed exists in file
invalid.e of the root cluster, but it contains a validity error. To see what it is, remove the initial double-dash
-- in the above line from class
TESTROOT so that it is not a comment any more.
-
[[Image:index-76]] [[general/guided_tour/studio/index-76.png|(link)]]
-Click
Save , then
Compile . 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]] [[general/guided_tour/studio/index-77.png|(link)]]
+
+[[Image:index-76]]
+
+Click
Save , then
Compile . 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
VUAR , 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,
display -- appearing on the fifth non-blank line, after
Feature: -- 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:
-
[[Image:index-78]] [[general/guided_tour/studio/index-78.png|(link)]]
+
+[[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,
VUAR , 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:
-
[[Image:index-79]] [[general/guided_tour/studio/index-79.png|(link)]]
+
+[[Image:index-79]]
+
The icon shape for such information elements is a question mark
? . 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:
-
[[Image:index-80]] [[general/guided_tour/studio/index-80.png|(link)]]
+
+[[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:
-
[[Image:index-81]] [[general/guided_tour/studio/index-81.png|(link)]]
+
+[[Image:index-81]]
+
The result is to display the complete text of the violated rule, straight from the pages of
[http://www.eiffel.com/doc/ Eiffel: The Language] .
The rule has several clauses, numbered. Since the error message showed the error code as
VUAR(1) , the violated clause is the first; this convention of showing the clause number in parentheses applies to all multi-clause validity constraints.
diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/how-eiffelstudio-compiles.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/how-eiffelstudio-compiles.wiki
index 990b79d6..6bfcda9b 100644
--- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/how-eiffelstudio-compiles.wiki
+++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/how-eiffelstudio-compiles.wiki
@@ -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.
==Compilation is automatic==
@@ -157,7 +155,9 @@ Only two operations, noted above,
require 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
Project --> Freeze . You get the following dialog:
-
[[Image:index-142]] [[general/guided_tour/studio/index-142.png|(link)]]
+
+[[Image:index-142]]
+
Note the
No 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
Yes to confirm freeze and C-compilation. Once the Eiffel compilation is complete, a message in the Development Window (
C compilation launched in background ) 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:
diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/look-project-directory.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/look-project-directory.wiki
index c982b1ee..bd5f3a0e 100644
--- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/look-project-directory.wiki
+++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/look-project-directory.wiki
@@ -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
YOURDIR (either
$ISE_EIFFEL\examples\studio\tour or the copy that you have made). Go to that project directory using the Windows explorer or a
cd command, and look at its contents (using
ls on Unix/Linux):
-
[[Image:index-7]] [[general/guided_tour/studio/index-7.png|(link)]]
+
+[[Image:index-7]]
+
The contents of this
YOURDIR directory include the following:
* First you see a number of files with the extension
. e , for "Eiffel":
heir.e ,
invalid.e and others. These are the Eiffel source files, each containing one class. The recommended convention is to store a class of name
CLASS_NAME into a file of name
class_name .e , where
class_name is the lower-case version of
CLASS_NAME ; here, file
heir.e contains the class
HEIR 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
class_name .e is only a recommendation, not an obligation; but you
are required to store one class per file. This keeps things simple and facilitates project and configuration management.
* You also notice a file with an
ecf 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 "
Create project " 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.
diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/producing-and-exporting-documentation.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/producing-and-exporting-documentation.wiki
index 337bd0ca..9755dd9f 100644
--- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/producing-and-exporting-documentation.wiki
+++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/producing-and-exporting-documentation.wiki
@@ -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
... -- 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
Cancel 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:
-
Project --> Generate documentation...
+
+ Project --> Generate documentation...
+
This is the next-to-last entry in the
Project menu. The last one, by the way,
XMI Export ..., 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
Documentation entry to start the Eiffel Documentation Wizard.
diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/recompiling-and-editing.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/recompiling-and-editing.wiki
index 110414b3..c077e069 100644
--- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/recompiling-and-editing.wiki
+++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/recompiling-and-editing.wiki
@@ -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
root_cluster and click class
PARENT to retarget the Development Window to it.
Make sure that the Editing Tool is big enough to display the text of the class:
-
[[Image:index-66]] [[general/guided_tour/studio/index-66.png|(link)]]
+
+[[Image:index-66]]
+
The Editing Tool hosts a text editor which you can use to change the class text. Here the routine
display 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
do , before the first two instructions of the routine:
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.
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-
C (or
Copy from the
Edit menu), then paste them just after the
do using CTRL-
V (or
Paste from the
Edit menu). Add or remove tabs to align with the rest of the routine, and change the string to
THIS IS SOME MORE ADDED TEXT 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!
-
[[Image:index-67]] [[general/guided_tour/studio/index-67.png|(link)]]
+
+[[Image:index-67]]
+
Now save your changes; you may indifferently use CTRL-
S , the
Save entry from the
Edit 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.)
==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 -
F 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:
-
[[Image:index-69]] [[general/guided_tour/studio/index-69.png|(link)]]
+
+[[Image:index-69]]
+
You can enter a term to replace your search term in the
Replace with 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
if , or
from for a loop, the editor will automatically display the structure of the whole construct. Here for example is the result if you type the
from followed by Return/Enter at the beginning of our example routine:
-
[[Image:index-71]] [[general/guided_tour/studio/index-71.png|(link)]]
+
+[[Image:index-71]]
+
This has produced the structure of an Eiffel loop:
from ... until ... loop ... end . 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
from with a space rather than Return. Typing
if 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
is and a Return. The editor generates the basic structure of a routine text:
-
[[Image:index-72]] [[general/guided_tour/studio/index-72.png|(link)]]
+
+[[Image:index-72]]
+
This prompts you to enter the header comment (no self-respecting Eiffel developer even
thinks 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
require ,
local ,
do ,
external ,
once . Once you type
do , followed by a Return or space, the completion mechanism will insert the appropriate
end , 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
io . followed by CTRL-SPACE, where
io is the feature, coming from class
ANY , that provides access to standard input and output facilities:
-
[[Image:index-73]] [[general/guided_tour/studio/index-73.png|(link)]]
+
+[[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.
diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-browse.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-browse.wiki
index 284ad41b..6d098a2e 100644
--- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-browse.wiki
+++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-browse.wiki
@@ -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
browse 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:
-
[[Image:index-8]] [[general/guided_tour/studio/index-8.png|(link)]]
+
+
[[Image:index-8]]
+
{{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:
Features ,
Class ,
Properties ,
Clusters ,
Context . There will be others, such as
Search , and you can remove any of them, except
Class , at any time to make room for the others.
diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-eiffelstudio-and-opening-project.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-eiffelstudio-and-opening-project.wiki
index d8351cba..8f5ef895 100644
--- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-eiffelstudio-and-opening-project.wiki
+++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-eiffelstudio-and-opening-project.wiki
@@ -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
YOURDIR denotes the directory where the example resides (the original,
$ISE_EIFFEL/examples/studio/tour , 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
-
Programs --> EiffelStudio Version --> EiffelStudio
+
+ Programs --> EiffelStudio Version --> EiffelStudio
+
where
Version 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
YOURDIR and, from the command line, type
-
estudio
+
+ estudio
+
In general you can start EiffelStudio from any directory, but to make things simple for this Tour '''please make sure''' indeed to execute the
estudio command from
YOURDIR . (This will allow us to use relative rather than absolute names for some of the files involved.)
diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/viewing-classes.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/viewing-classes.wiki
index c8b9b9fd..5e84de0e 100644
--- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/viewing-classes.wiki
+++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/viewing-classes.wiki
@@ -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
views 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
LIST . 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
File --> Close -- but don't select "Exit" which would take you out of EiffelStudio altogether!
@@ -82,7 +80,9 @@ The only two classes that
LIST 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
INTEGER_32 and
BOOLEAN 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,
Attributes , lists the attributes. It's not very interesting for
LIST , a deferred class with only one attribute -- you can check this for yourself by clicking the
Attributes button -- so let's look at the next one. Click the
Routines button now to display information about the routines of class
LIST :
-
[[Image:index-36]] [[general/guided_tour/studio/index-36.png|(link)]]
+
+[[Image:index-36]]
+
The sections of this display group routines according to the ancestors of
LIST -- including
LIST itself -- that first introduced them; for example (second and third sections)
extendible originally comes from
COLLECTION and
extend from
BAG . 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: