mirrors/eiffel-org
1
0
Fork 0
mirror of https://github.com/EiffelSoftware/eiffel-org.git synced 2026-04-05 09:39:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Author:admin

Browse Source 
Date:2008-09-17T13:53:28.000000Z


git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@3 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
jfiat
2008-09-17 13:53:28 +00:00
parent 4fee9356ea
commit 2ee31ab9c7
763 changed files with 36576 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
documentation/current/eiffelstudio/eiffelstudio-guided-tour/compiling-and-executing-system.wiki Normal file
View File

@@ -0,0 +1,52 @@
[[Property:title|4 COMPILING AND EXECUTING A SYSTEM]]
[[Property:link_title|Compiling and Executing a System]]
[[Property:weight|-12]]
[[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]] [[general/guided_tour/studio/index-2.png|(link)]]
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> 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.
Right now you first have to add the project, so click on <code>Add Project</code>. This brings up a File Explorer inviting you to select an ECF file. The file you want is
<code>
$ISE_EIFFEL\examples\studio\tour\simple.ecf
</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]] [[general/guided_tour/studio/index-3.png|(link)]]
Click <code> Open </code> to confirm. This starts compilation of your project.
During Eiffel compilation, a progress bar displays the successive compilation steps, or "degrees". The bulk of our little project is the EiffelBase library, which the EiffelStudio installation procedure has precompiled; so just now there's only a few extra classes to compile, and the process is almost instantaneous on a state-of-the-art computer. Even if you had to compile the EiffelBase classes, EiffelStudio compilation is so fast that you would hardly have the time to read the "degree" messages; you can see them later in compilations of bigger classes and systems.
{{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>
At this stage your project is finished compiled and you can start using EiffelStudio.
Congratulations! You have successfully compiled your first Eiffel project. More precisely it's been both "melted". Strange terminology, you may think; in a little while we'll see why these compilation steps are called that way.
==Executing the system==
The system doesn't do anything exciting, but let's execute it anyway. Find the execution icon ("Run with breakpoints") at the top of the EiffelStudio window.
It would be OK too to use the neighboring icon to the left, "Run without breakpoints", since we haven't set any breakpoints. Click either icon to execute the system.
This little application doesn't use graphics or anything fancy but simply creates some objects and displays some information. Output done using the default Eiffel I/O (from the EiffelBase classes <code> ANY </code> and <code> STANDARD_FILES </code> ) goes to a console. On Unix/Linux and VMS it's the window from which you started EiffelStudio. On Windows it's by default a new console window that comes up when and if the system does its first output operation, and stays up:
[[Image:index-6]] [[general/guided_tour/studio/index-6.png|(link)]]
The message " <code> Press Return to finish the execution </code>" would not appear if you executed the system from outside of EiffelStudio, for example from a command line. Its purpose within EiffelStudio is clear: to let you see the console output; without it, the console would go away at the end of execution. (None of this applies to Unix/Linux/VMS since there is no new console window to get rid of.)
If before closing the console window you look at the main EiffelStudio window (by moving away the console window) you will notice that it looks different from before, since it now shows the fields useful in monitoring execution and debugging. But we'll look at this later. For the moment just dismiss the console by following the advice to " <code> Press Return </code>": hit the Return or Enter key.
[[2 COPYING THE EXAMPLE FILES|<< Previous]] [[5 A LOOK AT THE PROJECT DIRECTORY|Next >>]]

29
documentation/current/eiffelstudio/eiffelstudio-guided-tour/copying-example-files.wiki Normal file
View File

@@ -0,0 +1,29 @@
[[Property:title|2 COPYING THE EXAMPLE FILES]]
[[Property:link_title|Copying the Example Files]]
[[Property:weight|-14]]
[[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.
To copy all the files of the example to <code> YOURDIR </code>:
* On Windows, open a Windows Explorer, go to <code> $ISE_EIFFEL\examples\studio\tour </code>, select all the files in that directory, and drag-and-drop them to <code> YOURDIR </code>.
* On Unix execute the shell command
<code> cp $ISE_EIFFEL/examples/studio/tour/* YOURDIR</code>
* On VMS execute the command
<code> copy $ISE_EIFFEL:[examples.studio.tour]*.* YOURDIR</code>
Once you have compiled the example under EiffelStudio, relying on the precompiled EiffelBase library (the default), and without optimization, the contents of <code> YOURDIR </code> will take up less than one megabyte, including information on diagrams and metrics.
The final executable generated through " ''finalization''" (optimized compilation) will take only about 300 kilobytes.
Without precompiled EiffelBase you would need about 3.5 megabytes, plus about 25 megabytes of generated C code and auxiliary files. The executable in that case will take up about 250 kilobytes.
[[1 OVERVIEW AND PREREQUISITES|<< Previous]] [[3 STARTING EIFFELSTUDIO AND OPENING A PROJECT|Next >>]]

190
documentation/current/eiffelstudio/eiffelstudio-guided-tour/how-eiffelstudio-compiles.wiki Normal file
View File

@@ -0,0 +1,190 @@
[[Property:title|16 HOW EIFFELSTUDIO COMPILES]]
[[Property:link_title|How EiffelStudio Compiles]]
[[Property:weight|3]]
[[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==
Any speed issue aside, the most important property of the compilation process is that it is entirely automatic.
You've seen it from the beginning of this Tour: all the information the compiler has -- obtained from a configuration file, as here, or generated automatically by the other options -- is the name of the root class and the list of directories holding Eiffel clusters. In fact it only needs these directories for non-precompiled clusters; here, since we are using precompiled EiffelBase, the only directory we are required to specify is the one containing the root cluster, denoted simply as " <span>.</span> " (current directory) since, to simplify things, we've started EiffelStudio from the Tour's own root cluster directory.
The compiler takes care of the rest, in particular of finding all the classes that must be compiled.
There is never any need, when compiling Eiffel systems, to supply "Make files", "include files", or other manual descriptions of inter-module dependencies.
</div><div>
==Compilation modes==
EiffelStudio offers several forms of compilation, which you can see in the entries of the <code> Compile </code> menu (don't trigger any of them right now) as well as keyboard shortcuts and, in some cases, buttons:
* '''Melt''': quick incremental recompilation, doesn't optimize code for changed parts.
* '''Freeze''': incremental recompilation, not as fast as Melt, but generates more efficient code for changed parts.
* '''Finalize''': recompile entire system, generating highly optimized code.
* '''Precompile''' (available both in the <code> Project </code> menu and through <code> Tools </code> <code> --> </code> <code> Precompilation wizard </code>), to process an entire library, on which many systems can then rely without having to compile it.
You'll quickly learn to use each of these modes to suit your needs.
</div><div>
==Criteria==
EiffelStudio's '''Melting Ice Technology''' reconciles the following goals:
* ''Security and efficiency of the generated code'': compiling techniques for the strongly typed Eiffel language ensure that compilers can catch many errors before it is too late, and generate more efficient code. The "validity constraints" of the language, whose violations are caught as compilation errors, are particularly useful here, playing the role of enforceable design rules.
* ''Quick turnaround '': you should experience an almost immediate transition from the time you write or (more commonly) modify software to the time you can execute it.
* ''C code generation'': for portability, it is useful to take advantage of C in its proper role, that of a portable assembly language. C's closeness to machine concepts -- one of the very properties making it less suitable for human programming except in the case of short routines to access low-level mechanisms --, its almost universal availability, and its good level of standardization, make it an excellent target language for a code generator. This also enables the environment to benefit from the often extensive optimizations performed by good C compilers, and facilitates interfacing new software with the large body of existing C-based systems, tools and libraries. As the final output of Eiffel compilation, you can obtain a complete C package that you can either C-compile on the same machine or port to other platforms, making EiffelStudio a tool of choice for '''cross-platform development''': develop on one platform, deploy on one or more others.
</div><div>
==The Melting Ice Principle==
The idea of the melting ice is based on the observation that, for the practicing software developer, the crucial day-to-day compilation problem is not how to process an entire system but how best to process a '''changed system''', of which an earlier state had previously been processed.
The change may be big or small; the system may be big or small. ("Small system" here means up to a few tens of thousands of lines.) This gives four possible cases, of which only one is really critical:
{|
|-
|
| '''Small System'''
| '''Large System'''
|-
| Small Change
|
| xxx
|-
| Big Change
|
|
|}
If the system is small, as in both of the left column entries, speed of recompilation with a good compiler will be acceptable.
In the bottom-right box, the developers have spent days or weeks changing many classes in a large system, so they will not resent having to wait a little to see the results of the recompilation, as long as the time remains reasonable. In EiffelStudio this corresponds, as we'll see shortly, to <span>finalization</span>, which is in fact fairly fast anyway, but not as fast as the incremental modes.
In the day-to-day, minute-by-minute practice of building and modifying software, the case that recurs by far the most often -- and can cause most frustration -- is the one marked xxx: you change only a small share of a big system. Then the result should come quickly enough. More precisely:
{{note|'''Melting Ice Principle '''<br/>
The time to re-process a system after a change should be a function of the logical size of the change, not of the size of the system. }}
''The "logical size" of a change may be different from its physical size because a small physical change in a class may have consequences in many others. Imagine for example that you add a feature to class '' <code> ANY </code>'', although this is an extreme case and won't normally happen. Since every class is a descendant of '' <code> ANY </code>'', the logical change may affect the entire system.''
''In practice, however, most small physical changes will also be small logical changes and will only cause minimal recompilation. In particular, EiffelStudio will detect that a change does not affect the interface of a class -- for example if it's only a change to non-exported features -- avoiding the need to re-process its clients.''
Processing such incremental changes, in time proportional to the logical size of the changes, is known in EiffelStudio as '''melting'''. The reason for this terminology is the metaphor illustrated on the following figure. Think of a compiled system as a block of ice; it may have taken some time to "freeze" -- compile. Now you start working on it again; the changes are like melted drops of water, dripping from the ice as a result of the heat generated by your work.
<div> [[Image:index-140]] </div>
The Melting Ice Technology ensures that incremental compilation will only process the "melted" part, usually small, leaving alone the "frozen" part, which may be large. This is crucial to the incrementality of the mechanism.
The roles of the four compilation modes follow from this analysis:
* '''Melting''' is the fastest mode: it processes the melted part without affecting the frozen part. With EiffelStudio, the melted elements will be <span>interpreted</span> while the rest is compiled.
* '''Freezing''' is the process of putting back the melted parts into the "freezer": bringing them to the same compiled state as the parts that have not been modified.
* '''Finalizing''' is the non-incremental process of producing a stand-alone C package and the resulting executable, extensively optimized, from the current system.
* '''Precompiling''' is the process of compiling an entire set of reusable classes, once and for all, so that it can be shared by many systems and many users without duplicating the code or compiling it again for each project.
</div><div>
==Properties of the compilation modes==
The following table summarizes the differences between the four compilation modes:
{|
|-
|
| '''Regenerate C Code?'''
| '''Incremental?'''
| '''Compilation result shared between projects?'''
|-
| '''Melt'''
| No
| Yes (fast)
| No
|-
| '''Freeze'''
| Yes
| Yes (but requires C compilation of changes and linking)
| No
|-
| '''Finalize'''
| Yes
| No
| No
|-
| '''Precompile'''
| Yes
| No
| Yes
|}
During the production and modification of your software, you will usually alternate between melting and freezing, since both of these modes are incremental. Most of the time, you will simply '''melt''', since melting satisfies the Melting Ice Principle: the time to get back to a working system is very short -- proportional to the size of the changes. Note in particular that the unit of melting is the smallest possible one: each feature of a class -- attribute or routine -- may be melted separately.
The main difference between melting and '''freezing''' is that freezing implies re-generating C code for the changed elements, and hence relinking the system as well. In contrast, when you melt changes, you do not change any C code: it remains frozen.
As a consequence, melting can only process changes to Eiffel code. If you add new external code (in C, C++ or other languages whose modules will require linking), you must freeze. This is also true if you add new Eiffel agents. If you ask for a Melt in such cases, the operation will trigger a freeze anyway. More generally, the <code> Compile </code> button, which you have used a number of times to recompile the system in this Tour, triggers a Melt by default, and a Freeze when it has to.
EiffelStudio knows how to hide the differences and present you with a uniform view of the frozen parts (the C code) and the melted parts. Here indeed is the full view of the picture that was previously given in part:
<div> [[Image:index-141]] </div>
When you examine a component of the system -- to edit a class, produce a view such as Contract or Flat Contract, enable a breakpoint on a routine, run the system, inspect a run-time object -- EiffelStudio automatically knows where to look for the corresponding information: melted or frozen part. If one of your actions requires melting or freezing more elements, EiffelStudio will also handle this automatically.
As suggested by the lower red arrow, successive melting operations "pour water into the bowl", corresponding to the elements that you have changed since the last freeze. Freezing, represented by the top red arrow, updates the C code so that it integrates all the latest changes, emptying the bowl in the process.
Because the difference between melted and frozen code is largely invisible to users of the environment, the term '''workbench code''' will cover both kinds; workbench code is code resulting from a succession of freezing and melting operations. As long as you are working within EiffelStudio, you are using workbench code.
When you are happy with the results of your development, you will normally finalize the system, thereby generating '''final code'''. Although not strictly required, this step is in most cases appropriate since final code is significantly more efficient than workbench code in both time and space: finalization performs a number of optimizations -- dead code removal, replacement of dynamic by static binding -- that wouldn't be justified in incremental development where, for example, some code element that is "dead" one minute may be resurrected the next moment through the addition of just one line of text. In addition, because finalized code is more efficient than frozen code, it is the natural choice if, using EiffelStudio for cross-platform development, you wish to port the resulting C-package to other architectures.
If you have a set of reusable classes that may be useful to many applications, you can '''precompile them''' into a library. This set of classes must be <span>self-contained</span> in the sense that all the classes needed by any of them must be either in the library itself or in another library that you will include in the precompilation.
</div><div>
==Bytecode==
The result of melting operations -- the contents of the "bowl" -- is an internal software representation known as melted code or (for no particularly good reason) as <span>bytecode</span>. EiffelStudio generated bytecode serves two complementary purposes:
* It can be executed directly. This is what happens during melting: while the rest of your system, the frozen part, is executed in the form produced by Eiffel compilation generation and C-compilation of the result, the melted part is interpreted "as is" without further translation.
* It can be compiled into C for further processing.
Internally, the melted code is in a file <code>simple</code>.<code>melted</code> (where <code>simple</code> is our project's name) in the subdirectory <code>EIFGENs/simple/W_CODE</code> of the project directory. The file is not human-readable, but as you add elements to your software and melt you watch its size grow. Whenever you freeze, it's emptied.
On the Microsoft .NET implementation of EiffelStudio, bytecode is replaced by that platform's own internal code, MSIL.
</div><div>
==Degrees==
You can now see the reason behind the terminology used to describe compilation steps, called '''degrees''' on the messages that flash on the screen when you do a compilation. The names are inspired by the international temperature scale -- Celsius, also known as centigrade -- where water freezes at 0 (and boils at 100, but Eiffel software never reaches that). For EiffelStudio:
* Compilation starts at degree 6, which examines the clusters of your system to determine what classes may have changed. In many cases the compilation can safely skip part of this degree.
* Degree 5 parses modified classes. It's executed not only when you explicitly request a compilation, but also when you save a class from the EiffelStudio editor, or exit from an external editor, so that you can see and fix syntax errors without delay.
* Degrees 4 down to 1 take care of melting.
* Negative degrees only take place when you freeze or finalize.
* After negative degrees comes C-compilation if needed.
</div><div>
==Using melting and freezing==
When should you melt, freeze, finalize or precompile? The answers are simple and follow directly from the preceding overview; they provide the key to getting the environment to work for you in the most effective way possible.
Melting is the bread and butter of the Eiffel developer. As you build your software, either from scratch or by modifying an existing system, you will regularly melt to benefit from the various checks that compilation performs and, of course, to generate executable code that you can test and debug immediately. During this process, there is no need to refreeze, since this operation (although still incremental) takes significantly more time than melting.
Only two operations, noted above, <span>require</span> freezing: the addition of external (non-Eiffel) routines, such as C functions or C++ classes, and the addition of agents. The reason is easy to understand: the EiffelStudio compiler knows how to melt Eiffel software, but not software written in C or other languages; agents similarly require special code generation.
''For the first compilation of a system that does not use precompiled EiffelBase, a Freeze is needed since class '' <code> ANY </code>'', from which all other classes inherit, uses some external routines. In this case the environment automatically starts a freeze even if you just click Melt. This does not apply if you have access to precompiled EiffelBase.''
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>
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:
* On Windows, in a new console that comes up for the occasion (minimize it if you don't want to see the messages).
* On Unix/Linux and VMS, in the window from which you launched EiffelStudio.
You will be able to execute the frozen system as soon as the C compilation finishes.
You will note that freezing, although it takes more time than melting, is actually quite fast, both due to the speed of Eiffel compilation and to the structure of the generated C code, designed to optimize the operation of the C compiler.
</div><div>
==Using finalizing==
The main reason for finalizing a system is run-time performance of the generated system. Finalization enables you to generate the high-performance executables that are among the hallmarks of ISE Eiffel. As a consequence, finalized code is the best vehicle for cross-development: you can port the resulting C package to various target platforms and C-compile them on these platforms.
The '''optimizations''' performed by finalization affect both space and time:
* <span>Dead code removal</span> strips the executable module of all the routines in the system that are not actually called, directly or indirectly, by the root's creation procedure. In a large system relying on many general-purpose classes, dead code removal can easily reduce an executable's size by one third or more.
* Finalization also applies <span>static binding</span> to non-polymorphic calls, and <span>inlines</span> some routine calls.
As long as you continue changing, melting and freezing your system, the workbench compiling mechanisms cannot perform such optimizations: if a routine is "dead" today you may resurrect it tomorrow by adding a new call to it somewhere; and if a call is non-polymorphic a single additional assignment may require dynamic binding. Compilation can only generate optimal code by working on a full, stable system. This is the task of finalization.
'''Cross-development''', the second reason for finalizing, is important if you are taking advantage of the portability of ISE Eiffel to develop your system on a certain platform and then run the result on target computers with possibly different architectures. A target machine may lack an ISE Eiffel compiler (unmistakably signaling its owner's backwardness) but include a C compiler. If the development and target platforms are of different architectures you will need to obtain a copy of the run-time system for the target architecture. The run-time system is also ANSI-C-based, so porting it is usually a straightforward matter.
Note that cross-development does not <span>require</span> finalization, since you can cross-compile a frozen version. In practice, however, the finalized version is usually the preferred form for porting a C package because of the performance advantage.
Finalize the example system now by selecting the menu entry <code> Project </code> <code> --> </code> <code> Finalize </code>. Here too you will be asked to confirm, although the dialog enables you to suppress that confirmation for later attempts, and you may skip C compilation. You will note that finalization is longer than freezing, but still remains quite reasonable thanks to the extensive optimization of the Eiffel compilation process and the structure of the generated C code.
</div>
[[15 GRAPHICS-BASED DESIGN|<< Previous]] [[17 THE COMMAND-LINE COMPILER|Next >>]]

49
documentation/current/eiffelstudio/eiffelstudio-guided-tour/index.wiki Normal file
View File

@@ -0,0 +1,49 @@
[[Property:title|EiffelStudio: A Guided Tour]]
[[Property:weight|0]]
==Interactive Software Engineering==
===[[MANUAL IDENTIFICATION AND COPYRIGHT|MANUAL IDENTIFICATION AND COPYRIGHT]]===
{{note| This is not an introduction to the Eiffel method and language. See the list of [[Getting started with Eiffel|introductory documents]] for ''Invitation to Eiffel'' and a longer tutorial. }}
<div>
==[[1 OVERVIEW AND PREREQUISITES|1 OVERVIEW AND PREREQUISITES]]==
==[[2 COPYING THE EXAMPLE FILES|2 COPYING THE EXAMPLE FILES]]==
==[[3 STARTING EIFFELSTUDIO AND OPENING A PROJECT|3 STARTING EIFFELSTUDIO AND OPENING A PROJECT]]==
==[[4 COMPILING AND EXECUTING A SYSTEM|4 COMPILING AND EXECUTING A SYSTEM]]==
==[[5 A LOOK AT THE PROJECT DIRECTORY|5 A LOOK AT THE PROJECT DIRECTORY]]==
==[[6 STARTING TO BROWSE|6 STARTING TO BROWSE]]==
==[[7 CLASS VIEWS|7 CLASS VIEWS]]==
==[[8 PRODUCING AND EXPORTING DOCUMENTATION|8 PRODUCING AND EXPORTING DOCUMENTATION]]==
==[[9 BROWSING FEATURES|9 BROWSING FEATURES]]==
==[[10 RETARGETING THROUGH PICK-AND-DROP|10 RETARGETING THROUGH PICK-AND-DROP]]==
==[[11 RECOMPILING AND EDITING|11 RECOMPILING AND EDITING]]==
==[[12 HANDLING SYNTAX AND VALIDITY ERRORS|12 HANDLING SYNTAX AND VALIDITY ERRORS]]==
==[[13 DEBUGGING AND RUN-TIME MONITORING|13 DEBUGGING AND RUN-TIME MONITORING]]==
==[[14 COMPUTING PROJECT METRICS|14 COMPUTING PROJECT METRICS]]==
==[[15 GRAPHICS-BASED DESIGN|15 GRAPHICS-BASED DESIGN]]==
==[[16 HOW EIFFELSTUDIO COMPILES|16 HOW EIFFELSTUDIO COMPILES]]==
==[[17 THE COMMAND-LINE COMPILER|17 THE COMMAND-LINE COMPILER]]==
==[[18 EXECUTING A SYSTEM WITHIN AND WITHOUT EIFFELSTUDIO|18 EXECUTING A SYSTEM WITHIN AND WITHOUT EIFFELSTUDIO]]==
==[[19 APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT|19 APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT]]==
</div>

73
documentation/current/eiffelstudio/eiffelstudio-guided-tour/manual-identification-and-copyright.wiki Normal file
View File

@@ -0,0 +1,73 @@
[[Property:title|MANUAL IDENTIFICATION AND COPYRIGHT]]
[[Property:link_title|Manual identification and copyright]]
[[Property:weight|7]]
Title: ''EiffelStudio: A Guided Tour'', Eiffel Software Technical Report TR-EI-68/GT. (Replaces TR-EI-38/EB.)
===Publication history===
First published 1993 as ''First Steps with EiffelBench'' (TR-EI-38/EB) and revised as a chapter of ''Eiffel: The Environment'' [http://www.eiffel.com/doc/ (TR-EI-39/IE), also available as] <span>An Object-Oriented Environment</span> (Prentice Hall, 1994, ISBN 0-13-245-507-2.
Version 3.3.8, 1995.
Version 4.1, 1997
This version: July 2001. Corresponds to release 5.0 of the EiffelStudio environment.
===Author===
''Bertrand Meyer''
===Software credits===
Emmanuel Stapf, Arnaud Pichery, Xavier Rousselot, Raphael Simon; Etienne Amodeo, Jrome Bou Aziz, Vincent Brendel, Gauthier Brillaud, Paul Colin de Verdiere, Jocelyn Fiat, Pascal Freund, Savrak Sar, Patrick Schonbach, Zoran Simic, Jacques Sireude, Tanit Talbi, Emmanuel Texier, Guillaume Wong-So; EiffelVision 2: Leila Ait-Kaci, Sylvain Baron, Sami Kallio, Ian King, Sam O'Connor, Julian Rogers. See also acknowledgments for earlier versions in ''Eiffel: The Environment''(TR-EI-39/IE)
Non-Eiffel Software: special thanks to Thomas Beale, Eric Bezault, Paul Cohen, Paul-Georges Crismer, Michael Gacsaly, Dave Hollenberg, Mark Howard, Randy John, Eirik Mangseth, Glenn Maughan, Jacques Silberstein.
===Cover design===
Rich Ayling.
===Copyright notice and proprietary information===
Copyright Interactive Software Engineering Inc. (Eiffel Software), 2001. May not be reproduced in any form (including electronic storage) without the written permission of Eiffel Software. "Eiffel Power" and the Eiffel Power logo are trademarks of Eiffel Software.
All uses of the product documented here are subject to the terms and conditions of the Eiffel Software user license. Any other use or duplication is a violation of the applicable laws on copyright, trade secrets and intellectual property.
Any third-party products mentioned in this document are hereby acknowledged as trademarks of their respective owners.
===Special duplication permission for educational institutions===
Degree-granting educational institutions using EiffelStudio teaching purposes as part of the <span> [http://www.eiffel.com/educators/resources.html Eiffel University Partnership Program] </span> may be permitted under certain conditions to copy specific parts of this book. Contact Eiffel Software for details.
{|
|-
| <center>'''About Eiffel Software ''' </center>
|-
|
Eiffel Software (Interactive Software Engineering) helps you produce software better, faster and cheaper.
Eiffel Software provides a wide range of products and services based on object technology, including EiffelStudio, a complete development environment for the full system lifecycle. Eiffel Software's training courses, available worldwide, cover key management and technical topics. Eiffel Software's consultants are available to address your project needs at all levels.
Eiffel Software's TOOLS (Technology of Object-Oriented Languages and Systems) conferences, [http://www.tools-conferences.com http://www.tools-conferences.com] , are the meeting point for anyone interested in the software technologies of the future.
Eiffel Software originated one of the earliest .NET products and offers a full range of .NET services and training at [http://www.dotnetexperts.com http://www.dotnetexperts.com] .
For more information <br/>
<br/>
Interactive Software Engineering Inc.<br/>
Eiffel Software Building, 360 Storke Road<br/>
Goleta, CA 93117 USA<br/>
Telephone 805-685-1006, Fax 805-685-6869 <br/>
<br/>
Internet and e-mail
Eiffel Software maintains a rich source of information at [http://www.eiffel.com http://www.eiffel.com] , with more than 1200 Web pages including online documentation, downloadable files, product descriptions, links to Eiffel Software partners, University Partnership program, mailing list archives, announcements, press coverage, Frequently Asked Questions, Support pages, and much more.
Visit [http://www.eiffel.com/general/contact_details.html http://www.eiffel.com/general/contact_details.html] to request information about products and services. To subscribe to the Eiffel Software user list, go to[http://groups.eiffel.com/join http://groups.eiffel.com/join] .
Support programs
Eiffel Software offers a variety of support options tailored to the diverse needs of its customers. See [http://support.eiffel.com http://support.eiffel.com] for details.
|}

87
documentation/current/eiffelstudio/eiffelstudio-guided-tour/overview-and-prerequisites.wiki Normal file
View File

@@ -0,0 +1,87 @@
[[Property:title|1 OVERVIEW AND PREREQUISITES]]
[[Property:link_title|Overview and Prerequisites]]
[[Property:weight|-15]]
[[Help reading the EiffelStudio Guided Tour|Help reading this manual]]
EiffelStudio is the central tool of Eiffel Software's implementation of Eiffel, letting you design, develop, debug, document, measure, maintain, revise and expand systems using the full power of object technology and Design by Contract <span>TM</span>.
This presentation introduces the essential properties of EiffelStudio. It will take you through a tour of the environment, using a pre-existing example system.
==What will I achieve?==
Although it skips many specific or advanced facilities, this Tour will help you quickly become familiar with the way you can use the environment for your work. After reading it you will know the basics of working with EiffelStudio:
* Starting a project and retrieving an existing project.
* Entering new software elements -- clusters, classes and features.
* Compiling your software.
* Making changes and having them immediately recompiled using the Melting Ice Technology <span>TM</span>.
* Displaying a graphical representation of your software elements, and modifying the software through the graphical views (as well as through its text).
* Producing extensive documentation of your system, textual or graphical, under many different formats such as HTML, RTF, Postscript, XMI (for example Rational Rose) and others.
* Browsing through simple or complex software systems, to find out their various components, properties and relationships.
* Measuring quantitative properties of the software, by applying metrics predefined in EiffelStudio as well as new ones that you define.
* Executing a compiled system, and controlling its execution through the debugging mechanisms of EiffelStudio.
==About the scope of EiffelStudio==
The most important property to keep in mind as you are discovering EiffelStudio is that it is neither just a "programming environment" nor just a "CASE tool" (Computer-Aided Software Engineering) for analysis and design. It encompasses both of these functions and many others. Most system builders today are used to a dichotomy between the high end and the low end:
* At the analysis and design levels, graphical tools help you clarify your thinking about the system, interacting with customers and end users, and devise high-level system architectures, usually in diagrammatic form.
* At the low end, programming tools help you edit, compile and debug your programs.
Keeping these tools separate is, however, detrimental to the quality of the software process and the resulting products. If they are in the hands of different teams, communication problems may arise, leading to discrepancies between need and realization; this can be a source of bugs or even project failure. If it's the same people using tools of both kinds, they have to keep switching notations, tools and modes of thinking. The use of different frameworks at both ends makes it difficult to keep the high-level model and the implementation consistent; too often, a change decided at the implementation level is not reflected back in the higher model. After a while, the system gets into the state of disorder and inconsistency that good tools are precisely meant to avoid.
EiffelStudio, in line with the principles of <span>seamless development</span> and <span>reversibility</span> of the Eiffel method, removes the gap by providing a single set of tools that accompany you throughout a project, from the most high-level initial stages to the most low-level aspects of implementation and maintenance.
This generality is reflected throughout the environment by, for example, the dual use of text and graphics. As another example, you should think of the EiffelStudio <span>compiler</span>, not just as a tool for executing Eiffel software in its final form, but also, thanks to its extensive <span>validity checking</span> facilities, as a design consistency tool that performs many verifications commonly associated with CASE tools.
Depending on your project needs, you may take advantage of EiffelStudio's versatility to address specific purposes:
* You may use EiffelStudio as a programming environment, with advanced tools for compiling, browsing and debugging.
* Some people use EiffelStudio as a <span>modeling</span> tool only, building system descriptions consisting only of <span>deferred</span> (abstract) classes with no implementation, and relying on the Diagram Tool to build, present and discuss these descriptions through graphical views.
* You may use EiffelStudio in both capacities, taking advantage of the seamlessness between all the affected phases.
==Learning by doing==
If you have access to EiffelStudio as you read this Tour, the most effective technique is to execute all the suggested operations as you read about them.
Please execute user actions, such as clicking, only when asked to do so.
==What should I already know?==
This Tour assumes very little about what you know and what you don't.
It does assume that you can do simple manipulations on your platform of choice, such as: on Windows, finding and drag-and-dropping folders and files in the Windows Explorer; on Unix, changing to a certain directory ( <code> cd </code> ) and listing the files of a directory ( <code> ls </code> ).
The more you already know about object technology and object-oriented environments, the better. But remember, if you have used other environments before, keep a fresh outlook; EiffelStudio <span>is</span> different, and it may take a while before you fully understand why it does some things in a certain way.
==A note on platform differences==
EiffelStudio is one of the most portable environments in the industry, running in an almost identical fashion on Windows, on the new Microsoft .NET environment, on many variants of Unix, on Linux, on VMS.
Once an EiffelStudio session has been started, you can largely forget about the operating system. But a few operations -- mostly at the beginning, to launch EiffelStudio -- require platform-dependent mechanisms: starting a program, traversing the file structure, selecting a file. These cases will be marked accordingly below.
Windows users should particularly note the following two conventions of terminology:
* Operating systems store files into hierarchically nested structures called <span>folders</span> or <span>directories</span>. Although "folder" is the more common term for Windows, we will mostly speak of "directories". It's exactly the same thing.
* A file has a full <span>path name</span>, used to describe how to reach it from the root of its file system, as in <code> c:\d1\d2\f </code>. This example uses the Windows notation, which separates successive components of a path name by a backward slash character <code> \ </code>. On Unix and Linux, the separator is a forward slash <code> / </code>, as in <code> /d1/d2/f </code> ; this is also the convention on the Internet for denoting addresses (URLs). Most file names in this manual appear in this Unix/Internet style. On Windows you will normally have to use the backslash convention, although EiffelStudio also accepts forward slashes. In any case you must be consistent: don't mix backward and forward slashes in the same path name. Also note that some names, such as those of object files to be linked with your system, will be passed to outside tools -- C compilers, loaders -- that may not accept the forward slash.
VMS users may similarly use either the Unix convention or the specific VMS path naming convention.
If you are a one-platform person, just ignore, for the next few pages, all references to any platform other than your heart's favorite. They will quickly go away.
==What should I have done first?==
To run the example you must have installed EiffelStudio and set up the environment. Check in particular the following:
* On Windows, you must have run the installation procedure; it will have put EiffelStudio in the Programs section of the start menu, subsection "EiffelStudio version", where version is the version number, e.g. 6.0.
* The environment variable <code> ISE_EIFFEL </code> must be set to the installation directory, and the environment variable <code> ISE_PLATFORM </code> to the platform. On Windows this is taken care of automatically by the installation procedure, but on Unix/Linux and VMS you must update your path and environment manually. Throughout this discussion the notations <code> $ISE_EIFFEL </code> and <code> $ISE_PLATFORM </code> will refer to the values of these variables -- the installation directory, and the platform. (The Windows notation would be <code> %ISE_EIFFEL% </code> and <code> %ISE_PLATFORM% </code>.)
* On Unix/Linux and VMS, your "path" must include the place where EiffelStudio executables reside. (On Windows the installation procedure takes care of this.)
* Also, the discussion assumes that as part of the installation you have included the EiffelBase library, in precompiled form. EiffelBase is automatically included if you have installed another precompiled library, such as WEL, the Windows Eiffel Library. The installation procedure takes care of precompiling EiffelBase.
==Locating the example==
Please take a moment to locate the example files on your installation. They all appear in the following directory, part of the Eiffel delivery:
<code>$ISE_EIFFEL/examples/studio/tour</code>
(Windows users: remember that instead of the slash <code> / </code> your platform uses a backslash <code> \ </code>. VMS users: this is to be replaced by the VMS path naming conventions.)
[[2 COPYING THE EXAMPLE FILES|Next >>]]

146
documentation/current/eiffelstudio/eiffelstudio-guided-tour/producing-and-exporting-documentation.wiki Normal file
View File

@@ -0,0 +1,146 @@
[[Property:title|8 PRODUCING AND EXPORTING DOCUMENTATION]]
[[Property:link_title|Producing and Exporting Documentation]]
[[Property:weight|-7]]
[[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:
* You must be able to export the information easily to the World-Wide Web, the most general and widely available interaction mechanism.
* The documentation must be <span>faithful</span> to the software. Because of the ever-changing nature of software, this goal is impossible to satisfy unless the documentation is <span>extracted</span> from the software -- as opposed to the traditional approach, still perpetuated by many CASE tools, of treating the two as separate.
* The task of updating the documentation after a software change must be straightforward and automatic.
* It's not enough to support HTML; many other formats are useful too.
* Users must have the ability to adapt the mechanism to support <span>new</span> formats.
* For existing formats, they must have a way to tune the output easily to any specific style standards, company policies, local variants.
EiffelStudio's documentation generation satisfies all these requirements.
==Documentation filters==
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>
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.
The Wizard starts with a list of available output formats, also called <span>filters</span>:
<div> [[Image:index-37]] [[general/guided_tour/studio/index-37.png|(link)]] </div>
The filter names correspond to major documentation formats which EiffelStudio supports by default. Among the most important, listed here in rough order of appearance in the list:
* <code> ASCII </code> : plain text, no formatting codes.
* <code> eiffel </code> : essentially the same as ASCII; useful if you want EiffelStudio to pretty-print your class texts and replace the originals, as explained below.
* <code> MML </code> : internal format for Adobe FrameMaker.
* <code> Postscript </code> : to generate Adobe Postscript output, suitable for printing on a Postscript printer, display on a Postscript previewer such as Ghostscript, or distilling to Adobe PDF.
* <code> COM </code> : to generate class specifications in the form of an Interface Description Language (IDL) interface for Microsoft's COM component model.
* <code> RTF </code> : Microsoft's Rich Text Format, used in particular for Windows "Help" files.
* <code> TeX1 </code>, <code> TeX2 </code> : two variants for Donald Knuth's TEX processing format.
* <code> troff </code> : if you already know what this is, congratulations (or condolences), you've been around the industry for a while. This is a traditional text-processing format available on Unix systems. Also works for the <span>gtroff</span> variant.
* <code> html-classic </code> : HTML, no style sheets. The next variant, <span>with</span> style sheets, is strongly recommended unless your colleagues will be reading your documentation with Mosaic 1, vintage 1993, or Netscape 2, Vintage 1995.
* <code> html-stylesheet </code> : HTML with style sheets. This is particularly attractive for Web publishing not only because the output makes full use of style sheet capabilities (fonts, colors, layout, formatting) but also because it becomes trivial to change the look-and-feel to support any style you or your users like, even <span>after</span> generation, simply by editing the style sheet file.
Not only do these predefined filters provide support for a number of important industry formats; better yet, if you want <span>another</span> format not represented on the list, or would like to adapt an existing format to your own style preferences, it's easy to define a new filter. The list that EiffelStudio displays comes from the files with a <span>.</span> <code> fil </code> extension that it finds in a subdirectory of the installation:
<code>
$ISE_EIFFEL/studio/filters
</code>
To define a new filter, simply add a file to this directory. Filters are expressed in a simple notation called EFF ( <span>Eiffel Filter Format</span> ), general enough to support a wide variety of tools for text processing, project management, Web publishing etc. The best way to define a new filter is usually to start from an existing one and adapt it. You will find the specification of EFF at the end of this manual, [[19 APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT|here]] .
==Generating an HTML record of your project==
Let's select the most obviously attractive of the predefined filters: HTML with stylesheets. Click the line <code> html-stylesheet </code> in the list to make it active, then click <code> Next </code> at the bottom of the Documentation Wizard window. The next window appears:
<div> [[Image:index-38]] [[general/guided_tour/studio/index-38.png|(link)]] </div>
This is to let you decide which clusters of your system the documentation will include. Initially all clusters/libraries appear in the <code> Include </code> list on the right; but you might want to exclude some standard libraries or other clusters from the documentation.
To move a cluster from the right column to the left one, click it to select it, and click the left arrow button; for the reverse, use the right arrow.
You can play with moving a couple of clusters back and forth, but for this Tour we'll want to generate everything, including EiffelBase, so make sure that in the end all clusters appear in the right column, as on the last figure. Then click <code> Next </code>.
==Generating Metatags from Indexing entries==
The next step of the documentation wizard asks you to select indexing entries:
<div> [[Image:index-39]] [[general/guided_tour/studio/index-39.png|(link)]] </div>
Eiffel classes, as you know, may start with an <code> Indexing </code> entry that enables class authors to include documentary information in any category they like. It is standard (and part of the official style guidelines) to include at the very least an entry of the form <code> description: </code> <code> Descriptive text </code> in every class. The earlier displays of class <code> LIST </code> showed that entry, which read " <code> Sequential lists, without commitment to a particular representation </code>".
You may have noted that the purpose of Eiffel's <code> Indexing </code> clauses is, conceptually, similar to that of '''metatags''' in HTML. Metatags carry information which Web page visitors do not normally see in the browser; this information is available, however, to search engines and other tools that explore and classify Web pages. So it seems quite appropriate to generate metatags from <code> Indexing </code> entries.
The dialog illustrated in the last figure lets you select the entries you wish to transform into metatags. It appears only if you have selected an HTML filter. It lists all the <code> Indexing </code> tags found anywhere in the system; those on the right will be retained for metatags. Initially the <code> Exclude </code> list on the left contains three tags conventionally used -- at Eiffel Software and other Eiffel sites -- for interfacing with configuration management tools, and hence of internal interest only.
There is no need to change the default selection, so just click <code> Next </code>.
==Choosing a level of detail==
The next step of the Documentation Wizard lets you specify what kinds of documents you want to generate:
<div> [[Image:index-40]] [[general/guided_tour/studio/index-40.png|(link)]] </div>
This is a very important facility since it gives you control over how much you want to publish about the properties of the software:
* You may want to publish <span>everything</span>, source included, for example on your Intranet for a group of developers working closely together on the same classes, or on the Internet for open-source software.
* You may want to publish only the <span>interfaces</span> (Contract or Flat-Contract views). This is not necessarily to protect proprietary information; even if you don't care about showing your source code, it is usually too detailed for client programmers, especially in the case of libraries. If various teams work on separate parts of a project, what each releases to the other should usually be the specification, not the implementation.
* You may of course want to publish <span>both</span> the text and the interface, and let the recipients use the version that best suits their needs for each use.
* You may want to publish the <span>diagrams</span>, showing the structure in graphical form. Note the warning -- which we are about to ignore -- telling us this may take a while.
* The class list, cluster list, cluster hierarchy view, cluster chart (following the conventions of BON) are also optional.
The dialog shown on the last figure lets you specify the exact combination you wish. The figure indicates the default options.
This time, if we generate anything, we'll generate everything. Please check '''all''' the boxes (the generation won't occur until the last step) and click <code> Next </code> to move to the next dialog of the Documentation Wizard.
==Specifying cluster views==
The next dialog only appears when you have asked to generate diagrams:
<div> [[Image:index-41]] [[general/guided_tour/studio/index-41.png|(link)]] </div>
Although we didn't use this possibility yet, the Diagram view lets you define different subviews of any cluster. One view might show inheritance only, the other client links only; one might include all classes, the other hide some library classes. The last dialog shown will allow you, for any cluster, to select a subview other than the default for the generated diagram.
Here we only have the default view, so just click <code> Next </code>.
==Generating==
The last dialog simply asks you where you want to generate the result:
<div> [[Image:index-42]] [[general/guided_tour/studio/index-42.png|(link)]] </div>
By default, as shown, EiffelStudio will produce the documentation in a subdirectory -- created for the occasion, if it doesn't exist yet -- of the project directory:
<code>
Project_directory /Documentation
</code>
You may, however, select any other location you like. In the case of HTML generation, as here, EiffelStudio takes great care to use only '''relative hyperlinks''' so that you can move the <code> Documentation </code> directory around, for use either on a file system or on your Web site, with the guarantee that the hyperlinks will work -- as long as you move the entire directory together.
To continue the Guided Tour, you do '''not''' need to complete the generation now unless you want to. If you are happy to continue without generating the documentation at the moment then click <code> Cancel </code> on the last dialog.
{{note| ''If you prefer to produce your own, click "Finish". For our example system the process takes 7 minutes on the Thinkpad configuration mentioned earlier, and generates a 82 megabyte documentation directory.'' }}
==Browsing generated documentation==
Let's take a look at the generated documentation. We start with the root of the generated documentation, <code> Documentation/index.html </code> :
<div> [[Image:index-43]] [[general/guided_tour/studio/index-43.png|(link)]] </div>
This root page shows overall information about the system. The top set of links, repeated at the bottom, enables you to browse the system from its list of classes, its list of clusters, or the cluster hierarchy; note the box labeled <code> to Go </code>, which provides a built-in search engine, enabling you to type any class list and go directly to the corresponding page. Let's look at the class list: click the box <code> Classes </code> at the top left.
<div> [[Image:index-44]] [[general/guided_tour/studio/index-44.png|(link)]] </div>
This shows the beginning of the list of classes, alphabetically sorted. You could click any class to get the corresponding information, but wait; we'll look at individual classes in a moment. Instead, click <code> Cluster hierarchy </code> to see the overall organization of the system into clusters:
<div> [[Image:index-45]] [[general/guided_tour/studio/index-45.png|(link)]] </div>
Click <code> BASE </code> to see details of the EiffelBase library where (under EiffelStudio) we had found the class <code> LIST </code> used as example in the preceding sections:
<div> [[Image:index-46]] [[general/guided_tour/studio/index-46.png|(link)]] </div>
This indicates the relations of the cluster to others in the hierarchy, and its list of classes. Again you could click any class name but instead note the mention <code> (diagram) </code> next to the cluster name near the top. Remember that when generating the documentation we elected to generate everything, diagrams included. Hadn't we checked the corresponding check box, the <code> (diagram) </code> link wouldn't be there. Click it now to get the generated diagrams:
<div> [[Image:index-47]] [[general/guided_tour/studio/index-47.png|(link)]] </div>
The output is a diagram showing graphically the classes of the cluster and their inheritance relations. All EiffelStudio-generated HTML diagrams use the PNG graphics format ( <span>Portable Network Graphics</span> ), supported by all recent browsers.
The class bubbles in a diagram are all hyperlinks. To see the HTML documentation for our old friend the class <code> LIST </code> -- which you could also obtain by clicking its name on one of the preceding diagrams, or typing it in the <code> Go to </code> field -- just click its bubble:
<div> [[Image:index-48]] [[general/guided_tour/studio/index-48.png|(link)]] </div>
The display shows key information on the class, in a form called the "Chart format" listing the ancestors and then the features, divided into <code> Queries </code> (shown in part on the figure) and <code> Commands </code>. Note that all class names and feature names are hyperlinks, which would lead you to the appropriate place in a class text.
The top row of hyperlinks now includes class formats corresponding to those we discovered under EiffelStudio ( [[7 CLASS VIEWS|"CLASS VIEWS"]] ): <code> Relations </code> (covering ancestors, descendants, clients, suppliers, ), full <code> Text </code>, <code> Contracts </code>, <code> Flat contracts </code>. Click <code> Flat contracts </code> to see the full interface of the class:
<div> [[Image:index-49]] [[general/guided_tour/studio/index-49.png|(link)]] </div>
We'll stop this brief review here but you may continue browsing through the HTML pages if you like. Note how closely the appearance of the class texts, flat forms, contract forms, diagrams and other forms of documentation matches the corresponding formats under EiffelStudio.
Although we suggest staying with the standard, you can easily change any convention that doesn't match your own preferences:
* For the EiffelStudio appearance, use <code> Tools </code> <code> --> </code> <code> Preferences </code>.
* For the HTML appearance, if you know about Cascading Style Sheets (CSS) for HTML, edit the style sheet <code> default.css </code>. You will find this file in the generated documentation directory; alternatively, to ensure the changes are applicable to the generated documentation of all future projects, edit <code> defaults.css </code> in the directory after backing it up. For more profound changes in the structure of the generated HTML, you may also backup and edit the Eiffel Filter Format file <code> html-stylesheet.fil </code> in the same directory. EFF is described in [[19 APPENDIX: WRITING DOCUMENTATION FILTERS WITH EFF, THE EIFFEL FILTER FORMAT| Chapter 19, "Appendix"]] .
<code>
$ISE_EIFFEL/studio/filters
</code>
The documentation generation mechanisms, using HTML or other formats, let you publish your designs, at the level of detail you desire, on an Intranet, the Internet, or as part of documents you release. They are an important part of the power of EiffelStudio for quality software development.
[[7 CLASS VIEWS|<< Previous]] [[9 BROWSING FEATURES|Next >>]]

28
documentation/current/eiffelstudio/eiffelstudio-guided-tour/starting-eiffelstudio-and-opening-project.wiki Normal file
View File

@@ -0,0 +1,28 @@
[[Property:title|3 STARTING EIFFELSTUDIO AND OPENING A PROJECT]]
[[Property:link_title|Starting EiffelStudio and Opening a Project]]
[[Property:weight|-13]]
[[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/VMS.
==Launching EiffelStudio under Window==
On Windows, you can launch EiffelStudio from the Start Menu under
<code> 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).
If this is the first time you are using EiffelStudio, you may get a dialog asking for an unlock code or inviting you to register the product. See <span> [[Software Installation for EiffelStudio 6.2|your platform installation instructions]] </span> for registration information.
==Launching EiffelStudio under Unix or VMS==
To launch EiffelStudio on Unix or VMS, change directory to <code> YOURDIR </code> and, from the command line, type
<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.)
[[2 COPYING THE EXAMPLE FILES|<< Previous]] [[4 COMPILING AND EXECUTING A SYSTEM|Next >>]]

91
documentation/current/eiffelstudio/eiffelstudio-guided-tour/viewing-classes.wiki Normal file
View File

@@ -0,0 +1,91 @@
[[Property:title|7 CLASS VIEWS]]
[[Property:link_title|Viewing Classes]]
[[Property:weight|-9]]
[[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!
{{note| ''If you don't see a tool targeted to '' <code> LIST </code> '', just retarget one, as you know how to do this now, for example by typing the name followed by Enter in the Class Field at the top left.'' }}
First let's give ourselves more space. Right now we don't need the Cluster Tree, Feature Tree and Properties panes. Get rid of them by clicking the close buttons on the top right corner of the panes.
You can get these panes back later by clicking the buttons in the toolbar or by going to the View, Tools Menu.
{{note| ''Another way to hide a pane is to click on the button in the toolbar or by unselecting them in the View, Tools Menu.'' }}
Two panes remain, showing the Editing Tool and the Context Tool.
<div> [[Image:index-26]] [[general/guided_tour/studio/index-26.png|(link)]] </div>
Make sure the Context Tool pane is large enough; you can resize the window and, if necessary, narrow down the Editing Tool pane since we don't need it for the moment. Don't worry, though, if the Context Tool shows only part of the diagram, as it does on the last figure, since we will now use the Context Tool to display information other than the diagram, by selecting the corresponding tabs.
==The Class Tab==
The first tab we'll look at is the Class Tab. You'll find it at the bottom of the Context Tool.
This gives you access to many forms of information about the current class -- the target of the Development Window. A set of buttons at the top of the Context Tool enables you to display a number of '''views''' of the class. The currently highlighted button indicates the default view: <code> Ancestors </code>. You can see the others' names by moving the cursor over the various view icons, '''without clicking''', and reading the tooltips.
The view currently displayed, <code> Ancestors </code>, shows the inheritance structure that leads to the current target, <code> LIST </code> :
<div> [[Image:index-29]] [[general/guided_tour/studio/index-29.png|(link)]] </div>
This shows that <code> LIST </code> is an heir of <code> CHAIN </code> which itself, as an example of multiple inheritance, is an heir of <code> CURSOR_STRUCTURE </code>, <code> INDEXABLE </code>, and -- twice, as an example of <span>repeated</span> inheritance -- <code> SEQUENCE </code>. If, because of direct or indirect repeated inheritance, a class appears more than once, the display doesn't repeat its ancestry the second and subsequent times; the omitted repetition appears as just three dots, '''...''', as illustrated here for the second occurrences of <code> BAG </code>, <code> ACTIVE </code> and others.
As you may have guessed, all the class names that appear on this display, by default in blue, can function as hyperlinks: you can use any one of them to retarget the Development Window to the corresponding class. This will be another major retargeting mechanism. But let's not pursue it for the moment and instead continue looking at the documentation views.
Next to <code> Ancestors </code> button is <code> Descendants, </code>which will give you the descendants of a class in a similar format:
[[Image:index-30]] [[general/guided_tour/studio/index-30.png|(link)]]
The progeny of <code> LIST </code>, as you can see, is just as impressive as its ancestry.
Let's now look at the other formats, starting from the left. The first button, <code> Clickable </code>, gives the class text. It's essentially the same information as appears in the top Editing Tool (whose pane was reduced to its bare minimum in the last few pictures, showing only the first three lines or so), but with some differences:
* The top Text view is editable. In fact it's EiffelStudio's primary tool for entering software texts. The bottom <code> Clickable </code> view is just a view; you can't change it.
* The Text view retains the formatting of the class text the way it was typed in; the <code> Clickable </code> view is automatically formatted -- "pretty-printed" -- according to the standard Eiffel layout rules.
* The <code> Clickable </code> view does not include comments inside routine implementations ( <code> do </code> and <code> once </code> clauses), although it does retain features' header comments.
* As part of the pretty-printing, the <code> Clickable </code> view uses colors and fonts to distinguish keywords, identifiers, comments and other syntactical elements. You can change the fonts and colors, like many other elements of the interface, through <code> Tools </code> <code> --> </code> <code> Preferences </code>. (Now is not the time.)
This view is called "clickable" because, as we'll see later, every syntactical element on it is a hyperlink, which you can use for browsing.
After <code> Clickable </code> comes the <code> Flat </code> view button. The layout of the result is similar. The flat form of a class is the reconstructed class text including not only what's declared in the class itself but also everything that it inherits from its ancestors, direct or indirect. This applies to the flat form's features, which include ancestor features, but also to contracts: the flat form's invariant includes all clauses from ancestors' invariants, and the preconditions are expanded to take <code> require else </code> and <code> ensure then </code> clauses into consideration. (The <span> [[An Eiffel Tutorial|Eiffel Tutorial]] </span> explains these notions in detail.)
As a result, the <code> Flat </code> view shows the class text as it might have come out had inheritance (what a horrible thought even to contemplate!) <span>not</span> been available to write it.
The first two features appearing in the above display, <code> cursor </code> and <code> first </code>, are indeed inherited from ancestors, rather than declared in <code> LIST </code> itself. Note how EiffelStudio, when producing the flat form, adds a line of the form
<code>
-- (From CLASS_OF_ORIGIN)
</code>
to the header comments of inherited routines, to document where they come from.
The flat form is an important notion of object technology, making it possible to understand a class by itself, regardless of the possibly rich inheritance structure that led to it. Looking at the Flat view of <code> LIST </code>, you may note how few of its properties come from the class itself; most of the interesting work has been done in ancestors, and <code> LIST </code> just adds a few details.
{{note| ''If at any time you want to search for a certain pattern in the views displayed, click the '' <code> Search </code> '' button at the top of the window, or type CTRL-'' <code> F </code>. ''A self-explanatory Search Tool will come up, with various options such as '' <span> ''Match case'' </span> '' and '' <span> ''Whole word'' </span> }}
Next come two essential documentation views: <code> Contract </code> and <code> Flat Contract </code>. Based on Eiffel's principles of Design by Contract, they document the interface properties of a class. Unlike the previous two, they do not show actual Eiffel texts, but information useful for client classes.
The contract form (also known as the '''short form''' of a class) is the class text deprived of any internal detail to retain interface information only. It discards any feature that's not exported (available to all clients); for the retained features, it discards the implementation -- <code> do </code> or <code> once </code> clause -- but retains the header (feature name, arguments, results), the header comment, and the contracts (precondition, postcondition, invariant) minus any contract clause that refers to a non-exported feature and hence would be useless to clients.
As you will know, particularly if you have read the book <span> [http://eiffel.com/doc/oosc/ Object-Oriented Software Construction] </span> , the contract form is the preferred way of documenting software elements, especially reusable components, as it provides clients with just the right level of abstraction: precise enough thanks to the type signature and the contracts; clear enough thanks to the header comments; and general enough since it omits implementation details that are irrelevant to client programmers (and might lead them to write client code that won't work any more if the implementation changes).
In practice you will often want to use, instead of the <code> Contract </code> view, the next one, <code> Flat Contract </code>, also known as "flat-short form" and "interface form", which applies the same rules to the flat form rather than to the original class. This means it shows information on all the features of the class, immediate (defined in the class itself) as well as inherited, whereas the short form, non-flat, only considers immediate features. The <code> Flat Contract </code> view provides the complete interface information for the class. Try it now on class <code> LIST </code>.
The next two buttons are for the <code> Ancestors </code> and <code> Descendants </code> views, which we have already seen, showing classes connected with the target through one of the two inter-class relations, inheritance. After them come <code> Clients </code> and <code> Suppliers </code>, to list the classes connected through the other relation, client. Clicking the <code> Clients </code> button shows the (empty) list of clients of <code> LIST </code>.
No class of this system directly uses <code> LIST </code> as client, although some use its descendant <code> ARRAYED_LIST </code>. Now click the next button to see the <code> Suppliers </code> of <code> LIST </code>.
The only two classes that <code> LIST </code> needs for its own algorithms are basic types from the Kernel Library, <code> BOOLEAN </code> and <code> INTEGER_32 </code>. In Eiffel, as you may remember, all types are defined by classes, even those describing such elementary values as integers and booleans.
==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>
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:
* <code> Deferred </code> features: abstract features which don't have an implementation in the current class, only in eventual descendants. Try this for <code> LIST </code> ; you'll see that this deferred class indeed has a number of deferred features.
* <code> Once and constants </code> : constant attributes, "once functions" which provide shared objects (close to the "singleton" pattern), and once procedures which provide a convenient initialization mechanism. <code> LIST </code> has 'Operating_environment' and 'Io' inherited from the parent class ANY.
* <code> External </code> features, implemented as calls to routines, macros or other elements implemented in other languages. <code> LIST </code> hasn't any.
* <code> Exported </code> features: those available to all clients. <code> LIST </code> has quite a few.
[[6 STARTING TO BROWSE|<< Previous]] [[8 PRODUCING AND EXPORTING DOCUMENTATION|Next >>]]