Application Management 1.2
Versioning and Packaging 
for
ObjectWorks Smalltalk Release 4.1
VisualWorks Release 1.0
VisualWorks 2.0

February 1995

Georg Heeg
Objektorientierte Systeme
Baroper Straße 337
44227 Dortmund

Tel.:		(x 49-2 31) 9 75 99-0
Fax:		(x 49-2 31) 9 75 99-20
email:	info@heeg.de

Copyright (C) 1993-1995 Georg Heeg, Dortmund. All rights reserved. No part of this document may be copied, photocopied, reproduced, translated or reduced to any electronic medium or machine-readable form without prior written consent from Georg Heeg.
Creation date: February 20, 1995

ObjectWorks Smalltalk is a trademark of ParcPlace Systems, Inc.

Contents
1.	Introduction and Overview	1
1.1	What is an Application?	2
1.2	Recording Changes	3
1.3	Versions	4
2.	Getting Started	5
2.1	Installation	5
2.2	Creating Applications	5
2.3	Construction and Maintenance of Applications	6
3.	Application Management Interface	7
3.1	Application Management Browser	7
3.2	Application Browser:  Editing Applications	9
3.2.1	Structure of Application Browser	10
3.2.2	Principles, Modes and Styles	11
3.2.3	Basic Functions for Application Maintenance	12
3.2.4	Special Editing	13
3.2.5	Browsing and Cross References	14
3.2.6	Filing In and Out Sources	15
3.2.6.1	Filing Out Normally	15
3.2.6.2	Filing Out Versions	16
3.2.6.3	Filing Out Sample Packages	16
3.2.6.4	Filing In Applications	17
3.2.6.5	Filing In Arbitrary Source Files	18
3.2.7	Summary of Commands	18
3.2.7.1	Category List Menu	19
3.2.7.2	Class List Menu	21
3.2.7.3	Protocol List Menu	21
3.2.7.4	Selector List Menu	22
3.3	Change Browser	23
3.3.1	Editing Change Lists	23
3.3.2	Reinstalling Methods	24
3.3.3	Utilities	24
4.	Programmer’s Guide	27

1
Introduction and Overview
Application Management is an ObjectWorks Smalltalk class library that provides structures for constructing and configuring software packages as basic components of applications. While Application Management works, it keeps track of all changes made to the ObjectWorks Smalltalk image during software development. To do so Application Management enhances the standard ChangeSet by implementing change sequences and method histories.
Application Management has been developed in order to improve the transparency of the change process during software development. Application Management maintains all known applications almost automatically without user interaction. This has become possible by extending the standard system change mechanism. See section 1.2 "Recording Changes" for detailed discussion of the new mechanism.
In addition to the improved change management Application Management also improves the standard source code management. Instead of using a single changes-file for each image Application Management maintains one source code file for each major version of an application. Thus different users of an application may share the source files of the application without copying. Thereby the file format used is the standard ObjectWorks Smalltalk source code format, thus providing full compatibility with users not using Application Management.
For the maintenance of applications Application Management includes an Application Management Browser, which serves as a launcher for meta functions such as loading, upgrading or creating new applications. Furthermore an application can be edited by a special browser (Application Browser) that inherits from the standard System Browser and adds some features for maintaining application or enhancing the cross reference features.
1.1	What is an Application?
Using the idea of the standard ObjectWorks Smalltalk change set we understand an application as a set of changes to classes, methods and organisations. In other contexts an application may also be called a project, package, class library, etc. Moreover an application simply can be viewed as a software library which is used to support an intended software project by making some basic functionality available to the developers. Nevertheless we prefer the term "application" to emphasise that any software is designed for special application purposes.
An application may consist of several other "sub-applications" that build reusable software components by their own. Thus the term "application" also refers to the reusability of the software components (e.g. classes) collected in an application. As described later in this document each application may define required applications, i.e. applications assumed to be present in order to run the target application properly. These definitions build a binary relation "is_sub_application_of" between applications, defined as the set of all pairs (A, B) of applications A and B, provided B requires A (i.e. A is sub-application of B). This relation may include cycles, but often it is hierarchical.
Another important aspect of each application is its development in time which is especially evident in further development that leads to new releases of an application (software life cycle). In order to support the software life cycle Application Management allows versioning of applications on different levels.
This versioning feature distinguishes between major and minor versions. The creation of major versions is recommended if changes to the "core" of the application have occurred since the last major version release or if some changes are hard to incorporate into the last major version. Minor versions are thought to reflect adding slight changes to the application like patching known bugs.
During the development of new major or minor versions all changes made to an application are recorded in a change sequence local to the current image without affecting the published state of the application. These local changes (also referred to as "temporary changes") are written to the source file and moved to another change sequence called "history" only after a new major or minor version is released by the application administrator. This also means that an application may store former versions of the source code even if a new release is built.
Further information included in the sources of an application are:
–	Expressions for pre-installation support (pre-installation script):
	These expressions are defined as part of the application and precede the sources of each major version. They may be used to prepare the following installation of the application (e.g. some methods need to be removed from a class to ensure proper working of the application).
–	Expressions for post-installation support (post-installation script):
	These expressions are defined as part of the application and are appended to the sources of each major version. E.g. the post-installation script may be used get rid of structures that are necessary only while the installation is running. Furthermore using a post-installation script allows to define an order of class initialisations (class initialisations that are defined in the post-installation script are removed from the initialisation "doIts" of the source code).
–	Pre-requisites:
	For users of Application Management an application can specify a collection of names of other applications that are required for the given application. These names are used to check whether the specified applications have been pre-installed.
–	Comment text:
	Each application may be given some text describing its purpose, special aspects, etc.
1.2	Recording Changes
The standard ObjectWorks Smalltalk change mechanism differentiates three main categories of changes
–	changes made to classes (editing, adding or removing classes)
–	changes made to methods (editing, adding or removing methods)
–	changes made to organisations (editing, adding or removing class categories or method protocols)
At any time such a change occurs during development the standard ObjectWorks Smalltalk change mechanism logs this change by performing a two stage procedure:
–	An entry describing the given change is added to the current change set of the image.
–	Smalltalk code that can be used to replay the change is appended to the image’s changes-file.
Unfortunately this technique implies two major disadvantages:
–	If a certain change occurs twice it will be logged only once. Thus there is no possibility to restore an older version of the change.
–	Since the standard change set behaves similarly to a set the order of the changes gets lost. Thus it can be rather complicated to build a working file-in of the application under development.
To overcome these disadvantages Application Management extends the standard mechanism by forwarding all changes that are introduced into the standard change set to "interested" (i.e. involved) applications. Applications then add the change to their change sequence in order to keep track of them. Of course it may happen that no application claims responsibility for a change (which may occur when adding new methods or classes). In this case the change is kept in a default application called "SystemChanges".
Application Management improves recording changes with respect to several aspects:
–	Application Management uses change sequences instead of the standard change sets. Thus Application Management does not only know that a change has taken place (as the standard change set does) but moreover records the order of changes in the change sequence. This technique is used for maintaining minor versions of an application and allows different users of an application to work with different minor versions.
–	Application Management maintains a change history instead of using a single entry in the standard change set (which only refers to the latest version of a change definition). This technique is used to store old versions of methods which is especially useful, if the old versions include valuable information for further programming.
Additionally, if some class or method is changed by compilation (including file-ins) Application Management tries to create a so-called "backup" and passes it over to "interested" applications which add it to their change sequence. A "backup" is a change object which refers to the class or method definition state prior to the compilation. While class changes will always produce a "backup" a method gets a backup only if the source code resides in a file other than the image changes file. You can recognize backups in Change Browsers marked with a leading asterisk enclosed in parentheses (e.g. "(*)"...).
Using these features of Application Management enables restoring old definitions of classes or methods. This is especially useful if some change is introduced into the ObjectWorks Smalltalk image only for experimental or debugging purposes (e.g. the "self halt"-statement). In this context restoring does not only mean replaying the old source code but also undoing all depending changes (the source code pointers are restored).
More information of editing change sequences is supplied in section 3.3 "Changes Browser".
1.3	Versions
In this section we explain the versioning concept of Application Management. Each application has a major and a minor version number, denoted in the usual way by writing the major version number followed by the minor version number, separated by a "." (e.g. 1.0, 4.1). If an application has been modified after filing in (i.e. the temporary changes of this application are not empty) the version number is automatically extended by the character "m", in order to mark its modified state. All temporary changes to any application will thereby be held in the image’s changes file.
Now we will explain what is included in major and minor versions:
–	Releasing a major version means writing some preparatory "doIts" as a pre-installation script to the version’s source file. The pre-installation script will be executed before the real installation of the application starts. After the pre-installation script the current state of the application’s source code is written followed by the "doIts" defined in the post-installation script.
–	Releasing a minor version means appending the source code of the temporary changes to the application’s source file and moving these changes to the so-called "history" of the application. Note that only those changes are added to a minor version release which are an element of the temporary changes (located in the image’s changes file). I.e. changes that have been removed during editing changes will not be included in the new release.
For more information about the source files and the source file format see sub-section 3.2.6 "Filing In and Out Sources".

2
Getting Started
This chapter describes the first steps with Application Management. We assume that you are familiar with the ObjectWorks Smalltalk development environment as well as with the operating and windowing system of your computer.
2.1	Installation
For installing Application Management open a file browser and select the file
	install.st.
Execute the "file in" command from the middle mouse button menu. During the installation process the first application structures are created (those building Application Management) and the appropriate source file references (reference to source files other than the image’s changes file) will be set.
2.2	Creating Applications
There are two ways for creating new applications:
–	Creating an empty application by executing the "new application" command in the application management browser’s middle mouse button menu and entering a name for the new application.
–	When filing in from a file list Application Management will prompt for an application to hold track of the filed in changes. Choosing "NEW APPLICATION" in the dialog box will prompt for a new name and the new application will be created.
2.3	Construction and Maintenance of Applications
There are four mechanisms for maintaining existing applications:
–	Upgrading an application can be done by selecting the "file in/out » upgrade" sub-menu item in the application management browser’s middle mouse button menu. This will add all changes appended to the selected application’s source file (after the current minor version).
–	Selecting the "file in/out » file in…" sub-menu item in an Application Browser’s middle mouse button menu will prompt for a file containing Smalltalk source code. This code will be filed in and recorded in the selected application.
–	The "include" and "exclude" menu items of an Application Browser’s middle mouse button menus allow to configure the contents of applications manually. (Further information on this topic will be found in sub-section 3.2.3 "Basic Functions for Application Maintenance".)
–	Compiling code as usual in an Application Browser will register the compiled class or method in the associated application.

3
Application Management Interface
This chapter gives an overview of the tools of Application Management. All tools are based on standard ObjectWorks Smalltalk development environment tools. Thus there should be no problem in getting used to the new tools. A difference which should be explained here is that Application Management avoids context sensitive menus, i.e. menu items which are not valid in a certain situation are disabled (displaying in italic face) rather than shortening menus to contain valid items only.
3.1	Application Management Browser
  	Figure 1:  Example Application Manager
The Application Management Browser is a launcher for all application meta functions such as loading, upgrading, creating applications, etc. It can be opened by executing the expression "ApplicationManagementBrowser open". Figure 1 shows an example Application Management Browser with the standard label "Application Manager".
Each Application Management Browser contains a list of registered applications. By using the button "modified" the list will be filtered showing only the modified applications (changed since the last minor version release) instead of the complete list. By using the button "hierarchy" the list will be displayed in a tree oriented way: An application will be followed by the sub-list of all its required applications in alphabetical order with each element indented by a tab. The sub-list may be hidden by selecting the menu item "contract" and the appropriate application will display in bold face. Hidden sub-lists are shown selecting menu item "expand". Hint: Sub-list elements written in brackets ("[...]") represent applications required but not loaded.
The hierarchy mode has two advantages: 1) It explicitly shows the "is_sub_application_of" relation mentioned above without opening browsers, and 2) the list may be restricted to "interesting" applications, hiding the "low level" applications which are required (often a case of reuse).
The middle mouse button menu shows the following entries that initiate the described actions:

menu entry
»	sub-menu entry	description	
file in/out	opens a sub-menu with commands for reading and writing source files	
»	upgrade...	shows a pop-up menu with all applications that have been changed by their author (enhancements, bug fixes etc.) since last loading or upgrading; selecting one of these applications raises a dialog inquiring the minor version number up to which the upgrade should be done (normally the newest one), then files in the incremental changes since the current version up to the version entered. 	
»	load...	shows a multiple selection dialog with names of directories where Application Management searches for available applications; deselecting a directory will skip the directory during the next search;
extend the name list by using the button "add" and entering a valid directory name or remove elements by using button "remove"; passivate (activate) all elements using button "none" ("all");
selecting button "accept" starts searching the selected directories and shows a pop-up menu of available applications; choosing one of these installs it in the image (hint: if more than one major version of an application is found in some directory, the corresponding menu entry is the directory and application name with a sub-menu of all major versions found; otherwise the entry is the directory, the application name, and the major version found)	
»	load info...	starts like "load..." to search and select an application, but then opens a text view showing the identifier, the comment, and the required applications as defined in the selected application's binary file (without loading the application)	
»	set directories...	opens an inspector on the collection of search paths used during application retrieval (cf. menu item "load...")	
»	new minor version	creates a new minor version release of the selected application	
»	new major version...	creates a new major version release of the selected application	
»	file out changes...	files out all changes of the selected application since the last major or minor version release to a file named by the user	
»	file out all changes...	raises a multiple selection dialog to pick changed applications, then files out all changes of the selected applications to a file named by the user 	
»	file out upgrade...	raises a multiple selection dialog to pick changed applications, then files out all changes of all selected applications to a file named by the user 	
»	file out installation...	creates an installation file and/or shipment package; see section 3.2.6 "Filing In and Out Sources" for details	
»	condense changes...	removes all unreferenced changes from the current image  changes file; this option is recommended especially after releasing or upgrading to new major version releases	
open browser	opens an Application Browser on the currently selected application	
new application...	prompts for a name and creates a new application (known application names are rejected)	
expand/contract	hierarchy mode only: works on applications with required applications and toggles hiding and showing required applications (visible by bold face and normal display)	
unregister	opens a sub-menu with commands for removing applications	
»	release...	moves the source code of the selected application to the current image changes file and unregisters the application from Application Management	
»	deinstall...	restores a state prior to installation of the selected application: reinstalls all method backups registered in the selected application's changes or history and excludes the corresponding selectors; all selectors and classes registered in the application after reinstalling and excluding will be removed from the image without any further checks	
update	updates the list of applications	

Deinstalling applications in general is a very complicated process. Reading the explanation of menu item "deinstall..." you can imagine system or application states conflicting with the described procedure. The current implementation is a straightforward approach for deinstallation working well for many situations. When deinstalling be careful. First of all, have a look at the application's full history to be conscious about what will be reinstalled. Furthermore be sure that methods which are necessary in the image have a backup (otherwise they will be regarded as owned exclusively and be removed). 
Hint: Make use of the "intersection" utility of the Application Browser to ensure that selectors or classes to be removed are not needed (registered) by other applications.
3.2	Application Browser:  Editing Applications
This section describes the features of the Application Browser. It is divided into the following sub-sections
–	Structure of Application Browser
	describes the structure (sub-panes) of the Application Browser
–	Principles, Modes and Styles
	describes the different appearances of entries and their meanings in the Application Browser
–	Basic Functions
	describes the basic Application Management functions accessible from the Application Browser
–	Special Editing
	describes the special editing functionalities of the Application Browser
–	Browsing and Cross References
	describes the additional cross reference features of the Application Browser
–	Filing In and Out Sources
	describes how the sources of applications are managed and how they can be maintained by filing in or out
–	Summary of Commands
	summarises the commands of the Application Browser
3.2.1	Structure of Application Browser
Application Browsers inherit from the standard System Browser and have a similar structure. We assume that the reader is already used to the standard browser since we adopt the associated terminology, too. Figure 2 shows an example Application Browser.

Figure 2:  Example Application Browser
The window label of an Application Browser is the identifier of the associated application. The version number in this label may be extended by the character "m" to indicate that the application has been modified since the last version release.
The main components of the Application Browser are similar to the standard System Browser regarding both position and extent and have the same purpose (differences in behavior to these components will be explained in section 3.3.2 "Principles, Modes and Styles"):
–	the class category list
–	the class list
–	the protocol list
–	the selector list
–	the text pane
–	the instance/class switch
Thus we can concentrate on the new elements:
–	The "system" button below the category list:
	This button is a toggle that changes between different modes of the Application Browser. The different modes are explained in detail in the sub-section 3.2.2 "Principles, Modes and Styles".
–	The "doc" button below the category list right to the "system" button:
	This button toggles the documentation mode. In documentation mode (the label "doc" appears in bold face) the text from the text pane is assigned to the comment of the application if "accept" is executed. Otherwise "accept" works as usual.
–	The source information line beneath the text pane:
	This line shows the source of the currently selected code in the text pane. Source here stands for a file or structure responsible of holding track of the shown code. Possible outputs in this line are:
–	the name of the system source file
	The selected code is located in the sources file delivered with the Smalltalk image; normally this only occurs in the system mode.
–	the name of the image changes file
	The selected code is located in the current changes file of the image; the code has been altered by some user action like "accept", "file in" etc.; the source may be associated to some application but has not been released in a new version of the application.
–	the name and version of an application
	The source code reference of the selected method refers to the source file of the shown application.
–	The inheritance switch placed beneath the selector list:
	This switch is accessed by the middle mouse button and shows a pop-up menu of all superclasses of the currently selected class. Selecting one of these classes adds all inherited protocols and selectors to the protocol and selector list. Choosing a selector induces the implementor of the chosen selector being shown by the inheritance switch.
3.2.2	Principles, Modes and Styles
The model of an Application Browser is an application. Thus an Application Browser can filter and restrict the lists in its subviews to the elements registered by the model. Since all menu entries work solely on the shown lists any action affects only visible entries. Thus it is possible to prevent the removal of methods that have not been registered by the application.
The "system" button is used in order to filter the application of an Application Browser. If the button label is displayed in plain style only the information that is registered by the application will be shown. This is especially important if inherited protocols or selectors should be shown, because in this case only the behaviour registered in the application will be accessible (cf. the remarks above).
If the "system" button displays in bold face there is access to all classes and methods in the image. To mark those classes, protocols or selectors that are not registered in the application the "non-application" items are displayed in italic face in the lists of the Application Browser.
3.2.3	Basic Functions for Application Maintenance
Application Browsers provide all functions known from the system browsers with the same semantics restricted by the filtering options described in the previous section. Thus we will describe only the additional functions.
For the maintenance of applications the most important functions are "include" and "exclude" which are available on the middle mouse button menus of each of the browser’s lists. "include" and "exclude" are used as basic constructors of an application. The different results of the "include" operation working on the different lists are described in the following table.

list	effect	
category	same as "include" for each class in the selected category	
class	registers the selected class and its metaclass together with all method selectors in the application	
protocol	same as "include" for each selector in the selected protocol of the selected class	
selector	registers the selected method selector of the selected class in the application	
Table 1:  Effect of the "include" operation
The "exclude" operator reverts the "include" action. The selected item is removed from the application registration structure. If no other application registers the selected item it is moved to application "SystemChanges". By using "include" and "exclude", changes can be moved from one application to another.
The class list menu additionally provides an "exclude definition" entry. This entry only removes the class definition from the registration structure but lets all method selectors be untouched. This is useful as normally the class definition is not registered if only a single method is registered in an application.
It is much more convenient to construct applications implicitly than constructing applications explicitly by using "include" and "exclude". This is done automatically by editing and accepting code in the Application Browser: Every compilation will register the change in the current application.
As mentioned before every compilation resulting in a change of a class or method will be registered in some application. Each application will decide on its own whether it is "interested" in a change or not. If no application claims on a change, the change will be registered in the default application "SystemChanges" (this refers especially to new classes not compiled in an Application Browser).
3.2.4	Special Editing
As one can spawn categories, classes, protocols, selectors and methods in a system browser, one can open new Application Browsers by spawning categories, classes, protocols, selectors and methods in an Application Browser. The model of these browsers again is the application of the Application Browser from which they were spawned (this does not hold for spawning a Hierarchy Browser). Additionally the sub-menu entry "spawn » application" has been added to the category list menu. This menu entry will open a new Application Browser on the currently edited application. Furthermore the sub-menu entry "spawn » required" opens an inspector on the list of required applications for the current model.
More important for maintaining applications than spawning browsers are the options for opening editors on the changes in an application. These options allow viewing and manipulating versions of class or method definitions. The required spawn options are accessible in an Application Browser. Depending on the menu (category list menu or selector list menu) and the selection in the "spawn"-sub-menu a Change Browser on one of the following lists will be opened:

»	sub-menu entry	description	
»	changes	changes since last major or minor version release	
»	history	changes from original or first major version to last minor version release	
»	full history	concatenation of the previous two	
»	pre-installation	list of expressions executed before installation of source code (pre-installation script)	
»	post-installation	list of expressions executed at the end of the installation (post-installation script)	

Detailed information about the Change Browser will be given in section 3.3 "Change Browser". The rest of this section will describe some details about post-installation scripts.
Sometimes you will need to define the order of class initialisations of classes occurring in an application. While Application Management totally relies on the file out order of the system, there is the possibility to delay or prohibit class initialisations. Each class initialisation occurring in the post-installation will not be filed out at the time defined by the standard file out order but at the time defined by the place in the post-installation. 
Example: Let X and Y classes defined by the application, both having defined and registered the selectors #initialize. Let further the post-installation comprise the following expressions:
	"initialize X after installing the global variable Z"
	Smalltalk at: #Z put: nil.
	X initialize
The end of the source file after filing out the major version will look like this: 
	Y initialize!
	"initialize X after installing the global variable Z"
	Smalltalk at: #Z put: nil.
	X initialize!
To minimize restrictions in formulation Application Management uses a Smalltalk Scanner to detect class initialisations, looking for pairs <aClass> <#initialize> with <aClass> replaced by an existing class. However, the following encoding does not achieve the goal.
a)	#(X) do: [:aClass | aClass initialize]
	-> The scanner finds a pair (#aClass, #initialize), but #aClass is no class' name.
b)	'X initialize'
	-> The scanner finds the single token #'X initialize' and not the pair (#X, #initialize).
c)	"X initialize"
	-> The scanner ignores comment.
If you want to prohibit an initialisation use the simple trick and define 
	[X initialize]
	-> A valid statement, but without effect.
This may look a bit queer on the first glimpse, but in practice this procedure is intuitive, general and circumvents tedious mechanisms for definition of file out orderings.
3.2.5	Browsing and Cross References
The class list menu holds an "applications"-sub-menu as does the selector list menu. This allows to retrieve information depending on the application by the following sub-menu entries:

»	sub-menu entry	description	
»	owners	shows a pop-up menu with all applications which registered the definition of the selected class; picking one of the applications opens a new Application Browser on the chosen application;	
»	includers	shows pop-up menu with all applications which registered a method of the selected class; picking one of the applications opens a new Application Browser on the chosen application;	
»	senders	similar to "senders" command in selector list menu; shows pop-up menu with all applications referring to the selected class by a registered method; picking one of the applications opens a Method List Browser with all senders registered in the chosen application;	

Furthermore Application Management enhances the standard "implementors" request of the system browser. The sub-menu entry "spawn » hierarchy" of the selector list menu of an Application Browser will open a Method List Browser on all implementors of the selected message within the hierarchy of the selected class.
Application Management allows to register methods in more than one application. Sometimes methods are registered in an application without any conscious user action and even without the user getting aware (normally you do not know in advance which selectors are imported when filing in some source code). Often it is necessary to have information about duplicate selector registrations (c.f. menu item "unregister » deinstall" on the Application Management Browser). A function for getting this information is provided with menu item "utilities » intersections": Application Management searches for applications which have selectors in common with the application currently edited and shows the names of these applications in a pop-up menu. Selecting one of them opens a Method List Browser with all selectors which are registered both in the edited application and the selected one.
3.2.6	Filing In and Out Sources
The source code format used by Application Management for creating file-outs is fully compatible with the standard ObjectWorks Smalltalk format for file-outs. The order of the file-out pays attention to the needs during file-in; i.e. superclasses are filed out before their subclasses and all protocols and other organisational structures are preserved as defined by the class organisations. Special file-in information necessary for installing an application using Application Management are stored using MessageSends, which are skipped during the standard file-in procedure.
Essentially there are two methods for filing out sources.
3.2.6.1	Filing Out Normally
First it is possible to file out categories, classes, protocols or methods in the standard Smalltalk manner using the menu entry "file out ..." in a browser. This action will prompt for a file name and write the source code of the respective organisational level to the specified file. In this case one slight difference appears between a standard browser and an Application Browser not working in "system" mode. Only those elements registered and accessible in the application will be filed out (this holds especially for class definitions and comments).
Another difference is the possibility to skip selectors during file out. When filing out new major or minor versions Application Management drops any selector classified under protocols matching the pattern "generated*". Thus selectors which are generated during class creation may be discarded from the source file, so that they do not compile twice during file in. To keep source code access consistent the source references of such selectors are flushed (set to nil) during major or minor version file out: You cannot have source code if you have no source file. This mode does not apply to "normal" file out (e.g. file out category, class, protocol, etc.).
3.2.6.2	Filing Out Versions
The second method for filing out sources supports source code management and is used to store major or minor versions. Creating code for a new version is followed by redirecting source pointers to the new position (source pointers are used to access the source code). This applies as well for compiled methods as for comments. Moreover the entry in the global change set reflecting the state just saved is removed. Thus the change set becomes smaller and the changes file will become much smaller after condensing.
Important: Note that method and comment source references are part of the image. Thus after releasing major or minor versions a snapshot is urgently recommended (but not mandatory) to ensure a stable image.
The name of the default source file for reading or writing an application’s source code is mainly defined by the application itself. Thereby Application Management constructs a path and file name according to the pattern "<path>/<name>/<vi>/s.st", the single subparts having got the following meaning:

<path>	name of an arbitrary directory specified by the user	
<name>	name of the application in a platform compatible format	
<vi>	major version where i is replaced by the version number (e.g. v3)	
s.st	real application source file	
"/"	the platform dependent filename separator	

While minor version release simply means appending temporary changes to the application’s source file (and redirecting source pointers), a new major version writes out much more information. The format used by Application Management for source files is:
	<identifier> <time stamp> <comment> <pre-installation code> <required> <source code> <post-installation code>
with the meanings listed below:

<identifier>	application name followed by the version string	
<comment>	text assigned to the application in the documentation mode of an application browser	
<pre-installation code>	collection of expressions which are executed before filing in the application source file	
<required>	collection of names of applications which should be installed before	
<source code>	source code of classes and methods building the application including all necessary class initialisations not defined in the post-installation script	
<post-installation code>	collection of expressions which are executed at the end of filing in the application source file	
3.2.6.3	Filing Out Sample Packages
Having defined numerous applications you will often have the problem to create a sample package which includes a certain subset of applications, e.g. customer shipment sets. The receiver of the package must be able to reconstruct an application from this package in its entirety. Application Management helps you with the export function "file in/out » file out installation..." available on the Application Management Browser menu. Because this procedure relies on application hierarchies defined via required applications, it is necessary that for a package exists at least one application, requiring (immediately or transitively) all other applications to be included in the package. Figure 3 shows the dialog box prompting for export parameters. 

Figure 3:  Export parameter dialog
The dialog asks for a target directory (mandatory, must exist before executing this action), an installation file name (optional), and a target platform.(optional).
If the target directory is given with <path> and the installation file name with <filename> Application Management creates a file <path>/<filename> (again "/" representing the platform dependent filename separator) which contains Smalltalk file-in expressions for reconstruction of the selected application in a target image. A second dialog asks for applications to be included in the installation file (default is the set of immediate required applications). The expressions will include all required applications (recursively), skipping those deselected in the second dialog, file-in paths will be paths as defined by the corresponding applications.
If the target platform is given the source and data files of each application included in the installation file will be copied to <path>/<appname>/<vi>, where <appname> is the given target platform compatible name of the application and i in <vi> its current major version. The file-in paths will be the current path at installation execution time extended by <appname>.
Note: The export does not include application changes which are local in the image, i.e. not frozen by a minor version.
3.2.6.4	Filing In Applications
Filing in an application source file first executes the expressions that have been defined in the source application as pre-installation script and afterwards reconstructs the source state. If Application Management is present in the target image the file-in procedure checks the presence of all required applications. If an application is missing Application Management will report this in a dialog box and wait for the decision of the user whether to proceed or not. Since most applications fortunately will not bother about incomplete installations proceeding is recommended here. Furthermore the report will be written to a newly opened workspace to remind the user of installing missing applications later on. Then filing in the main source area installs classes and methods as defined by the application. After that the file-in procedure will execute initializations and post-installation expressions (if the source application defines any). At last all sources defined by minor versions (if any) are read and installed. The whole process automatically reconstructs the source application structure except recording pre- and post-installation doIts.
3.2.6.5	Filing In Arbitrary Source Files
Last in this section we will explain what happens if an arbitrary source file is filed in. In this case Application Management prompts for an application to record all changes resulting from compiling the contents of the file. Hence four choices are possible:
a)	empty selection 
	(this cancels the file-in)
b)	selection of the default application ("SystemChanges")
	(starts normal file-in, logs the source code in the changes file and registers the compiled classes and methods in "SystemChanges")
c)	selection of an existing application
	(starts normal file-in; logs the source code in the changes file and registers the compiled classes and methods in selected application)
d)	selection of "NEW APPLICATION"
	(here a dialog box prompts for the name of a new application, a second dialog box asks if the source pointers shall be kept external; selecting "no" the file-in proceeds as for b) and c); selecting "yes" the source code is not appended to the changes file and the source pointers are redirected to appropriate positions in the file just read; additionally the path of the new application is set to the file just read).
A shortcut for filing in into an existing application (c) can be achieved by using the "file in/out » file in…" sub-menu entry in an Application Browser. This option prompts for an appropriate file name and afterwards will works like c) above, i.e. filing in into the Application Browser’s application.
3.2.7	Summary of Commands
This section summarises all menu commands of an Application Browser. Since Application Browsers provide commands same or similar to system browsers we introduce the following abbreviations:
–	An asterisk ("*") denotes identity of a command with identical name in Application Browser and system browser.
–	A hash sign ("#") denotes command identity with respect to the application membership restrictions (cf. sub-section 3.2.2 "Principles, Modes and Styles").
–	A plus sign ("+") stands for same functionality with additional actions.
The rest of this section is organised according to the various lists of the Application Browser. A single hint is given: All operators removing classes or selectors perform removal without checking if applications other than the edited one hold the same element.
3.2.7.1	Category List Menu
First we describe all commands in the category list middle mouse button menu:

menu entry
»	sub-menu entry	description	
file in/out	file oriented sub-menu (cf. sub-section 3.2.6 "Filing In and Out Sources");	
»	file in...	prompts for file name and compiles the contents of the specified file; source code is appended to image’s changes file; results of compilation (classes and methods) are registered in the model of the browser;	
»	upgrade...	if source file contains source code which has not yet been compiled, a dialog box showing the latest version number waits for confirmation to install the new sources; selecting "yes" files in the sources, redirects source pointers without appending source code to the image’s changes file; temporary changes are cleared; if the changes of the application are not empty they should be reassigned to the application;
follow the instructions shown in the dialog box which proceeds opening a Change Browser on these changes;	
»	new minor version	releases new minor version; appends corresponding source code to application source file; redirects source pointers; all entries in temporary changes are moved to "history";	
»	new major version...	releases new major version; prompts for directory to contain new version; files out pre-installation script, installation checks, application comment; sources and post-installation script to application source file, redirects source pointers;	
»	file out changes...	prompts for file name; files out source for temporary changes of application to specified file;	
»	file out category...	#	(equivalent system browser command is "file out");	
»	file out application...	prompts for file name; files out source code of registered entries of application to specified file (the file out format is the same as in "new major version");	
»	print out category	#	(equivalent system browser command is "print out");	
»	print out application	prints out source code of registered entries of application to default printer or print file;	
»	set path	asks for a new path name of the application; if the new path does not exist a warning will be shown afterwards allowing a new trial;
Warning:  if you have not copied the source file of the application to the new path an error may occur on an access to the application’s sources;	
»	set platform names	asks for the application's name compatible with various platform filename conventions; if an entry is undefined Application Management proposes a compatible one, appended a quotation mark ("?") to show you that it is an automatically gained entry; if you like it just accept the proposed value (the quotation mark will be discarded automatically); you may leave entries undefined by entering an empty string;
Warning: Note that the platform compatible name of an application is used during file access (c.f. section 3.2.6.2). Source code access generally will fail after "renaming" the compatible name until the corresponding directory will be renamed appropriately.	
spawn	sub-menu for editing oriented commands (cf. sub-section 3.2.4 "Special editing" and section 3.3 "Change Browser");	
»	application	opens new browser on the edited application;	
»	category	+	lists of the new Category Browser are restricted to registered elements (equivalent system browser command is "spawn");	
»	changes	opens Change Browser on temporary changes;	
»	history	opens Change Browser on change-history;	
»	full history	opens Change Browser on change-history and temporary changes;	
»	pre-installation	opens Change Browser on expressions to execute before installation;	
»	post-installation	opens Change Browser on expressions to execute at the end of the installation;	
»	statistics	opens a workspace on the following information:  number of class definitions, number of method definitions; size of current source code file (in bytes), size of current binary file (in bytes) of the application;	
»	required	opens editor on names of applications required for proper work of current application;	
»	inspect	opens inspector on current application;	
add category	*	
rename	*	
remove	#	
include	sub-menu for maintaining applications	
»	category	registers all classes with definitions along with method selectors organised in selected category in the application;	
»	required application...	shows pop-up menu with all applications in the image; selecting one adds its name to the collection of required application;	
»	all required applications	collects names of applications used by current application and stores them in the collection of required application names; application A uses B, if B defines superclasses of classes defined in A, or if methods registered in A refer to classes defined in B;	
exclude	unregisters all elements organised under selected category;	
utilities	sub-menu with special browser functions	
»	intersections	finds out which applications register elements of the currently edited application (see also section 3.2.5 "Browsing and Cross References")	
»	dependencies	opens a text view reporting on why/where the edited application requires its required applications	
»	update	+	unregisters empty protocols, class subsets and categories;	
»	edit all	*	
find class	#	(classes that have not been registered within the application can be found in non-system mode not at all).	
3.2.7.2	Class List Menu
Next we describe all commands on the class list middle mouse button menu:

menu entry
»	sub-menu entry	description	
file out	#	
print out	#	
spawn	+	lists of Class Browser restricted to registered elements;	
spawn hierarchy	*	
hierarchy	*	
definition	*	
comment	*	
protocols	*	
inst var refs	*	
class var refs	*	
class refs	*	
applications	sub-menu for special cross reference features (cf. sub-section 3.2.5 "Browsing and Cross References");	
»	owners	shows a pop-up menu with all applications which registered the definition of the selected class; picking one of the applications opens a new Application Browser on the chosen application;	
»	includers	shows pop-up menu with all applications which registered a method of the selected class; picking one of the applications opens a new Application Browser on the chosen application;	
»	senders	similar to "senders" command in selector list menu; shows pop-up menu with all applications referring to the selected class by a registered method; picking one of the applications opens a Method List Browser with all senders registered in the chosen application;	
rename	*	
remove	#	
include	registers the selected class with definition and all method selectors in application;	
exclude	unregisters the selected class with definition (if included) and all method selectors; each element not registered by another application is registered in application "SystemChanges";	
exclude definition	selectively unregisters definition of the selected class; if not registered by another application it is registered in application "SystemChanges".	
3.2.7.3	Protocol List Menu
Next we describe all commands on the protocol list middle mouse button menu:

menu entry	description	
file out as...	#	
print out	#	
spawn	+	lists of Protocol Browser is restricted to registered elements;	
add protocol...	+	proposes list of frequently used protocol names; selecting "other protocol" proceeds usually (the proposed list includes also protocols of superclasses which are not part of the selected class' organisation);	
rename as...	*	
remove...	#	
include	registers selected protocol with all method selectors in application;	
exclude	unregisters selected protocol with all method selectors; each element not registered by another application is registered in application "SystemChanges";	
edit all	*	
find method...	#	(selectors that have not been registered within the application can be found in non-system mode not at all).	
3.2.7.4	Selector List Menu
Next we describe all commands on the selector list middle mouse button menu:

menu entry
»	sub-menu entry	description	
file out	#	
print out	#	
spawn	sub-menu for editing oriented commands (cf. section 3.3 "Change Browser");	
»	method	opens Method List Browser on selected method selector;	
»	hierarchy	opens Method List Browser on implementors of selected method selector; restricted to the selected class and all superclasses;	
»	changes	opens Change Browser on temporary changes;	
»	history	opens Change Browser on change-history;	
»	full history	opens Change Browser on change-history and temporary changes;	
senders	*	
implementors	*	
messages	*	
applications	sub-menu for special cross references (cf. sub-section 3.2.5 "Browsing and Cross References");	
»	owners	shows pop-up menu with all applications registering selected method;	
»	senders	similar to "senders" command in this menu; shows pop-up menu with all applications referring to selected method by a registered method; picking an application opens Method List Browser on all senders registered in chosen application;	
move	+	implicitly registers destination protocol if not registered yet;	
remove	*	
include	registers selected method in application;	
exclude	unregisters selected method; if not registered by another application it is registered in application "SystemChanges".	
3.3	Change Browser
For editing change sequences of applications the Change Browser already present in the system environment is used. As described earlier for browsers special subclasses are built that inherit from the standard class ChangeList in order to link an application to a Change Browser. The structure of a Change Browser was not modified. The only thing with some impact is that we changed the class filter of Change Browsers, accepting change elements both referring to some class and the corresponding metaclass. For the rest it is sufficient to describe merely the new menu items.
You should revise change sequences frequently in order to get rid of intermediate versions of classes and selectors. Remember that Application Management logs every change created during development thus storing multiple versions. Especially before releasing a new minor version or before exporting temporary changes (using the "file out changes" command in an Application Browser) you should clean up the change sequence concerned. One of the most helpful commands may be the "purge methods" menu entry explained in section 3.3.3 "Utilities".
3.3.1	Editing Change Lists
The most important enhancements are the "accept" and "update" commands. Both menu entries are connected directly with the underlying application. "accept" is used as an assignment operator and replaces the application’s changes or history with all changes of the Change Browser that are not marked for removal (i.e. not struck out).
Note: It is important to know that "accept" does not depend on the currently set filters, but that also invisible changes will be transferred immediately.
Moreover it is noticeable that changes may be introduced into an application's change-list by any compilation ("do it", "file in", …). If a Change Browser (opened by using "spawn » changes" or "spawn » full history" from the category or selector list in an Application Browser) includes the temporary changes of an application and if some new changes have been introduced into the application by some compilation etc. after opening the Change Browser, select "update" to ensure a consistent change-list before accepting the changes. "update" reads the current state of the changes just edited and thus avoids creating improper minor versions by executing "accept" without the new entries (minor version release means simply filing out the changes). For more detailed information cf. section 1.3 "Versions".
An additional auxiliary enhancement is the possibility of using "copy", "cut" and "paste" for changes in the Change Browser. These options allow any easy editing and reordering of a change sequence. While "copy" and "cut" work in the familiar way, "paste" inserts the buffer contents in front of the current selection or appends it to the change-list if no selection is available.
The next addition is the possibility of adding "doIts" to a change list. To do so just type in the necessary code expressions in the text pane of the browser and then select "accept" from the middle mouse button menu. A dialog asks for confirmation to create a "doIt". Selecting "yes" will compile the entered text to check for syntax errors and add an appropriate "doIt" before the current selection or at the end of the change-list. Application Management tries to convert expressions into the "proper" change objects. Sometimes this is not possible, especially when typing in sequences of expressions including the expression separator ("."), resulting in a simple OtherChange.
Hint: Selecting "accept" on the text pane does not accept the new contents of the list itself. Do not forget to assign the new list to the application's changes selecting "accept" on the list pane.
3.3.2	Reinstalling Methods
Unlikely the options discussed above the "reinstall"-option of the menu is a completely new feature. Invoking this option for a selection will restore a state defined by the selection but doing more than simply recompiling:
–	first the selected change is recompiled (same as "replay selection");
–	if the result is a compiled method or a comment, additionally the saved source pointer is restored; if the source pointer refers to a file other than the image’s changes file, the appropriate entry in the global change set is removed; this operation causes the system environment to "forget" completely about the change;
–	thereafter all changes following the restored one and affecting the same class or method are marked as having been removed;
–	finally a new change representing the new state appears (unremoved) at the end of the change-list; if this new change redefines a state saved in a previous minor version, it should be kept; otherwise it may be removed as well.
After accepting the contents of the change-list both the system change apparatus and the application have cancelled any changes to the object concerned since the restored state.
3.3.3	Utilities
Application Management enhances the change list menu by a sub-menu labelled "utilities" including some useful functions, especially for cross-referencing and browsing. The following table gives an overview about the single menu items. Again we use the asterisk ("*") as abbreviation denoting that the menu item has been taken over unchanged from the standard operators set.

sub-menu entry	description	
»	find class...	shows a pop-up menu of all class names occurring in elements of the changes list; selecting one of them "jumps" to the first element in the list referring the selected class	
»	spawn compare	opens a text view showing the source code as installed in the current image, corresponding to the selected change; changing the change list selection always lets this text view also change to the corresponding system text;	
»	spawn system	* (known as "spawn selection..." in the default menu);	
»	spawn change list	* (known as "spawn all..." in the default menu);	
»	owners	shows a pop-up menu of all applications registering the class or selector referred by the selected change; selecting one of them opens an Application Browser pre-selected on the class or selector;	
»	implementors	opens a Method List Browser on implementors of the selected change selector;	
»	senders	opens a Method List Browser on senders of the selected change selector;	
»	messages	shows a pop-up menu with all selectors occurring in the method defined by the selected method change; selecting one of them opens a Method List Browser on implementors of the selected selector;	
»	check conflicts, save as...	*	
»	check with system, save as...	*	

Furthermore Application Management introduces more functions for removing change list elements, gathered in a sub-menu labelled "remove...", described by the next table.

sub-menu entry	description	
»	remove all	*	
»	all to end	discards all elements from the selected change to the end of the list	
»	all upper	discards all elements from top of the list up to the selected change	
»	invert	inverts the state "marked for removal" for all elements of the list: discards non-discarded elements, restores discarded ones;	
»	remove same	discards all elements of the list with equal source code compared to the current image;	
»	purge methods	discards all but the latest change for each selector referred to by elements in the list	

4
Programmer’s Guide
This chapter includes some notes and hints for programmers. First some comments on the concepts and the "holy places" claimed by Application Management.
While the body of Application Management is realised by the application "APL-Framework", the heart of it is actually the application "APL-SystemLink". Thus be more than careful if you want to modify functionality inherited or assumed by classes or selectors registered in this application.
Application Management attaches to the system change mechanism in order to get informed of any changes and additions of classes and methods. So every change event passed to the system change set (ChangeSet current) will be forwarded to existing applications.
Application Management records changes in a quite different way than the system change set does. In order to reflect the order in which changes occur each application holds a list of changes. These lists do not only store a symbol or flag (compare to ChangeSet) but also a position for the source code in the appropriate source file. Thus Application Management can record more than one change on the same item which leads to the following problem:
Compiling a method results in a change that will be broadcast to the change set and all applications. After this process has successfully been completed a new source position for the changed method will be defined. Now all change-objects referring to the change get invalid source pointers and have to be updated by a special run of the Application Manager. In general one should observe the following rule:  All calls to CompiledMethod>sourcePointer: which are preceded by a change emitting method (e.g. compilation) should be followed by an update run.
If you want to remove Application Management from a running image, refer to selector "ApplicationManagement class>#uninstall". We recommend to set source pointers of methods registered in applications to nil before #uninstall is called. The reason for that is that all applications will be released, having to move registered source code to the image changes file in order to associate new application independent source pointers to all of their methods.