Development with VisualWorks
VisualWorks Image
Topics on VisualWorks image files:
Save the image
Exit VisualWorks
Reclaim space in an image
Set the home directory for an image
Change global settings for an image
Prepare an image for application delivery
See also:
Launcher
Save the image
To save the currently running image, select File->Save As... in the Launcher window. A dialog prompts you for the name of the image, with the current image name as the default. To save the image to a different file, keeping the previously saved image safe, enter a new name, without the " .im " extension. If you choose a new name, VisualWorks will create a new changes file.
See also:
Recover changes
Exit VisualWorks
To end a VisualWorks development session, select File->Exit VisualWorks... in the Launcher window. A dialog prompts you to save the image before exiting. If you choose to save the image, you may provide a new filename.
Selecting Cancel continues your session.
Note that closing the Launcher window, for example by clicking the window's close icon, allows you to either exit VisualWorks, or simply close the Launcher window itself.
Reclaim space in an image
To invoke the
compacting garbage collector
, select System->Collect Garbage in the Launcher window. This will reclaim any unused data, sweeping all of the object memory except the zone called `Perm Space` .
To invoke the
global garbage collector
, select System->Collect All Garbage in the Launcher window. This will reclaim any unused data, sweeping all of the object memory including the zone called `Perm Space` .
Set the home directory for an image
To set the default "home" directory for the current image, select File->Set VisualWorks Home... in the Launcher window. A dialog box appears, in which you should enter the path to the directory that contains the current image.
The VisualWorks home directory path may be referenced using the parameter `$(VISUALWORKS)` . This parameter is used to locate the system sources and changes file, as well as parcels that can be loaded. Make sure you supply the name of the main directory, of which image , parcels , and bin are sub-directories.
Change global settings for an image
To open a Settings Tool for the current image, select System->Settings in the Launcher window.
See also:
Environment Settings
Prepare an image for application delivery
By selecting File->Perm Save As... in the Launcher window, you can create an image file with all `Old Space` objects moved into the zone called `Perm Space` . The newly created image will execute subsequent garbage collections more efficiently.
You may use the Runtime Packager to strip an image for deployment or delivery. For details, see the VisualWorks Application Developer's Guide .
Files
Topics on working with files:
Get the home directory
Navigate through a directory hierarchy
Create a new directory
Editing files
Load source code from a file
See also:
File Browser
Get the home directory
To display the VisualWorks home directory in a File Browser, click on Go to Default on the Directory menu.
See also:
Set the home directory for an image
Navigate through a directory hierarchy
To descend into a subdirectory shown in a File Browser, simply double-click on a directory name. Alternately, you can select a directory, and choose new pattern on the <Operate> menu. To move to a higher level in a directory hierarchy, edit the text in the pattern field (upper-right) and press <Return>.
Create a new directory
To create a new directory using a File Browser, click on Create... on the Directory menu.
Editing files
To open a Workspace for editing the contents of a text file, select the file name in the names (upper-right) view of a File Browser, and select Edit from the File menu.
Load source code from a file
To load and compile the contents of a source code (extension " .st ") file or a parcel (extension " .pcl "), choose the file in the File Browser's list view and select File in... or Load... on the <Operate> menu. The contents of the file will be loaded into the current image.
Environment Settings
Topics on Environment Settings:
Open the Settings Tool
Set the look of the user interface
Enable tools for globalization
Set the feel of the user interface
Set the placement of windows
Set a limit on the length of icon labels
Set the default text attributes
Platform-specific printing options
Set options for browsing
Set source and changes files
Set source directories
Set options for parcel loading
Set the local time zone
Set message catalogs for internationalization
Set XML source code option for file-out
Open the Settings Tool
The Settings Tool allows you to control a variety of global parameters, including the appearance of windows, source file name, and the default font for text. To open the Settings Tool, choose System->Settings in the VisualWorks Launcher window.
Use the scroll buttons and tabs on the right-hand side of the Settings window to navigate among the pages.
Set the look of the user interface
On the UI Look page of the Settings Tool, use the Look Selection menu to change the default appearance and behavior of buttons, scroll bars, and other widgets. The new look will apply to any window that you open subsequently. Select Basic Tools Adopt Look to make programming tools such as code browsers also adopt the new look. To let VisualWorks adopt the look that is most appropriate for your operating environment, use Auto Select in the Look Selection menu.
To affect the look of a single canvas while you're editing it, use the Canvas tool.
Use the Host Window System setting to tell VisualWorks which window manager you are using. This setting insures that windows can be placed correctly when they are opened automatically.
See also:
Set the feel of the user interface
Set user interface options
Set user interface options
On the UI Options page of the Settings Tool, use the Page Style setting to control multi-page Settings and Property Tool displays.
To immediately see the choices in Property Tools by swapping pages using notebook tabs, select Use Notebook Paging .
To obtain a more compact representation, select Use Menu Paging ; the latter allows page selection through a menu and is recommended when screen real estate is at premium. The Page Style setting affects Settings and Property Tools the next time they are restarted.
Enable tools for globalization
On the UI Options page of the Settings Tool, use the Show UI for Globalization setting to enable fields for support of globalization. When this option is enabled, the GUI Painter Tool will show special fields such as keys for message catalogs.
Set the feel of the user interface
To select the platform feel that you want text editors (including browsers) to have, select the UI Feel page in the Settings Tool and choose an option from the Feel Selection menu.
You may add your own feels by subclassing from `UIFeelPolicy` and providing your own keyboard bindings in the class. Subclasses of `UIFeelPolicy` must provide a class method called `menuName` that returns a string of what you want the new feel to be named.
See also:
Set the look of the user interface
Set user interface options
Set the placement of windows
On the Window page of the Settings Tool, select User placement to allow the user to position newly created windows.
To open newly created windows at a default size, and position them under the current mouse position, select Automatic placement .
Set a limit on the length of icon labels
On the Icon page of the Settings Tool, adjust the Icon Label Length setting to constrain the length of icon label text.
Set the default text attributes
VisualWorks keeps a set of global text attributes which you may adjust on the Text page of the Settings Tool. To change the attributes used to render text in the various environment tools, select one of the following:
small
This will select text that is slightly smaller than "default", useful for small displays on the order of 640x480 pixels
default
The usual style, suitable for 1024x768 displays
large
A slightly larger style, for 1600x1280 hi-res displays
fixed
Similar to "default", but all characters are the same size--this is useful for presenting table-oriented data or in a terminal emulator
To redefine the default text attributes press the corresponding radio button, and select Accept .
Platform-specific printing options
Select the Printing page in the Settings Tool.
Use the Document Printing options to choose between PostScript and Host printer drivers (the latter are supported only on MS-Windows platforms). If Host Printing is selected on a non-Windows platform, the system will default back to PostScript at print time.
Use the Text Printing options to choose how hardcopy commands (i.e., in browser code views) are handled. To make hardcopies via the Document system, select Document Printing ; to save hardcopy as a disk file (named temp.prt by default), select Plain Text Printing .
Set options for browsing
Select the Browsing option in the Settings Tool to set options.
To control the default action of the Browse -> Class Named... command in the Launcher window, use the Class Browsing setting. To open a hierarchy browser on the specified class, all of its subclasses and superclasses, select Use Hierarchy Browsers ; to open a class browser on the specified class, select Use Class Browsers .
To change display options for the System Browser, change the Show Namespaces , Show Parcels , and Show Packages switches. Enabling these options will add multi-fuction tabs and additional menu options to the System Browser. These options also affect the evaluation of the `browse` message (e.g., `Collection browse` .)
See also:
System Browser
Open the Settings Tool
Set source and changes files
Select the Source Files option in the Settings Tool to change the name of the system sources or changes files.
By default, both the sources " .sou " and changes " .cha " files reside in the image directory. In a networked environment, users normally share the same sources file and have a private changes file. To establish such a configuration, either add a new sources file path and click on Accept ; or else select an option from the scrollable list, edit the field to contain the absolute path name of the shared sources file, and click on Change .
To keep the changes file in a location other than the startup directory, select changes file " .cha ", and insert the appropriate path and file name.
When you make a backup copy of a VisualWorks image, three files must be archived together: the image file, the sources file, and the changes file.
See also:
Open the Settings Tool
Set source directories
VisualWorks Image
Set the home directory for an image
Set source directories
Select the Source Dirs option in the Settings Tool to change the directories where system and parcel source files are located.
To add a new sources path, enter the path in the field below the scrollable list and click on Accept . To modify an existing path, select it in the scrollable list, edit the field, and click on Change .
See also:
Set source and changes files
Set the home directory for an image
Set options for parcel loading
Select the Parcel Path page in the Settings Tool to set parcel loading options.
To reference the VisualWorks home directory, use the parameter `$(VISUALWORKS)` . If a parcel has prerequisite parcels, they will be searched for in the directories and in the order specified in this list. The period character " . " is used to indicate the directory in which the current parcel is being loaded from, not the directory in which VisualWorks is running. Use " . " to search for a parcel's prerequisites in the same directory as the parcel.
See also:
Managing Parcels
Set the local time zone
Select the Time Zones page in the Settings Tool to display options for setting your local time zone.
Select an expression that corresponds to your local time zone and evaluate it using Do It on the <Operate> menu. Note: you must select inside the single-quote marks to evaluate the expression properly.
Set message catalogs for internationalization
Use the Messages page of the Settings Tool to specify directories containing message catalogs for internationalization.
The list view specifies which directories contain message catalog files. These directories contain a collection of subdirectories, where each subdirectory is given a name that identifies the language group for which it is intended. Message catalog files for specific languages are located in these subdirectories.
To add a directory, type the directory's name into the input field, and press the Add button. To delete a directory, select it in the list and press Delete . To change a directory, select it in the list, change the name which appears in the input field, and then press Change .
Use Accept to finalize, and Reset to revert your changes.
Set XML source code option for file-out
Use the File-out Type page of the Settings Tool to specify use of XML formatting for source code files saved with File Out .
In VisualWorks 5i, sources are stored using XML. For compatibility with previous versions of the system, or to share code with developers not using VisualWorks 5i, you should set this option to Smalltalk chunk source code .
System Transcript
Topics on the System Transcript:
Display text in the Transcript view
Display text in the Transcript view
To display some text in the Transcript, evaluate the following Smalltalk expressions:
Transcript show: 'Hello World' printString; cr.
To perform these steps, open a Workspace window (select Tools->Workspace in the Launcher window), and type these expressions in it; next, select the entire text (using the <Select> button), and click and hold the <Operate> button with the cursor in the Workspace. Move the cursor to select Do It , and release the mouse button. The text will display in the Transcript.
Transcript
is a global variable, and refers to an instance of the class `TextCollector` , where you will find other useful Transcript behavior.
Changes and Change Sets
Topics on the ChangeList Tool:
Open a change list tool
View groups of changes
View specific changes
Filter the list of changes
Examine the evolution of a change
Manage the list of changes
Cull the list of changes
Recover changes
Condense the system changes file
Examine the evolution of a change
Revert to a prior version of a change
Topics on Change Sets:
Open a Change Set Browser
Create a new change set
Browse specific change sets
Save the contents of a single change set
Empty a change set
See also:
Change List
Change Set Browser
Open a change list tool
To open a new Change List, select Tools->Change List in the VisualWorks Launcher window.
View groups of changes
To load and display the changes that have occurred since the last snapshot was taken, select file in/out->recover last changes in the <Operate> menu of the list view at the top.
To load and display changes that are in the current Change Set, select file in/out->display system changes .
To view the contents of a file-in (or a group of file-ins) as a collection of changes, select file in/out->read file/directory... and supply the name of the file at the prompt.
To view the contents of a loaded parcel as a collection of changes, select Display Parcel... on the File menu, and choose the name of a parcel in the dialog box.
To display all changes saved, ignoring snapshot boundaries, select file in/out->read file/directory... from the <Operate> menu, and supply the name of the changes file ( image .cha ).
Changes from different sources can be loaded and viewed simultaneously in a single Change List.
View specific changes
Entries in the Change List generally identify both the affected object and the nature of the change. For example, the list entry `NotifierController menu (add)` indicates that the method named `menu` was added to class `NotifierController` .
When you select an entry, the code for the affected class or method appears in the lower text view as it existed after the change.
Filter the list of changes
Use the switches in the upper right region of the Change List to filter the displayed list of changes.
Change List filter switches:
file
Display only entries that are recorded in the same disk file as the selected entry.
type
Display only entries of the same type as the selected entry (for example, all doIts, which represent executed expressions).
class
Display only entries that affect the same class as the selected entry.
protocol
Display only entries that affect a class or message in the same protocol as the selected entry.
selector
Display only entries that involve the same message selector as the selected entry.
same
Display only entries that have the same type as the selected entry and affect the same class or method. Although the entries in the change list appear identical, the underlying code may be different for each entry. Use this switch to examine the evolution of a change.
Examine the evolution of a change
With the same filter turned on, you can examine the evolution of a class, method, or protocol. Typically, this filter is used to examine the evolution of a single class or a method, but it can be used to filter any type of change.
See also:
Filter the list of changes
Revert to a prior version of a change
Manage the list of changes
By default, the Change List automatically compares the displayed changes against the corresponding methods in the image, emphasizing the list elements to indicate differences. Elements marked with italics are the same as the current definition in the image; this is indicated with the text (same) . Elements marked in bold do not match their corresponding definitions in the image; this is indicated with the text (changed) . This emphasis can be enabled or disabled by selecting the Conflicts->Emphasize in list command on the Show menu.
Once you have loaded a particular set of changes into the Change List, you can shorten the list either by filtering or by culling the list. Use the filter switches to show only changes made to a specific class, method, or protocol.
See also:
Filter the list of changes
Cull the list of changes
To pair down the list of displayed changes, mark those item(s) to be deleted by choosing remove selection or remove all from the <Operate> menu, and then forget . To un-mark item(s), choose either restore selection or restore all . Note that the forget operation does not permanently affect the system Change Set.
As a short-cut, you can also mark an item for removal by double-clicking on the list entry; items marked for removal are display is struck text. Double-clicking on the item a second time will restore it to the list.
See also:
Open a Change Set Browser
Recover changes
To display the changes that have occurred since the last snapshot was taken, select file in/out->recover last changes on the <Operate> menu of the list view in the top-left region of the window.
When recovering from a system failure, you must eliminate any changes that may have contributed to the crash.
To cull unnecessary entries such as doIts, edit the displayed list.
To delete all doIts, which are usually unnecessary for recovery purposes, select any doIt in the list view and select the type switch.
Choose remove all in the <Operate> menu to mark all the doIts for deletion, then select forget to clear them from the list.
Deselect the type switch to display the remaining changes.
When the displayed list contains only the desired changes, select replay all->from top in the <Operate> menu.
Condense the system changes file
In a large development effort spanning months or years of programming, the changes file can become very large. To condense it so that it contains only the most recent change for each method, select Changes->Condense Changes from the Launcher's System menu. Changes involving anything other than a method -- such as a class addition or redefinition -- will also be purged from the file permanently. It's a good idea to make a backup copy of the changes file before condensing it.
Examine the evolution of a change
With the same filter turned on in a Change List, you can examine the evolution of a class, method, or protocol. Typically, this filter is used to examine the evolution of a single class or a method, but it can be used to filter any type of change.
See also:
Filter the list of changes
Revert to a prior version of a change
Revert to a prior version of a change
Use the same filter to see the evolution of the particular change you want to revert. To revert the code to a prior version, select the entry representing that version and then select replay selection in the <Operate> menu. You can also use the options under replay all , when you want to incorporate all of the listed changes. The menu item replay all->from here will revert every change listed from the current selection to the end of this list, while replay all->from top will revert every change in the list. Note that any change entries marked for removal will not be reverted. If an exception occurs during the replay, the selection is left at the item which caused it.
Open a Change Set Browser
Change sets are listed in the Project Browser window. To open the browser, select Changes->Change Sets from the Launcher's System menu. To browse the changes in a particular change set, select the change set then select Browse in the <Operate> menu. This will open a separate Change Set Browser.
Create a new change set
To create a new change set, open the Project Browser in the Launcher window (select Changes->Change Sets from the System menu), and in the new Browser, select Add... from the ChangeSet or the <Operate> menu. Enter a name for the new change set in the prompter dialog, and click OK .
To make this the current change set, select it so it is highlighted. All subsequent changes will be recorded to this change set.
Browse specific change sets
To browse the changes in a change set, select the change set in the Project Browser, then select Browse in the ChangeSet or <Operate> menu.
Unlike the Change List, the change set browser does not show the evolution of changes. Instead, change sets are used to organize groups of changes. The Change Set Browser lists the affected parts of the system so you can use the File out as... command to store your work in a set of disk files.
Save the contents of a single change set
Use File out as... in the left view's <Operate> menu. To file out all projects into a directory, use File out all... .
Change sets only keep track of the parts of the system that have been modified. Unlike Change Lists, change sets do not keep track of the evolution of changes.
Empty a change set
To empty the active change set, in readiness for a new batch of work, select Empty... in the <Operate> menu.
Team Development
Topics on Team Development:
Strategies for sharing code
Integrate code
Remove multiple versions of a change
Identify conflicts
Identify conflicts using source or code analysis
View conflicts
Identify conflicts in file-Ins
Create a conflicts file
Strategies for sharing code
When the code you want to share consists of fragments from many different classes and categories, use the Change List to create a single new file with the desired code.
Load all changes you want to export, using file in/out->display system changes .
Remove all irrelevant changes. For example, `doIts` are likely candidates for removal because they rarely affect the image in a lasting way.
Remove duplicate entries, e.g., when a method has undergone several changes -- leave only the last entry in each case. Use remove selection and remove all in the <Operate> menu to mark one or more changes for deletion, then use forget to erase them from the list. Use the filter switches to control the affected range of entries.
To remove all `doIts` , begin by selecting any `doIt` . Then turn on the type switch so all of the `doIts` are listed. Select remove all in the <Operate> menu to mark them for deletion, then forget to erase them. Then turn off the type switch to see the remaining entries.
When the displayed list of changes is the desired set you want to save, select file in/out->write file... in the <Operate> menu and supply the name of a file in which to store the code.
Only the displayed changes are included in a write file... operation, so if it is possible to define the minimum set of changes by using the filter switches alone, it is not necessary to remove and forget the nondisplayed entries.
NOTE: When you write selections to a file, be sure to choose a file name that is different from any file that has been read into the change list. The change list maintains pointers to the code in the files that are read in, and these pointers become invalid when you overwrite a file.
Integrate code
Integrating code into the system typically involves cross-checking between several source files, or between source files and the current image.
To integrate code that you believe to be compatible with the current image, load all the different sources into a Change List, and then select Remove->Conflicts , followed by Remove->Exchange removed . This produces a list of any definitions that may conflict between different source files.
To check code that you are not sure is compatible with the current image, use Read different source from file/directory... on the File menu.
To create a list of changes necessary to co-ordinate a file-in with the current system, use Build script to system on the Conflicts menu. A new Change List window will be opened with the changes necessary to make the changes correspond to the current system. The resulting changes can be used as a script to co-ordinate the current system with a foreign (deficient) system.
See also:
Identify conflicts
Remove multiple versions of a change
To remove all older, conflicting changes in the Change List, use Old Versions on the Remove menu. Only the latest version of each change will not be marked for removal. Conflicts are determined by comparing only the successive items in the list--not the actual source code.
To remove any duplicate changes from the list of changes, select Exact Duplicates on the Remove menu. Only the latest version of each change will not be marked for removal. The duplicates are identified using a full source comparison.
With both Old Versions and Exact Duplicates , if there is a selection in the list, only conflicting changes that occur before the selected item will be removed. If the left-shift key is pressed while selecting the menu action, then only items later in the list will be removed. With the left-shift key down, the direction of scanning for duplicates will be reversed, so that the first item is the "latest.")
Identify conflicts
To remove all items in the list of changes that conflict with other changes in the Change List (even if they're duplicates), use Conflicts on the Remove menu. Only the elements in the list will be checked for conflicts--not the corresponding source code.
To view the specific conflicts in a new window, use Conflicts on the Remove menu, followed by Exchange removed , followed by Find->Spawn all . This will open a new window, in which you can use forget to reduce the list to show only the conflicting definitions.
See also:
Remove multiple versions of a change
Identify conflicts using source or code analysis
To remove all items in the Change List that conflict with the definitions in the current image, use the Different source to system or Different code to system commands on the Remove menu. These two commands scan all the items in the list of changes as follows:
To perform a full source comparison against definitions in the system, use Different source to system . Using full source text comparison, any definitions with changes to formatting or comments will be marked for removal.
To perform a code analysis comparison against definitions in the system, use Different code to system . With the code analyzer, changes to formatting or comments will be ignored, and only methods with code changes will be marked for removal. Note that although names of temporary variables are often considered part of the source, they are treated as code changes by this analysis.
To remove all methods in the list of changes that do not conflict with the system, use the Same code as system or Same source as system commands on the Remove menu.
Note that Different... and Same... commands only compare items that correspond to definitions in the system.
See also:
Integrate code
View conflicts
To view differences between the code for a method in the Change List and the definition in the current image, select Show conflicts on the Show menu. This command splits the lower view of the Change List window to display two parallel panes. When this option is enabled, it is possible to see a source-level or code analysis of conflicts between methods. To toggle between the different types of analysis, select Conflicts->Source differences and Conflicts->Code differences on the Show menu.
Identify conflicts in file-Ins
To identify conflicting methods in a source file (or group of source files) displayed in the Change List, select Read different source from file/directory... on the File menu. This command will build a list of changes using only those definitions in the source file which differ from the system. A full source text comparison is performed, so any changes to formatting or comments will be flagged, and the corresponding methods or classes will be added to the list of changes.
If you want to perform this operation using code analysis instead of raw source comparison, select Read different code from file/directory... on the File menu. Changes to formatting or comments will be ignored, and only methods or classes with code changes will be added to the list of changes. Note that although names of temporary variables are often considered part of the source, they are treated as code changes by this analysis.
These commands are equivalent to file in/out->read file/directory... , followed by Same... .
See also:
Integrate code
Create a conflicts file
To locate places where the same method or class is affected in the Change List, use the conflicts->check conflicts, save as... command on the <Operate> menu in the upper-left view. Every duplicate entry in the change list will be checked, and all versions of the conflicting code are then saved in the designated file. This command can be used to identify conflicts when you are integrating code from multiple files.
To perform a similar conflict-check between the list of changes and the corresponding definitions in the current image, use the conflicts->check with system, save as... command.
See also:
Integrate code
Inspecting Objects
Topics on the Inspector:
Inspect a composite object
Modify an object using the inspector
Using specialized inspectors
Trace references to an object
See also:
Inspector
Inspect a composite object
To inspect objects composed of many elements, select the element in the left-hand view and use either inspect or dive in the inspector's <Operate> menu. Inspect opens a new inspector. Dive shows the selected object in the current inspector, reducing the number of windows cluttering your screen. Dive can also be invoked by double-clicking on an element in the left-hand view of the inspector. To back out of a diving inspector, select pop in its <Operate> menu; to back out to a specific layer in the object's graph, select utils->history and choose from the list of layers you have previously inspected.
Modify an object using the inspector
To change the value of a variable, enter a new value in the code view and select accept in the view's <Operate> menu.
Using specialized inspectors
Use specialized inspectors for dictionaries, and other collections. To override this behavior and inspect objects with a simple inspector, use the message `basicInspect` .
Trace references to an object
To identify the path of references from any object to a global in the `Smalltalk` dictionary, select a field in the left-hand view and choose utils->reference path in the inspector's <Operate> menu. This will open a new inspector showing an ordered list of all the objects in the reference path to the object in the selected field, with the global object at the top of the list.
Note: this command is available only when the Advanced Tools parcel ( AllAdvancedTools.pcl ) is loaded.
Debugging Techniques
Topics on Debugging:
Opening a Debugger window
Reading the execution stack
Inspect and change a variable
Insert a status message
Capture the stack for a bug report
Interrupt a program from the keyboard
Halt execution programmatically
Setting a breakpoint
Setting a variable watchpoint
Setting an expression watchpoint
Removing probes
Making a probe conditional
See also:
Debugger
Notifier
Opening a Debugger window
A Debugger window opens immediately when a breakpoint or self halt is encountered in the code, or when the user interrupts processing by pressing Ctrl+Y .
An error notifier window opens when an error condition is encountered. From the notifier, open the Debugger by clicking on the Debug button.
See also:
Capture the stack for a bug report
Reading the execution stack
Reading the execution stack
The Debugger displays the execution stack with the most recent message send at the top. The first line of the execution stack is often only of marginal interest, because it usually represents the method that handles the error --you must read around it to identify the cause of the error.
To double the amount of execution stack displayed, select the Stack / Show More menu item. This will allow you to trace the problem backward (down the list of contexts.) You may change variables, edit the method, restart, or else single-step execution.
Examples:
In the following line from the execution stack:
theNameSpace.theClass>>theMethodName
theNameSpace
is the namespace in which `theClass` belongs
theMethodName
is the name of the instance side method of `theClass`
In the following line from the execution stack:
theNameSpace.theClass(theParentClass)>>theMethodName
the method `theMethodName` is the name of the method defined in the parent class (`theParentClass` ) of `theClass` .
In the following line from the execution stack:
theNameSpace.theClass class>>theMethodName
theMethodName
is the name of the class side method of `theClass` .
See also:
Notifier
Inspect and change a variable
Inspect and change a variable
The bottom of the Debugger window is devoted to two inspectors that allow you to see the values of variables as they exist at the chosen point in the execution stack.
To inspect instance variables, use the inspector on the bottom left. To inspect temporary variables in the selected context, use the bottom right inspector.
To change the value of a variable and then restart the program, select the variable from the appropriate list, and edit its value in the right-hand part of the inspector. Then select Accept in the <Operate> menu. To begin execution from the beginning of the method, select Restart in the stack view menu.
Insert a status message
To have your program display status messages during the debugging phase, edit your code to use the System Transcript as a status log.
To send output to the System Transcript, insert expressions such as the following in your code, substituting a pertinent object name for the italicized word:
Transcript show: anObject printString.
Transcript cr.
Transcript tab.
Transcript show: 'Checkpoint 1'; cr.
To avoid an update of the display with each part of a larger message, use `nextPutAll:` or `print:` , then use `endEntry` to output the message, as in:
Transcript nextPutAll: 'The account is: '; print: account; endEntry.
To clear the Transcript for a new batch of messages, select Cancel in the Transcript <Operate> menu. Alternatively, execute the expression `Transcript clear` .
The System Transcript is a distinguished instance of the `TextCollector` class. For more transcript output messages, browse the instance methods of that class.
Capture the stack for a bug report
Use the Stack / Copy Stack Report command to copy the contents of the stack view into the paste buffer as a block of text. You can then paste the stack text into a file.
Interrupt a program from the keyboard
Type the
user interrupt
key sequence: <Control>-y. Enter this key sequence when you want to freeze a program that is looping endlessly, or to capture its state at a specific observable stage.
User interrupts generate the usual error notifier, which can be used to open a Debugger.
See also:
Notifier
Capture the stack for a bug report
Halt execution programmatically
You can cause program execution to be interrupted during execution by inserting either a breakpoint probe or the Smalltalk expression `self halt` in a method at the location where you want execution to be interrupted. This can be done by editing code either in the Debugger or in a System Browser. The next time that method is called, the Debugger will will open at the specified point.
See also:
Notifier
Setting a breakpoint
Capture the stack for a bug report
Setting a breakpoint
A simple breakpoint is set in a method definition by placing the cursor at the point at which you want to interrupt processing, and then selecting Insert Breakpoint from the <Operate> menu. The character at the cursor location is highlighted, indicating the breakpoint.
A breakpoint can also be made conditional. To do this, select Insert Probe instead of Insert Breakpoint . Then, in the Select Probe Type dialog, select the Breakpoint radio button and check the Conditional check box. Refer to "Making a probe conditional" below for further information.
Setting a variable watchpoint
A watchpoint displays a message in a watch window without interrupting processing, as does a breakpoint.
To set a variable watchpoint, place the cursor in a method definition, and select Insert Probe in the <Operate> menu. In the Probe Type editor, select the Variable Watch radio button.
Then click Done . The Select Watch Variable dialog opens.
The three buttons allow you to specify what variable to watch. You can only specify one. Top of Stack will display in the watch window the value on the top of the argument stack, which is either a message argument or response. The Instance Variable and Temp Variable buttons pop up a list of available variables ( Temp Variable is active only if the method has temporaries).
When you have selected the variable to watch, click Done . The probe is set, and the watch window opens the first time the probe is triggered.
Setting an expression watchpoint
A watch expression provides a good deal of control over the display of information. The expression must evaluate to a String, which you must ensure in the expression, since the default `debugString` method is not applied.
To set a variable watchpoint, place the cursor in a method definition, and select Insert Probe in the <Operate> menu. In the Probe Type editor, select the Variable Watch radio button.
Then click Done. The Expression Watch Probe editor opens.
The expression watch provides maximum probe control, so the editor provides all of the editors. The top text box, the Conditional Test Expression editor, is described below under "Making a probe conditional". The Window ID text field and associated buttons allow you to select the watch window in which to display the watch expression.
The Watch Expression text box is where you specify what to display in the watch window. The expression can be any Smalltalk expression that returns as a `String` . This allows you to include descriptive text, values of Smalltalk expressions, and some formatting. For example, you could use an expression like this to display the value of `currentRandomValue` from the Walk Through:
^'The current value is: ', currentRandomValue value printString, '. '
Carriage returns included in the string are displayed as carriage returns, or you can include a backslash and send withCRs to the whole string:
^'The current value is:
', currentRandValue value printString, '.'
When you've entered an appropriate expression, accept the change and click Done . The probe is set, and the watch window opens the first time the probe is triggered.
Removing probes
You can remove probes either selectively or from an entire method.
To remove a single probe, select its highlighted character and select Remove probe / Selected .
To remove all probes from the method, select Remove probe / All .
Making a probe conditional
A conditional breakpoint interrupts processing at the set point only if the specified condition is met. To place a conditional breakpoint, place the cursor and then select Insert Probe from the <Operate> menu. The Select Probe Type editor opens.
Leave the Breakpoint radio button selected, and check the Conditional check box. Click Done. The Conditional Text Expression probe editor opens.
Initially the expression is simply `false` , which will prevent the breakpoint from triggering. You need to replace this with an expression that will evaluate to `true` in just those cases where you want the breakpoint to trigger, allowing you to further investigate the state.
For example, in `RandomNumberPicker` from the VisualWorks Walk Through, you could insert a breakpoint in the `nextRandom` message, and set the conditional expression to:
currentRandomValue value < 0.5
to break only when the random value is smaller than .5.
When you have entered the expression, accept the change (Accept on the <Operate> menu), and click Done . The probe highlight is placed and the probe is set.
A probe expression is a normal Smalltalk expression, except that it has additional variable scoping. This scoping permits the expression to reference variables in the probed method context and instance variables of its receiver. Additionally, each probe may refer to its own local debug variables and to global debug variables. Menu commands are available in the condition editor pane to define new variables.
There are two predefined variables that you can reference to access information in the context where the probe activation occurs: `DOITCONTEXT` and `TopOFStack` . The variable `DOITCONTEXT` holds the context itself, and `TopOFStack` is the object on the top of the context stack. An additional predefined variable, `ThisProbe` , holds probe state information, such as its `characterIndex` . This is useful when constructing an expression watchpoint that reports method selector or probe character position.
When a probe is created, it is given a default conditional expression. Initially, this expression is set to `^DebugActive` . `DebugActive` is a global debug variable, and is used to permit enabling and disabling of probes using the Probes menu in the Visual Launcher.
The default expression can be changed by editing the class method `newDefaultMethodFrom:inClass:` in class `CodeProbe` .
The conditional expression editor text view has the following commands to assist in building expressions:
Insert var
Opens a series of menus and submenus containing all the valid local variables, providing a convenient means to locate a variable name and insert it into the text. The selected variable is inserted into the text.
Define debug var
Allows the user to define debug variables, both local and global.
Inspect debug vars
Opens a dictionary inspector on either the local or global debug variable dictionary. The actual dictionary inspected is determined by the submenu item selected, local or global .
Reset method
Resets the expression to a standard expression and method. Using a standard method can speed up insertion of multiple probes, when inserting probes using the Message Received or Instance Variable Reference panels, and probe expression recompilation, as a result of a class redefinition. This is because these standard expression methods are known to the system and do not require rebinding.
Insert expression
Displays a menu of expressions currently in the expression library. The selected expression is inserted at the text insertion point.
Save expression
Prompts the user for a name to identify the expression, and then saves the expression text in the expression library. There is one library for the Test expression and another library for the Watch expression.
Managing Parcels
Topics on working with parcels:
Open a Browser for viewing parcels
Create a new parcel
Add a definition to a parcel
Remove a definition from a parcel
Save a parcel
Load a parcel
Unload a parcel
Browse dangling references
Browse unparcelled methods
Browse a parcel's prerequisites
Browse overridden extensions
Define a pre-load action
Define a pre-save action
Define a post-load action
Define a pre-unload action
See also:
System Browser
Open a Browser for viewing parcels
Open a new System Browser ( Browse->System in the Launcher window) and set the browser to view parcels loaded into the current image by choosing Browser->Parcel from the browser's menu bar.
Create a new parcel
To create a new parcel, select Parcel->New... from the Browser's menu bar.
Add a definition to a parcel
To add an existing category, class, protocol, or method to a parcel, select the item to be added using the browser's navigator. Then choose Parcel->Add to and specify the target parcel.
Remove a definition from a parcel
To remove any category, class. protocol, or method definitions, select the item in the Browser and then choose Remove from from the Parcel menu.
Save a parcel
To save a parcel from the Browser:
Select Parcel->Save .
In the parcel save dialog, enter the name of the parcel file. Do not add the " .pcl " extension--VisualWorks will append it to the name.
To save sources in a " .pst " file, check the save source file box.
To cause the sources to be hidden when the parcel is subsequently loaded into an image, check the hide source on load box.
Select republishing options, and click OK .
Load a parcel
Use the Browser's Parcel->Load command to load a parcel from the search path, and select a parcel from the pop-up list.
See also:
Set options for parcel loading
Unload a parcel
To unload a parcel, select it in the Browser's parcels view and choose Parcel->Unload .
Browse dangling references
To generate a report of dangling references, select a parcel in the Browser's parcels view, and choose Parcel->Browse...->Dangling references . The generated list shows methods that are not in the parcel but reference a class that is defined in the parcel.
Browse unparcelled methods
To browse the set of messages sent from within the selected parcel and nowhere else in the image, select the Browser's Parcel->Browse...->Unparcelled methods used exclusively command.
To browse methods in classes defined by the selected parcel but not called from within the parcel, select Parcel->Browse...->Unparcelled methods defined in classes .
Note: these operations take some time to execute.
Browse a parcel's prerequisites
Use the Browser's Properties code tool to display the prerequisites of the selected parcel.
To compute the parcel's prerequisites, click on the Compute prereqs button.
Browse overridden extensions
To browse a parcel's overridden extensions, use the Browser's Parcel->Browse->Overridden extensions command. This opens a Change List in conflicts mode, displaying previous versions, and a Method List Browser displaying the current versions.
Define a pre-load action
Select the parcel in the Browser's parcels view.
Select the Properties code tool.
Choose the Pre-load Action page in the properties tool, and edit the block.
Click Apply to finalize the action.
Define a pre-save action
Using the Browser, select the parcel and the class in which to define the method.
Select the Properties code tool.
Choose the Pre-save Action page in the properties tool, and edit the block.
Click Apply to finalize the action.
Define a post-load action
Select the parcel in the Browser's parcels view.
Select the Properties code tool.
Choose the Post-load Action page in the properties tool, and edit the block.
Click Apply to finalize the action.
Save the parcel to store this as its post-load action.
Define a pre-unload action
Select the parcel in the Browser's parcels view.
Select the Properties code tool.
Choose the Pre-unload Action page in the properties view, and edit the block.
Click Apply to finalize the action.
Save the parcel to store this as its pre-unload action.