Compatibility Notes (How to migrate from an older ST/X version

This page leads you towards possible incompatibility problems, when migrating from an older ST/X version.
Although we try to mention all possible trouble spots, we can neither guarantee 100% compatibility, nor can we guarantee listing all possible trouble spots in the list below.
(after all, we are all humans and "to err is human". However, we put a lot of effort in trying to maintain backward compatibility as much as possible.)

5.4.2 to 5.4.3

Unicode filename support

You should be prepared to now receive unicode strings (Unicode16String) when asking a directory for its contents. This should be transparent for most applications. However, expect problems, if you use a WriteStream on a String to collect text which contains such filenames.
Instead of:

s := WriteStream on:String new

you should use:

s := CharacterWriteStream on:String new

CharacterWriteStream is smart enough to automatically adjust the underlying collection and change it from String to Unicode16String or even Unicode32String if required. The contents returned by CharacterWriteStream will use the best representation. That means that for strings which can be represented using single bytes, you will get a String as before.

Of course, you may also expect problems if you destructively access a string with at:put:, trying to put a 16bit character into an 8bit String instance.

5.3 to 5.4

Instance variable changes in libview

The following instance variables have been eliminated from DisplaySurface / SimpleView:

    middleButtonMenu
    keyCommands
    gotExpose

these are now stored in a "moreAttributes" dictionary or the "flags" instVar. (i.e. the functionality and getters/setters are still there, but stored in another place).

The saved instVar slots are reused, so that subclasses do not have an instVar-index recompilation problem. This means that the instVar index of all other instVars remains the same, so that binary compiled class libraries with subclasses of SimpleView are still compatible (this is of special importance to customer libraries).

NOTICE:
all direct accesses to middleButtonMenu and keyCommands MUST be replaced by getter/setter calls.

5.1 to 5.2

Unicode support in Change-, Patch and Sourcefiles

Starting with 5.2, unicode is supported by corresponding String-classes (Unicode16String) and by the tools (editors, compilers etc) and external source files are utf8 enoded. For backward compatibility, files as read by the changeBrowser, fileBrowser and stc-compiler are considered to be 8859-1 encoded, UNLESS there is an utf8 encoding-hint found near the beginning of the input file. Encoding-hints look like

     Encoding: utf8

and are typically placed into a comment (or a compiler pragma comment).
This should ensure that old source files (which are 8859-1 encoded) are still compilable, while newly created files will be utf8 encoded.

Make sure to clear any existing changeFiles, as change records will be appended utf8-encoded by the new version (if you want to use old change-files with the new release).

Application code should be prepared to get Unicode16Strings as the result of messages like #asLowercase etc.

5.1.4 to 5.1.5

HTTPService authentication

HTTPService authentication changed from #authenticationFor: which returns a boolean to #authenticateFor: which reports the error directly. This was changed to allow for the service to generate its own error message and/or to return an alternative fallback document.

5.1.1 to 5.1.2

Subclasses of HTTPService

The inheritance of the HTTPService hierarchy has changed, and another abstract class named HTTPSelecorService was added. You might have to change the superclass of your HTTPService subclasses from HTTPService to HTTPSelecorService.

4.x to 5.x

PositionableStream and Subclasses

The major incompatible change relates to stream positioning: ST/X used to define the initial read/write position as 1, while all other Smalltalks defined it to be 0. (i.e. ST/X defined the position as "the position of the next element", whereas all others defined it as "the position of the last processed element".)
This incompatibility was due to the fact that the stream positioning was not defined in the blue book, and 1-based positions seem to be logical w.r.t. the 1-based indexing of collections.
The position-bias has been changed in order to make porting of code from other Smalltalk systems easier.

Starting with 4.1.9, 4 methods were added to aid in writing portable code:

    position0Based / position0Based:
    position1Based / position1Based:

These methods are still (and will still be) present, to allow for code to be written which works on any system.

All code which computes a stream position or takes a stream position as collection index, using position and/or position: should either:

be changed to invoke position1Based and/or position1Based:
or be changed to care for 0-based position values.

Error Handling when opening FileStreams

Prior to release 5 no error exception has been raised when opening or creating of a FileStream failed. A Notification has been signaled to those, who explicitly handled this notification. Most classes did not handle this notification and got a nil-return, when doing e.g. '/nonExistingFile' asFilename readStream.

From Release 5 on, FileStream openErrorSignal is an error exception and the same as ExternalStream openErrorSignal.

For conversion of old programs expecting (and checking for) nil, a new method Filename»readStreamOrNil has been introduced. Please use the Filename interface, and avoid using FileStreams directly.

Class

The layout of Classes has changed, by removing unused instance variables. This means, that old binary class libraries and object files are no longer compatible. You must stc-recompile your own machine code libraries and object files.

Bytecode binaries, source files or autoloaded classes are not affected, and do not need special care.

<info@exept.de>

Doc $Revision: 1.23 $ $Date: 2016/11/05 17:38:36 $