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


May 1994




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, 1994 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: June 8, 1994

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 Brow-
ser). 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.