From d149543df8941329a17c6abfd3e5b74d1043d82c Mon Sep 17 00:00:00 2001 From: halw Date: Sun, 11 Jan 2009 21:19:41 +0000 Subject: [PATCH] Author:halw Date:2009-01-11T21:19:41.000000Z git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@157 abb3cda0-5349-4a8f-a601-0c33ac3a8c38 --- ...tion-filters-eff-eiffel-filter-format.wiki | 70 ++++++++-------- .../command-line-compiler.wiki | 10 +-- .../computing-project-metrics.wiki | 8 +- .../debugging-and-run-time-monitoring.wiki | 50 ++++++------ ...ystem-within-and-without-eiffelstudio.wiki | 24 ++++-- .../graphics-based-design.wiki | 80 +++++++++---------- .../handling-syntax-and-validity-errors.wiki | 12 +-- .../how-eiffelstudio-compiles.wiki | 41 +++++++--- .../windows-tool/window-list.wiki | 2 +- 9 files changed, 160 insertions(+), 137 deletions(-) diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/appendix-writing-documentation-filters-eff-eiffel-filter-format.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/appendix-writing-documentation-filters-eff-eiffel-filter-format.wiki index 0f38226f..31e63424 100644 --- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/appendix-writing-documentation-filters-eff-eiffel-filter-format.wiki +++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/appendix-writing-documentation-filters-eff-eiffel-filter-format.wiki @@ -13,40 +13,40 @@ This appendix describes EFF and its conventions, enabling you to write filters.
==Where to put filters== -When you choose to generate documentation, EiffelStudio will ask you to select a filter from a list it obtains by looking up the files of extension . fil in the directory +When you choose to generate documentation, EiffelStudio will ask you to select a filter from a list it obtains by looking up the files of extension . fil in the directory $ISE_EIFFEL/studio/filters -To make a new filter available to yourself and other users of this installation, just add the corresponding file name . fil to this directory. Make sure to choose the appropriate name , since this is what the menu of available filters will display. +To make a new filter available to yourself and other users of this installation, just add the corresponding file name . fil to this directory. Make sure to choose the appropriate name, since this is what the menu of available filters will display.
==Filter basics== -An EFF filter follows a very simple structure. As with all other Eiffel-related notations (such as Eiffel itself and Lace, the control language for Eiffel systems), any line or part of a line beginning with two consecutive dashes -- is a comment, except if it immediately follows a percent sign since, as will be seen below, - %- is used to denote an Eiffel comment in the class text. Blank lines are also permitted. Comments and blank lines carry no semantic value. +An EFF filter follows a very simple structure. As with all other Eiffel-related notations (such as Eiffel itself and Lace, the control language for Eiffel systems), any line or part of a line beginning with two consecutive dashes -- is a comment, except if it immediately follows a percent sign since, as will be seen below, - %- is used to denote an Eiffel comment in the class text. Blank lines are also permitted. Comments and blank lines carry no semantic value. Except for comments and blank lines, a filter is a sequence of entries, all of the form Construct | Replacement -where: Construct is one of a set of possible strings, most of which correspond to Eiffel constructs such as Class_declaration or Eiffel keywords such as class ; and Replacement is a string indicating how to format specimens of the Construct that appear in a class text. +where: Construct is one of a set of possible strings, most of which correspond to Eiffel constructs such as Class_declaration or Eiffel keywords such as class ; and Replacement is a string indicating how to format specimens of the Construct that appear in a class text. -For readability, there may be any number of blanks or tabs between the Construct and the vertical bar | , so that you can align all the bars if you wish. On the right of the bar, however, all characters including blanks and tabs are significant, since they are part of the replacement for the Construct . +For readability, there may be any number of blanks or tabs between the Construct and the vertical bar |, so that you can align all the bars if you wish. On the right of the bar, however, all characters including blanks and tabs are significant, since they are part of the replacement for the Construct.
==The asterisk== -In the Replacement part, you may use the symbol * (asterisk) to denote the construct specimen itself. So for example the entry +In the Replacement part, you may use the symbol * (asterisk) to denote the construct specimen itself. So for example the entry Feature_clause | %N%N*%N%N -specifies the following formatting for any Feature_clause : two successive blank lines (expressed as %N , New Line, a convention taken from Eiffel); the feature clause itself; two blank lines. +specifies the following formatting for any Feature_clause: two successive blank lines (expressed as %N, New Line, a convention taken from Eiffel); the feature clause itself; two blank lines. Similarly, in an HTML format, the entry External | * -means that the Eiffel keyword external must appear in the filtered form immediately preceded by , the HTML code for switching to boldface, and immediately followed by , the code for reverting to the previous setup. Here you can also write the right-hand side without the asterisks, as external . If, however, all keywords are to use boldface, it is preferable to write a single entry +means that the Eiffel keyword external must appear in the filtered form immediately preceded by , the HTML code for switching to boldface, and immediately followed by , the code for reverting to the previous setup. Here you can also write the right-hand side without the asterisks, as external. If, however, all keywords are to use boldface, it is preferable to write a single entry Keyword | * -which, thanks to the asterisk, will govern all construct specimens of the Keyword category. You can still override this specification for an individual keyword by including a specific entry for it. +which, thanks to the asterisk, will govern all construct specimens of the Keyword category. You can still override this specification for an individual keyword by including a specific entry for it.
==Constructs== -The following general syntactic constructs may appear as the left-hand side, Construct , of an entry: +The following general syntactic constructs may appear as the left-hand side, Construct, of an entry: Class_declaration Class_end @@ -70,51 +70,51 @@ Symbol Tab -Most of these denote Eiffel constructs as they appear in the official language reference, the book [http://www.eiffel.com/doc/ Eiffel: The Language] . Since the Eiffel construct names Feature , Invariant and Obsolete are also keywords and EFF, like Eiffel, is case-insensitive, the EFF construct names use the suffix _clause , for example Feature_clause . +Most of these denote Eiffel constructs as they appear in the official language reference, the book [http://www.eiffel.com/doc/ Eiffel: The Language] . Since the Eiffel construct names Feature, Invariant and Obsolete are also keywords and EFF, like Eiffel, is case-insensitive, the EFF construct names use the suffix _clause, for example Feature_clause. The constructs corresponding to syntactic constructs are self-explanatory. The others are: -* Class_end , denoting the final end of a class text. -* Keyword , denoting any Eiffel keyword among those listed in boldface in the corresponding appendix in [http://www.eiffel.com/doc/ Eiffel: The Language] -* New_line , denoting any passage to a new line in the class text. -* Suffix , used to introduce the file extension for the generated documentation files. If you don't specify this, EiffelStudio will use the filter's name as extension. -* Symbol , denoting any of the Eiffel symbols listed in the corresponding appendix of [http://www.eiffel.com/doc/ Eiffel: The Language] . -* Escape , to protect special characters of the external tool, as explained below. -* Tab , denoting any tab character appearing in the class text. +* Class_end, denoting the final end of a class text. +* Keyword, denoting any Eiffel keyword among those listed in boldface in the corresponding appendix in [http://www.eiffel.com/doc/ Eiffel: The Language] +* New_line, denoting any passage to a new line in the class text. +* Suffix, used to introduce the file extension for the generated documentation files. If you don't specify this, EiffelStudio will use the filter's name as extension. +* Symbol, denoting any of the Eiffel symbols listed in the corresponding appendix of [http://www.eiffel.com/doc/ Eiffel: The Language] . +* Escape, to protect special characters of the external tool, as explained below. +* Tab, denoting any tab character appearing in the class text.
==Keywords== -A Construct part may consist of the name of an Eiffel keyword. To see the complete list of possible keywords, look at the template filter, file format.fil-template in the default filter directory $ISE_EIFFEL/studio/filters , which includes all of them with a single asterisk * as the Replacement part. +A Construct part may consist of the name of an Eiffel keyword. To see the complete list of possible keywords, look at the template filter, file format.fil-template in the default filter directory $ISE_EIFFEL/studio/filters, which includes all of them with a single asterisk * as the Replacement part. -If entries are present for both the Keyword construct and individual keywords, the individual keyword entries will override the general entry for the keywords listed; the general entry will apply to all other keywords. This makes it possible to have both a general convention for keywords and a special convention for some of them. +If entries are present for both the Keyword construct and individual keywords, the individual keyword entries will override the general entry for the keywords listed; the general entry will apply to all other keywords. This makes it possible to have both a general convention for keywords and a special convention for some of them.
==Symbol== -A Construct part may consist of an Eiffel symbol, such as := , /= and many others. Again, you may see the complete list by looking at format.fil-template . Note the following conventions: -* % * represents an asterisk. For example as a multiplication operator; the % avoids the confusion with the special meaning of the asterisk for EFF. You can find examples of this convention in the EFF filters for troff and gtroff. -* Similarly, the Eiffel comment symbol appears as - %- , since just writing - - would introduce a comment in the EFF filter itself. +A Construct part may consist of an Eiffel symbol, such as :=, /= and many others. Again, you may see the complete list by looking at format.fil-template. Note the following conventions: +* % * represents an asterisk. For example as a multiplication operator; the % avoids the confusion with the special meaning of the asterisk for EFF. You can find examples of this convention in the EFF filters for troff and gtroff. +* Similarly, the Eiffel comment symbol appears as - %-, since just writing - - would introduce a comment in the EFF filter itself. -As with keywords, you may specify a general convention for symbols, defined by an entry for the construct Symbol , and special conventions for certain individual symbols. Specific symbol entries will override the general Symbol convention. +As with keywords, you may specify a general convention for symbols, defined by an entry for the construct Symbol, and special conventions for certain individual symbols. Specific symbol entries will override the general Symbol convention.
==Escape characters== -A text processing system or other external tool may attach a special role to characters that may normally appear in Eiffel texts. For example, the braces { and } , used in Eiffel's Export clauses, have a special meaning for TEX. Including them without precaution in TEX input will cause trouble. Similarly, many text processing formats attach a special meaning to the backslash character \ which, although not special for Eiffel, may appear in an Eiffel string. +A text processing system or other external tool may attach a special role to characters that may normally appear in Eiffel texts. For example, the braces { and }, used in Eiffel's Export clauses, have a special meaning for TEX. Including them without precaution in TEX input will cause trouble. Similarly, many text processing formats attach a special meaning to the backslash character \ which, although not special for Eiffel, may appear in an Eiffel string. -In such cases the filter must " escape " the special character, that is to say, protect it by other characters. For example troff and other text processing tools treat two successive backslash characters \\ as denoting a single backslash in the text to be output. The first backslash is the escape character, protecting the second one. +In such cases the filter must " escape " the special character, that is to say, protect it by other characters. For example troff and other text processing tools treat two successive backslash characters \\ as denoting a single backslash in the text to be output. The first backslash is the escape character, protecting the second one. -The Escape construct addresses such cases. The first character that follows Escape (after one or more blanks or tabs) is the character to be escaped. The string after the vertical bar is the replacement for that character. +The Escape construct addresses such cases. The first character that follows Escape (after one or more blanks or tabs) is the character to be escaped. The string after the vertical bar is the replacement for that character. Here for example is an escape entry for the backslash in tools that need to escape it through another backslash: ==Special characters and strings== -EFF uses Eiffel-like conventions, based on the percent sign, for control characters appearing in Replacement parts of entries. Two of these conventions have just been noted: % * to represent an asterisk and %- to represent a dash that does not introduce an Eiffel comment. In addition: -* %| denotes a vertical bar. (This is necessary since EFF uses | by itself in each entry to separate the Construct from the corresponding Replacement.) -* %N (recommended form) or %n denotes a new line. -* %T (recommended form) or %t denotes a tab. -* %% denotes a percent sign. -* % (percent followed by a space) denotes a space. This is equivalent to just a space, but more visible. +EFF uses Eiffel-like conventions, based on the percent sign, for control characters appearing in Replacement parts of entries. Two of these conventions have just been noted: % * to represent an asterisk and %- to represent a dash that does not introduce an Eiffel comment. In addition: +* %| denotes a vertical bar. (This is necessary since EFF uses | by itself in each entry to separate the Construct from the corresponding Replacement.) +* %N (recommended form) or %n denotes a new line. +* %T (recommended form) or %t denotes a tab. +* %% denotes a percent sign. +* % (percent followed by a space) denotes a space. This is equivalent to just a space, but more visible. -If c is not one of the characters for which special conventions have been listed, % c denotes the character c itself. +If c is not one of the characters for which special conventions have been listed, % c denotes the character c itself. -A multi-line entry uses the Eiffel convention for string continuations: % at the end of a line to signal that there is a continuation; a continuation line begins with zero or more spaces and tabs followed by a % ; the characters after the % are the continuation of the string. +A multi-line entry uses the Eiffel convention for string continuations: % at the end of a line to signal that there is a continuation; a continuation line begins with zero or more spaces and tabs followed by a % ; the characters after the % are the continuation of the string. diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/command-line-compiler.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/command-line-compiler.wiki index 3b7f8cf1..defe16d9 100644 --- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/command-line-compiler.wiki +++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/command-line-compiler.wiki @@ -4,10 +4,10 @@ [[Property:uuid|62bd8d62-a734-3ec0-9533-eaa096e7b81f]] Along with compilation from within EiffelStudio, it is possible to start compilation from a command line (shell). This is useful in particular to recompile your system automatically as part of a script. -To use the command-line compiler -- ec for Eiffel Compilation -- execute - - ec option & [class_name] [feature_name] - +To use the command-line compiler -- ec for Eiffel Compilation -- execute + +ec option & [class_name] [feature_name] + -Specify class_name and feature_name only if you wish to produce information about a class or a feature. Otherwise ec will compile a system according to each specified option . [[EiffelStudio: Command line options|Click here to see the set of supported options.]] +Specify class_name and feature_name only if you wish to produce information about a class or a feature. Otherwise ec will compile a system according to each specified option. [[EiffelStudio: Command line options|Click here to see the set of supported options.]] diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/computing-project-metrics.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/computing-project-metrics.wiki index 1d8f8976..b7de64bd 100644 --- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/computing-project-metrics.wiki +++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/computing-project-metrics.wiki @@ -2,7 +2,7 @@ [[Property:link_title|Computing Project Metrics]] [[Property:weight|0]] [[Property:uuid|8d1a3556-d9a2-0ac8-4d54-458f18cb56ad]] -In earlier sections we saw how EiffelStudio provides extensive documentation on your systems. That information was qualitative. Project managers and developers will also be interested in quantitative information about their projects. You can get such information through the Metrics tool, which enables you to perform a number of operations, detailed over the next few pages: +In earlier sections we saw how EiffelStudio provides extensive documentation on your systems. That information was qualitative. Project managers and developers will also be interested in quantitative information about their projects. You can get such information through the Metrics tool, which enables you to perform a number of operations, detailed over the next few pages: * Apply predefined metrics -- number of classes, number of invariants, number of features, number of compilations so far and many others -- to components of a system at various levels including feature, class, cluster, entire system. * Define new metrics, through mathematical formulae or boolean selection, and apply them to your project. * Store measurement results, as well as metric definitions, into an XML archive that can be stored locally or made available on the Web for future reference. @@ -22,15 +22,15 @@ The following terms are used in the presentation of EiffelStudio metric mechanis A '''metric''' -- not to be confused with a measure -- is a quantitative property of software products or processes whose possible values are numbers. A '''measure''' is the value of a metric for a certain product or process. -For example, we can evaluate the metric "number of classes in the system", called just Classes , by counting the classes in our system. This yields a measure. +For example, we can evaluate the metric "number of classes in the system", called just Classes, by counting the classes in our system. This yields a measure. We may distinguish between '''product''' ''' metrics''', which measure properties of the elements being turned out (code, designs, documentation, bug reports...) and '''process''' ''' metrics''', which measure properties of the process used to turn them out (salaries, expenses, time spent, delays...). The current metric facilities of EiffelStudio are primarily product-oriented but include a process metric: "number of compilations". Any metric should be relevant: related to some interesting property of the processes or products being measured, such as cost, estimated number of bugs, ease of maintenance...A '''metric theory''' is a set of metric definitions accompanied with a set of convincing arguments to show that the metrics are relevant. Neither EiffelStudio nor this manual provide a metric theory. -The numbers yielded by measures are meaningless unless we describe what they refer to. Every metric is relative to a certain '''unit''', specified as part of its definition. For example the unit for a metric that counts classes, such as Classes , is called class . +The numbers yielded by measures are meaningless unless we describe what they refer to. Every metric is relative to a certain '''unit''', specified as part of its definition. For example the unit for a metric that counts classes, such as Classes, is called class. -EiffelStudio provides a set of predefined units. Some simply serve to count occurrences of certain construct specimens in the software; examples include group , class , feature , line , ... The metric ratio describes metrics whose values are divisions, for example "average number of classes per cluster", obtained by dividing the number of classes by the number of classes. +EiffelStudio provides a set of predefined units. Some simply serve to count occurrences of certain construct specimens in the software; examples include group, class, feature, line, ... The metric ratio describes metrics whose values are divisions, for example "average number of classes per cluster", obtained by dividing the number of classes by the number of classes. A metric can be computed over a scope, this scope is defined using a domain. In a domain diff --git a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/debugging-and-run-time-monitoring.wiki b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/debugging-and-run-time-monitoring.wiki index ad297b76..ca6ae89d 100644 --- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/debugging-and-run-time-monitoring.wiki +++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/debugging-and-run-time-monitoring.wiki @@ -23,11 +23,11 @@ A group of icons on the Project Toolbar help control breakpoints. They are known 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. +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]] -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: +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]] @@ -37,40 +37,40 @@ By (left) clicking on a breakpoint mark, you toggle it between enabled and not s [[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. +The breakpoint mark for the routine's third instruction, create o2, is filled but not red; 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. +You can see the list of enabled and disabled breakpoints by clicking the Output Tab, or the Display info button in the Project Toolbar. -For the continuation of this tour it doesn't matter which exact breakpoints of make you've set, as long as the one on its first instruction is set and enabled (red-filled circle) as above. Please make sure this is the case before proceeding. +For the continuation of this tour it doesn't matter which exact breakpoints of make you've set, as long as the one on its first instruction is set and enabled (red-filled circle) as above. Please make sure this is the case before proceeding.
==Executing with breakpoints== -To execute, you will use the following Run buttons in the Project toolbar, or the corresponding entries in the Debug menu: +To execute, you will use the following Run buttons in the Project toolbar, or the corresponding entries in the Debug menu: [[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 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 . +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 : +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]] -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. -* Along with attributes, an Eiffel class may have '''once functions''', executed at most once -- the first time they are called -- in a given session, and from then on always returning the same value. Here the once function io has not yet been called, but when it is it will return an object of type STD_FILES . +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. +* Along with attributes, an Eiffel class may have '''once functions''', executed at most once -- the first time they are called -- in a given session, and from then on always returning the same value. Here the once function io has not yet been called, but when it is it will return an object of type STD_FILES. -The execution-time objects that you may display in an Object Editor are our latest kind of EiffelStudio "development object", along with classes, features, explanations, clusters; notice the distinctive icon, a rectangular mesh shape suggestive of an object's division into fields. It appears colored for actual objects and gray for Void references such as operating_environment. +The execution-time objects that you may display in an Object Editor are our latest kind of EiffelStudio "development object", along with classes, features, explanations, clusters; notice the distinctive icon, a rectangular mesh shape suggestive of an object's division into fields. It appears colored for actual objects and gray for Void references such as operating_environment.
==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: +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]] -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. +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. @@ -78,31 +78,31 @@ To see the details of the object, pick-and-drop its identifier in place (that is
==From the instance to the class== -Now try pick-and-dropping that same object, the instance of HEIR , to the Context Tool above the Object window. The effect is the same as if you had pick-and-dropped the '''class''' name HEIR : retarget the Context Tool to that class. +Now try pick-and-dropping that same object, the instance of HEIR, to the Context Tool above the Object window. The effect is the same as if you had pick-and-dropped the '''class''' name HEIR: retarget the Context Tool to that class. In the same way that you can drop a feature pebble into a tool that expects a class, you can also drop an object pebble, which will be understood as denoting the object's generating class. -Because the Context Tool is showing a class, it has switched to the default format for classes, Ancestors , and is showing the ancestors of HEIR . Click the Feature Tab of the Context Tool to set it back to feature information for the continuation of our debugging session. No feature is currently displayed. +Because the Context Tool is showing a class, it has switched to the default format for classes, Ancestors, and is showing the ancestors of HEIR. Click the Feature Tab of the Context Tool to set it back to feature information for the continuation of our debugging session. No feature is currently displayed.
==Stepping into and out of a routine== -Click Step-by-step once more to advance just before the call o1 . display . +Click Step-by-step once more to advance just before the call o1.display. -Choosing Step-by-step again would execute the next step in the current routine, the call o1 . display , treating the entire execution of display from class HEIR as a single operation. Assume instead that you want to go into that routine and follow the details of its execution. For one thing, you might not know that it's a routine of class HEIR , since o1 is declared of type PARENT and it's only through polymorphism, o1 being dynamically of type HEIR at this point, and through dynamic binding, that the execution ends up calling a routine from HEIR . Of course here it's obvious because of the wording of the create a few lines up, but in many cases, especially all those for which polymorphism and dynamic binding are really interesting, the exact type won't be immediately clear from the neighboring software text. +Choosing Step-by-step again would execute the next step in the current routine, the call o1.display, treating the entire execution of display from class HEIR as a single operation. Assume instead that you want to go into that routine and follow the details of its execution. For one thing, you might not know that it's a routine of class HEIR, since o1 is declared of type PARENT and it's only through polymorphism, o1 being dynamically of type HEIR at this point, and through dynamic binding, that the execution ends up calling a routine from HEIR. Of course here it's obvious because of the wording of the create a few lines up, but in many cases, especially all those for which polymorphism and dynamic binding are really interesting, the exact type won't be immediately clear from the neighboring software text. -Click the Step into routine button (or press F11). This brings execution to the beginning of the appropriate display routine in class HEIR . +Click the Step into routine button (or press F11). This brings execution to the beginning of the appropriate display routine in class HEIR. -You can also expand the Call stack pane on the left to see the full call stack, consisting here of only two levels. Minimize it to get the above display back. +You can also expand the Call stack pane on the left to see the full call stack, consisting here of only two levels. Minimize it to get the above display back. -Now click Step out of routine (Shift-F11) to finish the execution of display . This brings you back to the next instruction of the calling routine, make of TESTROOT . +Now click Step out of routine (Shift-F11) to finish the execution of display. This brings you back to the next instruction of the calling routine, make of TESTROOT.
==Terminating== -You may now click the Terminate button (Shift-F5) to end execution. The execution-specific tools go away and the display returns to what it was before execution. +You may now click the Terminate button (Shift-F5) to end execution. The execution-specific tools go away and the display returns to what it was before execution.
==Other debugging capabilities== -In this little application nothing runs long enough to give you the time to interrupt it. In a longer-running application you may want to interrupt execution, without necessarily terminating it, while it's running (not stopped on a breakpoint). This is the purpose of the Interrupt button (CTRL-Shift-F5). It will interrupt execution at the closest potential breakpoint position, letting you -- as when execution stops because of an exception -- take advantage of all the debugging and browsing facilities to see what's going on inside the program. You may then restart execution -- with or without breakpoints, single-stepping, out of the current routine, into the next routine -- by choosing the appropriate Run button +In this little application nothing runs long enough to give you the time to interrupt it. In a longer-running application you may want to interrupt execution, without necessarily terminating it, while it's running (not stopped on a breakpoint). This is the purpose of the Interrupt button (CTRL-Shift-F5). It will interrupt execution at the closest potential breakpoint position, letting you -- as when execution stops because of an exception -- take advantage of all the debugging and browsing facilities to see what's going on inside the program. You may then restart execution -- with or without breakpoints, single-stepping, out of the current routine, into the next routine -- by choosing the appropriate Run button In debugging sessions for more advanced applications, you will also find self-explanatory mechanisms enabling you, in addition to what we have seen, to examine all the objects on the "call stack": arguments and local entities of the current routine, its caller, caller's caller and so on. 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 d61a9275..36313a88 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 @@ -8,9 +8,12 @@ To complete this study of the compilation process let's see a few more propertie Our example system is very simple and has no need for execution arguments. In more advanced cases you may want to pass values to the execution, such as a numeric parameter or a file name, so that you can have different executions without changing and recompiling the software. -In the Eiffel text, you can access such run-time arguments through the Kernel Library class ARGUMENTS . There is another technique -- using the arguments to the root creation procedure -- but using ARGUMENTS is the most general way. Any class of your system can inherit from ARGUMENTS and use queries argument_count to know the number of arguments passed to the execution, and argument ( i ) , for i between 1 and argument_count to access the i -th element. Class ARGUMENTS has more features; since you have Eiffelstudio up, you can check the details if you wish (use the contract form). +In the Eiffel text, you can access such run-time arguments through the Kernel Library class ARGUMENTS. There is another technique -- using the arguments to the root creation procedure -- but using ARGUMENTS is the most general way. Any class of your system can inherit from ARGUMENTS and use queries argument_count to know the number of arguments passed to the execution, and argument (i), for i between 1 and argument_count to access the i-th element. Class ARGUMENTS has more features; since you have Eiffelstudio up, you can check the details if you wish (use the contract form). -There are 2 ways to specify execution arguments from within EiffelStudio. The first is through the Project --> Project Settings --> Debug/Profile --> Program Execution tab. The second is through the argument dialog which can be opened by right-clicking on any of the debugging or program execution buttons on the main toolbar. The latter is more convenient for quick and easy access to execution arguments. +There are 2 ways to specify execution arguments from within EiffelStudio. The first is through the menu path + +Project --> Project Settings --> Debug/Profile --> Program Execution +The second is through the argument dialog which can be opened by right-clicking on any of the debugging or program execution buttons on the main toolbar. The latter is more convenient for quick and easy access to execution arguments.
==Executing from EiffelStudio== @@ -19,20 +22,25 @@ We have seen how to execute a compiled system from within EiffelStudio: choose o ==Executing a finalized system outside of EiffelStudio== A finalized system can be executed on any computer of the appropriate platform; it doesn't need EiffelStudio. The executable version is in the directory - project_directory/EIFGENs/target_name/F_code + +project_directory/EIFGENs/target_name/F_code -where project_directory is the project's directory and target_name ist the name of the target. The name of the executable file is system_name .exe , where system_name is the name that you have assigned to your system in the project settings (reflected in the ECF file). +where project_directory is the project's directory and target_name ist the name of the target. The name of the executable file is + +system_name.exe +where system_name is the name that you have assigned to your system in the project settings (reflected in the ECF file). -The target of the Guided Tour system is classic and the name is simple , so you can locate simple . exe in EIFGENs/classic/F_code for your project, and run it stand-alone if you like. +The target of the Guided Tour system is classic and the name is simple, so you can locate simple.exe in EIFGENs/classic/F_code for your project, and run it stand-alone if you like. -If you run the system from a command line, and it requires arguments ( simple doesn't), you will provide the appropriate arguments after the command name: - system_name.exe ... arg ... +If you run the system from a command line, and it requires arguments (simple doesn't), you will provide the appropriate arguments after the command name: + +system_name.exe ... arg ... Because various platforms have different conventions, "relative paths" referenced in your system will mean something different under Unix/Linux, where they relate to the directory from which the command is launched, and under Windows, where they relate to the application's directory.
==Executing a frozen or melted system outside of EiffelStudio== -A system compiled in "Workbench mode" -- frozen or melted -- is normally meant for execution within EiffelStudio, not for outside delivery, since it is not optimized. If you need to execute it outside of EiffelStudio, make sure that you have access to the system_name . melted file in project_directory /EIFGENs/target_name/W_code . +A system compiled in "Workbench mode" -- frozen or melted -- is normally meant for execution within EiffelStudio, not for outside delivery, since it is not optimized. If you need to execute it outside of EiffelStudio, make sure that you have access to the system_name.melted file in project_directory /EIFGENs/target_name/W_code.
==Moving on== 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 a23fa698..90597bc7 100644 --- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/graphics-based-design.wiki +++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/graphics-based-design.wiki @@ -10,63 +10,63 @@ Many people like to use the graphical mechanisms at the beginning of a project,
==Displaying a cluster view== -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.) +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: +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]] ==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: +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]] -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: +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]] 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. +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. -For the rest of this discussion we assume INVALID is hidden. +For the rest of this discussion we assume INVALID is hidden.
==Adding a class== We are now going to add a class graphically to our system. This means you don't have to worry about creating and initializing a file; EiffelStudio will take care of the details. -The useful button here is New class . +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: +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]] -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. +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 : +The new class is now in the diagram, part of root_cluster: [[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. +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]] ==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: +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]] -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). +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]] -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 . +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 : +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]] @@ -74,55 +74,55 @@ This is EiffelStudio's way of telling us that these two classes, listed because
==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: +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]] -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 +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 + my_heir_not_void: my_heir /= Void -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 . +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 . +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]] -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. +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. +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, my_heir /= Void -- 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. -If you look at the end of the class, you will see an invariant clause listing the invariant that you have entered. +If you look at the end of the class, you will see an invariant clause listing the invariant that you have entered.
==Updating the diagram from the text== In this tour of the diagram facilities we have, so far, worked on the diagram and seen the text updated immediately. Of course we want full reversibility. So let's make a change in the text and check the diagram. -The change will be very simple. We'll make TESTROOT a client of HEIR . In the top Editing Tool, use the editor to add an attribute declaration +The change will be very simple. We'll make TESTROOT a client of HEIR. In the top Editing Tool, use the editor to add an attribute declaration - other: HEIR + other: HEIR 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. }} +{{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: +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]] -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. +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== 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: +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]] -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. +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: @@ -132,41 +132,41 @@ Make sure that the display looks approximately like the above; you may have to r
==Moving a class to a different cluster== -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 . +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: +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]] -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 . +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.
==Adjusting the display== -A number of buttons enable you to customize the display. So far all class bubbles had the same default color (yellow). Try pick-and-dropping a bubble into the Color hole to get a color palette that enables you to select a different color. This is useful if you want to highlight classes possessing certain properties, for example classes that are part of a certain Design Pattern. +A number of buttons enable you to customize the display. So far all class bubbles had the same default color (yellow). Try pick-and-dropping a bubble into the Color hole to get a color palette that enables you to select a different color. This is useful if you want to highlight classes possessing certain properties, for example classes that are part of a certain Design Pattern. - Relation depth enables you to select the depth at which inter-class relations will be displayed. (Don't change this setting now.) Extend to cluster is more useful for class diagrams than for the cluster diagram we have now, which by default included all classes of the cluster; if you click it here it will add the class INVALID that you removed earlier. There is no need to do this now. +Relation depth enables you to select the depth at which inter-class relations will be displayed. (Don't change this setting now.) Extend to cluster is more useful for class diagrams than for the cluster diagram we have now, which by default included all classes of the cluster; if you click it here it will add the class INVALID that you removed earlier. There is no need to do this now.
==Views== -So far the top-right View field has always shown DEFAULT . You can define any number of views in your project, and apply them to various class and cluster diagrams. +So far the top-right View field has always shown DEFAULT. You can define any number of views in your project, and apply them to various class and cluster diagrams. -For example, using the buttons to show and hide links of various kinds you can produce diagrams that only show the inheritance links, and others that only show the client links. If you want to keep both kinds of diagram, simply define views by typing view names -- such as Inheritance , Client , All_links -- into the View field. +For example, using the buttons to show and hide links of various kinds you can produce diagrams that only show the inheritance links, and others that only show the client links. If you want to keep both kinds of diagram, simply define views by typing view names -- such as Inheritance, Client, All_links -- into the View field. You can also use views to retain some of the choices seen just before, such as different colors and depths. -To load a previously defined view, just use the menu associated with the View field. +To load a previously defined view, just use the menu associated with the View field. You may remember that when we generated HTML documentation, the dialog asked you to select a view among the available ones. You can choose a different view for each cluster.
==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 : +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]] -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: +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]] 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 fb0fc980..ce9a5310 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 @@ -8,7 +8,7 @@ So far we have tried to make sure that everything went smoothly. But in actual s Let's remind ourselves first of how the language is specified. The book [http://www.eiffel.com/doc/ Eiffel: The Language] , the language reference, carefully distinguishes between three levels of description: '''syntax''', '''validity''' and '''semantics'''. Their roles are clearly distinct: * Syntax defines the structure of software texts. A typical syntax rule states that an assignment starts with a Writable entity, continues with the symbol :=, and ends with an Expression. This is a purely structural specification, saying nothing for example about the types of the Writable and the Expression. -* Validity, applicable only to syntactically legal texts, defines required consistency conditions. A typical validity rule states that in an assignment the right-hand-side Expression must conform -- a property of its type, defined rigorously on the basis of inheritance -- to the left-hand-side Writable. Eiffel has about 75 validity rules; part of the language's originality is that these rules are of the " if and only if " form, not only telling you individual error cases ("this is valid only if ... ") but also reassuring you that your text will in fact be valid if it satisfies the conditions listed exhaustively. +* Validity, applicable only to syntactically legal texts, defines required consistency conditions. A typical validity rule states that in an assignment the right-hand-side Expression must conform -- a property of its type, defined rigorously on the basis of inheritance -- to the left-hand-side Writable. Eiffel has about 75 validity rules; part of the language's originality is that these rules are of the "if and only if" form, not only telling you individual error cases ("this is valid only if ... ") but also reassuring you that your text will in fact be valid if it satisfies the conditions listed exhaustively. * Semantics, applicable only to valid texts, defines the software's expected run-time behavior. A typical semantic rule states that an assignment replaces the value of its left-hand-side Writable by the value of the right-hand-side Expression at the time the assignment is executed, with precise rules on the different possible cases involving references, objects and simple values. You may make an error at any of these levels: @@ -20,7 +20,7 @@ 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. +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]] @@ -30,7 +30,7 @@ You may wonder why the syntax error messages are not a little more verbose than
==A validity error== -A validity error is a violation of one of the validity constraints given in [http://www.eiffel.com/doc/ Eiffel: The Language] . Every such constraint is identified by a four-letter code of the form V XXX (the first letter is always V). +A validity error is a violation of one of the validity constraints given in [http://www.eiffel.com/doc/ Eiffel: The Language] . Every such constraint is identified by a four-letter code of the form VXXX (the first letter is always V). A validity error will produce a precise error message, which includes the validity code. Although short, the error message is usually sufficient to find out what the error is. If not, you can get the complete rule, straight from the book. @@ -48,9 +48,9 @@ Click Save, then Compile. Compilation starts but after 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. +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: +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]] @@ -70,7 +70,7 @@ As is often the case when dropping into a specific hole, you don't need to shoot 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. +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. To correct the error the easiest is to go back to class TESTROOT and reinstate the comment symbol -- (two consecutive dashes) on the erroneous line. Save and compile to continue with a valid system.
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 6bfcda9b..2a1863b9 100644 --- a/documentation/current/eiffelstudio/eiffelstudio-guided-tour/how-eiffelstudio-compiles.wiki +++ b/documentation/current/eiffelstudio/eiffelstudio-guided-tour/how-eiffelstudio-compiles.wiki @@ -16,11 +16,11 @@ There is never any need, when compiling Eiffel systems, to supply "Make files",
==Compilation modes== -EiffelStudio offers several forms of compilation, which you can see in the entries of the Compile menu (don't trigger any of them right now) as well as keyboard shortcuts and, in some cases, buttons: +EiffelStudio offers several forms of compilation, which you can see in the entries of the Compile 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 Project menu and through Tools --> Precompilation wizard ), to process an entire library, on which many systems can then rely without having to compile it. +* '''Precompile''' (available both in the Project menu and through Tools --> Precompilation wizard), 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.
@@ -36,7 +36,9 @@ EiffelStudio's '''Melting Ice Technology''' reconciles the following goals: 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: -{| + + +{| border="1" |- | | '''Small System''' @@ -51,16 +53,16 @@ The change may be big or small; the system may be big or small. ("Small system" | |} + 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 finalization, 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 '''
-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. }} +{{definition|Melting Ice Principle|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 '' ANY '', although this is an extreme case and won't normally happen. Since every class is a descendant of '' ANY '', the logical change may affect the entire 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 '' ANY'', although this is an extreme case and won't normally happen. Since every class is a descendant of '' ANY'', 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.'' @@ -77,7 +79,9 @@ The roles of the four compilation modes follow from this analysis: ==Properties of the compilation modes== The following table summarizes the differences between the four compilation modes: -{| + + +{| border="1" |- | | '''Regenerate C Code?''' @@ -99,17 +103,22 @@ The following table summarizes the differences between the four compilation mode | 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 Compile 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. +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 Compile 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:
[[Image:index-141]]
@@ -150,17 +159,20 @@ Melting is the bread and butter of the Eiffel developer. As you build your softw Only two operations, noted above, require 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 '' ANY '', 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.'' +''For the first compilation of a system that does not use precompiled EiffelBase, a Freeze is needed since class '' ANY'', 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 Project --> Freeze . You get the following dialog: +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]] -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. +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: +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: * 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 OpenVMS, in the window from which you launched EiffelStudio. @@ -182,6 +194,9 @@ As long as you continue changing, melting and freezing your system, the workbenc Note that cross-development does not require 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 Project --> Finalize . 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. +Finalize the example system now by selecting the menu entry + +Project --> Finalize +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.
diff --git a/documentation/current/eiffelstudio/eiffelstudio-reference/browsing-tools/windows-tool/window-list.wiki b/documentation/current/eiffelstudio/eiffelstudio-reference/browsing-tools/windows-tool/window-list.wiki index 8ed047f3..66a3a5b3 100644 --- a/documentation/current/eiffelstudio/eiffelstudio-reference/browsing-tools/windows-tool/window-list.wiki +++ b/documentation/current/eiffelstudio/eiffelstudio-reference/browsing-tools/windows-tool/window-list.wiki @@ -1,7 +1,7 @@ [[Property:title|Window list]] [[Property:weight|1]] [[Property:uuid|95058f0f-7c1b-841d-03df-dde4494afaf4]] -The window list is the main part of the [[Windows tool: Introduction|window tool]] . +The window list is the main part of the [[Windows tool|window tool]] . [[Image:windows-tool]]