[up]

Installing Smalltalk/X

Index

Introduction

This document describes details of the contents of the ST/X distribution and gives more background information on the installation procedure.

Installation

Linux and Windows

For Linux and Windows, ST/X is delivered as an archive; either in "tgz" (tar-compressed) or in "zip" format. For all Unix systems except OSX, two archives are required: one containing all the files which are common to all unices (mostly sources and configuration files), and another one containing the architecture-specific binaries. For MS-Windows everything is contained in a single archive.

Due to the different line-end-conventions, the common file used for unix should not be unpacked into a windows system, and vice versa.

No real installation is required: simply unpack the whole archive(s) somewhere on your system.

OSX

ST/X is delivered as a mountable ".dmg" file. For installation, open the "stx.dmg" file and drag the "stx.app" file to the "Application" folder. You can install "stx.app" into any other folder (eg. your private "Application" folder or your desktop), if you like.

To run, "stx" needs "xquartz" to be be installed. Open safari, and navigate to "https://www.xquartz.org/" to download that package.

Delivered Package


The delivery includes all classes in both source and machine compiled form (class libraries), the stc (Smalltalk to C compiler) as a binary, Makefiles and scripts to recompile the system in part or as a whole, demonstration code, examples and finally an executable Smalltalk/X system.
The executable has been generated by linking all compiled classes into a number of shared libraries which are loaded by the "stx" program. The executable enables incremental development of classes and/or applications, which can either be executed within this environment or compiled down to machine code for binary class libraries or standalone executables.

The license allows for commercial use with some minor exceptions, regarding military use.

Files and Directories as on the Delivery Medium

After unpacking, you will find the following directories (on OSX, these are found under the "Packages" folder):

Reading the Delivery Medium

The first step in your installation is to verify that enough disk space is available. A full installation requires approx. 300-500Mb of disk space (the full amount is only required while the system is recompiled, some of the intermediate object files can be removed later).

An installation consisting of the source files and the resulting class libraries only (as contained on the distribution medium) requires approx. 200 Mb of disk space.

Linux and Windows

Create a new directory where the files should go, and change into it. 
	mkdir stxXXX
	cd stxXXX
Replace XXX by the release-number; currently, this would be release 6.2.3, therefore "stx623" is a good name. In the following description, we call this directory "TOP".

Installing Files for a Single User

If only one person is going to use ST/X, your installation is already complete when all files have been extracted from the distribution medium.
To start it, execute:
cd TOP/projects/smalltalk
smalltalk (or "stx", for short)
On some Unix machines, you may get an "stx not found" error message. Then either add "." to your PATH, or type "./stx" instead.

Installing Files for Group Usage

ST/X, as delivered lives in its own directory, and does not need any files to be added to system directories. Especially, no dlls need to be added to the standard "windows" folder.
However, if more than one person are going to use ST/X, it is useful to install the common files in some standard places, and have the private files per-user. This not only saves valuable disk space, but also makes administration and distribution of new code and classes easier.
For most file accesses within ST/X, it uses a searchpath (i.e. a list of directory names in which files are searched), allowing users to override definitions and settings.
By default, the path looks like:
.
$HOME/.smalltalk
$STX_LIBDIR
/usr/local/lib/smalltalk
/usr/lib/smalltalk
where $HOME is your login directory and $STX_LIDIR is a shell environment variable which can be left undefined.
Files are searched for in those directories, in the above order (*).

For example, a personal startup-script "smalltalk.rc" can be put into "HOME/.smalltalk/smalltalk.rc".
Since $HOME comes before "/usr/local/lib/smalltalk" in the searchpath, ST/X will consult this private file; even if some other "smalltalk.rc" file exists there.

There are rare situations, in which the above searchpath is not adequate for a particular setup. Therefore, the searchpath can also be initialized from a shell variable named "STX_SEARCHPATH". If defined, it should contain a colon-separated list of directory names. However, it does not affect the builtin searchpath for VM required files - especially the "symbols.stc" file.

To install the system into some standard place (usually "/usr/local/lib" or "/usr/lib"), you should create the following directories:

/usr/local/lib/smalltalk
/usr/local/lib/smalltalk/source
/usr/local/lib/smalltalk/resources
/usr/local/lib/smalltalk/bitmaps
/usr/local/lib/smalltalk/include
/usr/local/lib/smalltalk/doc
and copy the files from corresponding subdirectories found in "projects/smalltalk" to those new directories. Also, all files ending in ".rc" should be copied to this new directory.

You can also create symbolic links in those directories to point to the files found under your actual TOP.
(don't symlink to the directories; many system's chdir command gets a bit confused when changing back to ".." from a symlinked directory.)

The ST/X executable itself should go to 

	/usr/local/bin/smalltalk
or any other directory in your path. Alternatively, create a symbolic link, or adjust your $PATH variable to have its directory included.

If you do not have access to "/usr/local/lib", you can also put the stuff into any directory you like, and set the shell-variable $STX_LIBDIR to the name of that directory.

Thus, your global directory should look like:

.../source
.../source/*.st
.../resources
.../resources/*.rs
.../resources/*.style
.../include
.../include/symbols.stc (**)
.../bitmaps
.../bitmaps/*.xbm
.../fileIn/...
.../doc/coding
.../doc/misc
.../doc/...
.../smalltalk.rc
.../smalltalk_r.rc
.../display.rc
.../host.rc
.../d_*.rc
.../h_*.rc
.../abbrev.stc
.../patches
and (if "..." is not one of "/usr/lib/smalltalk" or "/usr/local/lib/smalltalk") the shell environment should contain a variable named STX_LIBDIR, which is set to whatever "..." is.

Since compiled code does not include the source code itself, but instead a reference (filename & position) to it, an incorrect installation will lead to no source code being shown in the browser (the "smalltalk.rc"-script which is described below does a quick check and gives a warning).

Also, please do not manually edit the source files themselfes - you will make the position-information in compiled code invalid, and therefore see funny source code (parts only) in the browser.

The free demo package does not include all sources - some stuff is only avaliable in the non-free release. Therefore some methods source will not be visible in the browser's - even with a correct installation.

Building your own Smalltalk

In order to create your own Smalltalk exeutable, which may be linked with additional (or less) precompiled classes, we recommend the following procedure: You may build executables with many classes left out, if these are seldom used at your site - either by modifying individual "Make.proto" files (to change the set of classes in a classLibrary), or by changing the package list (to change the set of classLibraries which are included in the initial executable). (Package definitions for common configurations are found in "configurations/PACKS").

ST/X can execute with a much smaller set of initial classes (even most of the user interface classes can be left out) - due to the autoload mechanism, missing classes will be loaded on demand and installed as bytecode interpreted code.
Of course, this slows down the initial startup. However, the loading will be done only once, since after a snapshot restart, the image will already contain them.

Startup Actions

During startup, ST/X reads a file called "smalltalk.rc" to setup some internal stuff. Since the search for this file is done using the above path, you can put your private "smalltalk.rc" into either the current directory or "HOME/.smalltalk".

This script contains Smalltalk expressions which will first do some display-specific setup (by executing "display.rc"), followed by host-specific setup (executing "host.rc"), and (if present) private definitions from "private.rc".
Finally it launches some default applications (currently the Transcript and Launcher). You can of course add more to this (for example, if you like to arrange for a systemBrowser to come up automatically).
"display.rc" tries to find out the kind of display hardware you are working with and then executes one of the "d_xxx.rc" scripts.Have a look at "display.rc" to see how this is done.
Some display specific scripts are already provided with the system, but you can add your own ones, if you are not happy with those settings. However, please leave the existing "d_xxx.rc"-files unmodified - better add your own new, and call it "d_displayname.rc". Your new "d_xxx.rc" file should set your personal preferences, such as view-look and keyboard mappings (use "d_sample_display.rc" as a guide). Also, keyboard mappings are set up in both "display.rc" and the individual "d_xxx.rc" files. For example, national keyboard variants are set there.

The same strategy is used for host specific setup, which consists mainly of printer setup. "host.rc" tries to find out, what host you are running on (which is NOT always the same as the display in X). Like with the display files, you should leave the existing host files untouched and add a new one, called "h_hostname.rc". Use "h_sample_host.rc" as a guide.

The other startup script "smalltalk_r.rc" is consulted, when a snapshot image is restarted; it also does the display and host setup but does not launch any new applications. Thus, the existing views will reopen after restart, but the look may be different, if started with another DISPLAY setting.

Summary, startup actions:

Please read the document on ``configuration and customization'' for details on how to change ST/X's settings to meat your personal preferences.

Hint:

the above mentioned search-path is valid for all files used and read by ST/X. The order allows both sharing of startup files and individual setups both per user and per project.
For example, you can put global default scripts into "/usr/local/lib", workgroup specific files into "STX_LIBDIR", user private things into each users "HOME/.smalltalk" and finally project specifics into individual subdirectories.
Since bitmaps and resource files are too found along that path, you can even define your private bitmaps (for example: icons), by creating a "bitmaps" directory somewhere in the path and putting your own bitmap files there (most view classes use their abbreviated class name and append ".xbm" to construct the name of the icon bitmap file).

Hint:

actually the above was not completely correct: the name of the startup script is "executable-name.rc" - not strictly "smalltalk.rc". Thus, you can create an application by simply linking to the Smalltalk executable, call it "whatever" and create a corresponding "whatever.rc".

Of course, if you have a full distribution (including the stc-compiler) you can also create stand alone executables.
However, using the same executable for multiple applications (customized by startup scripts) is not as stupid as it may look at first: all UNIX systems share the physical memory of the text space if multiple processes execute the same program. Therefore, all running Smalltalk processes will use the same physical memory containing the code.
Especially in multiuser setups, this may lead to a much better memory utilization than creating multiple standalone applications. (BTW: on Ultrix, this is the reason for those monster executables found in "/usr/bin/X11" ;-)
For systems which support shared libraries, the same is true on a finer grain level: here individual class libraries share their memory.

The above is - of course - only valid for the text segment (i.e. for statically compiled machine instructions). Interpreted bytecode (and also: on the fly generated machine code) has to be placed into the data space. Unless special tricks are used, these data segments are not shared.

Notes

(*) Searchpath
The searchpath is kept in a class variable of the ST class (SystemPath) and can be accessed via class methods. You can add components to the path or change it completely from your startup file "smalltalk.rc" or "private.rc". Obviously, the startup file itself must be found in the initial (default) searchpath to do that.

(**) symbol file
This file is not required for all architectures - in those that do require it, ST/X will NOT work without it or if it is corrupted
(so, never change or remove it).
Also, since this file is read by the VM during early startup time (before any Smalltalk objects exist), a builtin searchpath is used for it (i.e. the setting of the above described searchPath class variable has no effect).
The builtin searchpath for the symbols file is: 

	./include/symbols.stc
	$SMALLTALK_LIBDIR/include/symbols.stc
	$STX_LIBDIR/include/symbols.stc
	/usr/local/lib/smalltalk/include/symbols.stc
	/usr/lib/smalltalk/include/symbols.stc
	/opt/smalltalk/include/symbols.stc
for Unix, and: 
	.\include\symbols.stc
	$SMALLTALK_LIBDIR\include\symbols.stc
	$STX_LIBDIR\include\symbols.stc
	\Programme\eXept\SmalltalkX\include\symbols.stc
	\Programs\eXept\SmalltalkX\include\symbols.stc
	\Programme\SmalltalkX\include\symbols.stc
	\Programs\SmalltalkX\include\symbols.stc
	\SmalltalkX\include\symbols.stc
for MS-Windows systems.

Summary for the Impatient

For the impatient, the following summarizes the installation procedure:

Unix:

	mkdir stxXXX
	cd stxXXX
	tar xvf nameOfArchitectureTarFile
	tar xvf nameOfCommonTarFile
follow this by a quick smoke test: 
	cd stx/projects/smalltalk
	./stx

Windows:

	mkdir stxXXX
	cd stxXXX
	unzip nameOfZipFile (or use Windows Explorer to unzip)
follow this by a quick smoke test: 
	cd stx\projects\smalltalk
	stx

OSX:

	mount "stx.dmg" (double click in the finder)
	drag "stx.app" from the mounted drive to the destination
	double click on "stx.app"

[stx-logo]
Copyright © 1996 Claus Gittinger Development & Consulting
Copyright © 1996 eXept Software AG

<cg at exept.de>
Doc $Revision: 1.38 $ $Date: 2021/03/13 18:24:50 $