VSE-S8 Migration Guide

[View] [Edit] [Lock] [References] [Attachments] [History] [Home] [Changes] [Search] [Help]

VSE-S8 Migration Guide

Preparing for migration

This section will describe, the minimal pre-requisites to start a migration process
Depending on what is the migration target (applications, UI framework, non UI frameworks, etc) you should identify modules or fragments of your code and fileOut them in several (st or cls) files. It is recomended that content of such files meets some functional meaning, for further testings phase. To ensure this process, you will need to group classes that can be tested (if possible) as whole. For example: DB access, UI related, core-model, I/O socket related, or any framework, etc.

Migration process

This section will describe, in a general form, the migration process, how to apply the "migration kit" and what requires a manual modification of source code and how can be done.
The migration starts applying the "migration kit" on building phase. Any module or source code fragment must be compiled in conjunction of a set of classes and method definitions to ensure most general compatibility cases. In the building process the migration kit is a set of source(.st) files that will be loaded before target. Later, a private patch redefining classes and/or methods is used to adapt specific target issues. These redefinitions are aimed to overcome impedance between S8 underliying javascript and VSE.
In the build process (see Working with real cases to see detailed build process) you should define a fileIn list as following:

VSE2S8Common.st
VSE2S8Collections.st
VSE2S8Exceptions.st
VSE2S8Stream.st
VSE2S8Geometry.st
VSE2S8Console.st
VSE2S8UI.st
target-to-migrate.st
private-target-patch.st

(Note: VSE2S8Console.st & VSE2S8UI.st are mutually exclusive, depending on specific migration scenary)

All VSE2S8*.st files belongs to the migration-kit and is still changing periodically. The remaining correspond to specific migration target part where you should pay special attention in syntax issues, string and number manipulation (see below sections)

Migrating non UI parts

Syntax issues

S8 compiler can manipulate strings & symbols as the same way (There is no Symbol class in S8). A literal can be 'myString' or #myString both forms are supported although S8 global names must be in a mandatory symbol form as #MyGlobalName.
Literal arrays must have # for:

subarrays
uppercase string literals/symbols.

VSE is more relaxed and allows to define literal arrays omiting # character. As a use case you can see an example of this issue in IDLSourceFile class>>defaultInterfacesDefinitions in hReader sample framework. Original source code as follows:

!IDLSourceFile class methods !
defaultInterfacesDefinitions
   " Private -  Returns the definitions for default interfaces. "
   ^#(
      ( 'IUnknown' ( '#QueryInterface|AddRef|Release' ) none )
   )! !

and must be changed to:

!IDLSourceFile class methodsFor: #VSECompat !
defaultInterfacesDefinitions
   " Private -  Returns the definitions for default interfaces. "
   ^#(
      #( #IUnknown #( #QueryInterface|AddRef|Release ) #none )
   )! !

Core-Model issues

This section will describe several topics (in a general way) about core-model compatibility. String, Collection, Exception, Number.
Major difference between S8 and VSE is String manipulation, Collection, Stream, Exception & Number. In most cases these incompatibilities can be treated with migration-kit.
Basically:

Collection hierrachy in VSE is larger than S8 counterpart. Treated in VSE2S8Collections.st
Stream hierarchy in vSE is larger than S8 counterpart. Treated in VSE2S8Stream.st
Exception hierarchy is larger than S8 counterpart. Treated in VSE2S8Exceptions.st
Number hierarchy is larger than S8 counterpart. Non treated yet.
S8 String (javascript string) is readonly where VSE String is not. Treated in VSE2S8Collections.st
Object, BlockClosure, CharacterConstant, Message and common adaptations. Treated in VSE2S8Common.st

Depending on what kind of execution enviroment the migrated target is going to run -native/console mode, web mode- IO file operations could be adapted to specific need.

In web-mode (for more detailed information see UI8) input could be done throug text pane widgets or using AJAX-like operations. This is treated in VSECompat-UI8.st
In native/console enviroment some aspect of VSE File class were adapted to S8 allowing IO file operations. This is treated in VSECompat-Console.st

Streams issues

String issues

Exception issues

Collection issues

Number issues

Number specific issues & considerations
S8 have only one class for numbers. It is bound to Number implementation of javascript. The arithmetic operations are handled by the execution environment (implementation of diferent types of numbers are handlen internally by the execution environment).

Working with real cases

Migration is an iterative process. As the migration progresses the developer will gain deeply understand of target and its goals. Also as a general recommendation the migration procces it should never change target behaviour. Such modification should be treated in a further stage of development.
The next sections aims to show a detailed description of how can be done the whole migration process.

Migrating StReader