2008 1

Converting workspaces and

using SALT & subversion to

maintain them.V1.01

2008 2

Introduction

This is an example of converting an existing application to SALT and using a version control system afterwards to maintain it.

2008 3

What is SALT?

SALT is a tool to deal with code outside the workspace in text (Unicode) format.

Script formUp until V11 namespaces came in a

single form.They contained functions, variables

and other namespaces.

2008 4

Script formStarting with V11 namespaces also

came in a script form.The contained functions, etc. are

listed in text format:

2008 5

Script formThe script and the functions in it can

be edited via the editor, e.g.)ED ns2)ED ns2.tfn1

2008 6

2008 7

How do we do it?

• We'll see the conversion process and• how to use subversion, a third party

product, to control its versioning

2008 8

The situation

• BAAD is a military weapons manufacturing company

• One of its best sellers is the SD2, a device used to search and destroy specific targets

2008 9

BAAD's SD2 product

• This unit is self contained: its behaviour is set once and does not require external input.

• There are several (possibly 1000s) models, each with a different code name. The logic (code) of each is unique.

2008 10

BAAD's SD2 product

• Unit is made of 2 main components:

- a driving component- a weapons component

2008 11

Testing the product

• Obviously, testing these devices in real life presents a problem

• In its infinite wisdom the company has decided to use a simulator written in (what else?) Dyalog APL

• A single workspace holds all the system

2008 12

The simulator

Battling units

Units'Consoles

Battlefield

2008 13

The simulator

2008 14

The simulator's structure• The workspace is divided into

namespaces• One namespace contains all the

units' logic, here its name is 'R' (for Robots)

• Each unit's logic is also contained in a namespace whose name is the name of the unit (like CARLA or AI2)

2008 15

The simulator's structure

Here, namespace RR is where all the Units' logic reside

2008 16

Updating the workspace • This involves modifying individual

units' code in their respective namespaces

• and resaving the entire workspace when finished with the changes

• This prevents other users from updating the workspace at the same time

2008 17

Acceptable updating timeline

Time

Tester A

Tester B

load

load

save

save

change

change

Sequential updates

2008 18

Unacceptable updating timeline

Time

Tester A

Tester B

load

load

save

save

change

change

Tester A's changes are overwritten by Tester Beven if the modified namespace is different

2008 19

Tracking changes

Another problem with this model is that changes are irreversible.

Even tracking changes is difficult.

Finding differences in code is hard to document.

2008 20

Dyalog V11.0This version allows namespaces to

exist in script format.

Instead of havinga series of namespaces each with functions and variables

2008 21

Dyalog V11.0You can have

everything in script form, including the definition of variables

2008 22

Scripts files

Keeping namespaces in scripted form allows us to save them in (Unicode) text files outside the workspace.

workspace

2008 23

Updating can now be done in parallel for different namespaces

Tester A

Tester B

load

save

change

Tester A's changes are NOT overwritten by Tester B

Timelo

adsave

change

namespace A

namespace B

2008 24

Tracking changes

It is easier to track changes now that files are in human readable format.

By saving multiple copies we can see the difference between each modification.

workspace

2008 25

Tracking changes

Comparing files can be done easily in APL by SALT or by any 3rd party program.

Line aLine bLine c

Line aLine XLine c

2008 26

Doing it

The first step is to convert the workspace to the new form

2008 27

Start Dyalog, SALT should be there:

Converting the workspace

2008 28

If it isn’t we have to make sure SALT is enabled:

Converting the workspace

2008 29

)LOAD our workspace:

Converting the workspace

2008 31

Bring in the conversion tools:

Converting the workspace

2008 32

ConvertCode is a namespace containing code to perform conversion of regular (non sourced) namespaces.

The function to use in it is <Convert>.

Converting the workspace

2008 33

For example, to convert namespace 'UTIL':

Converting the workspace

2008 34

To convert several namespaces first )CS where the namespaces are:

Converting the workspace

2008 35

Then use an expression like:

Converting the workspace

2008 36

Explorer now shows us the namespaces with the new icons:

Converting the workspace

2008 37

The workspace has the same functionality as before.

It can be )SAVEd in this new format

Converting the workspace

2008 38

Filing away

The next step is to store those namespaces in Unicode files.

Altho is it relatively simple to read/write text to file, their management is a bit more complex.

Again, SALT comes in handy.

2008 39

Saving the scripts as text files

1. decide where to put them

2. use the SALT Save function

2008 40

Saving the scripts as text filesThe Save function takes a string

argument of: 'namespace location':

2008 41

Saving the scripts as text filesTo save all the namespaces at once

do:

2008 42

Saving the scripts as text filesIf you want to save everything at

once you can do instead

2008 43

Saving the scripts as text filesEither way you should now have a

folder with many scripts in it:

2008 44

Making changes

SALT 'remembers' where each script was saved.

Changing one of them now means SALT will change the file as soon as the script is modified through the editor.

2008 45

Making changesHere's what one of the units' logic looks like:

2008 46

Making changesAnd here we make a change:

2008 47

Making changesSALT detected the change and offers to change the script file:

2008 48

Making changes

You should )SAVE the workspace here.

Like this SALT will remember where the edited namespaces are stored and detect if changes have been made outside APL (e.g. with Notepad)

2008 49

Version Control

This is the 2nd part of the work to do.

SALT comes with its own versioning of files and comparison functions but it is primitive compared to state of the art version control systems like subversion.

2008 50

Version Control

For a company like BAAD it is preferable to use existing software like subversion.

To use subversion we first need somewhere to put the scripts files.

2008 51

Version ControlWe picked folder \weapons as

repository

2008 52

Version Control

We now import the scripts into the repository:

(we put our code in 'Troops')

2008 53

Version Control

One of the testers now checks out a copy:

2008 54

Version Control

Any other tester can do the same thing and update it independently.

repository

checkout

tester x

checkouttester 7

tester n

tester 3

checkoutcheckout

2008 55

Version Control

He can see what's in his folder

2008 56

Version Control

And use any portion (pattern) of it

2008 60

Version Control

He can now repeat this procedure each time he )LOADs the workspace or )SAVE his own copy (e.g. 'tester1robots') which can be )loaded instead.

2008 61

Version ControlHe, and any other tester that has

done the same thing, can now test the system and update it independently.

repository

tester x

tester 7

tester n

tester 3

Modifying the code

2008 62

Viewing changes

2008 63

Viewing changes

2008 64

2008 65

Version Control

When changes are ready to be checked in you do (here DANIMAL has been changed)

2008 66

Version ControlHe, and any other tester that has

done the same thing, can now test the system and update it independently.

repository

tester x

tester 7

tester n

tester 3

commit

commit

commit

commit

2008 67

Version Control

The VC should be able to handle conflicts, report on differences and generate complete new systems from the current repository.

2008 68

Conclusion

For local or smaller systems you may choose to use SALT's limited versioning and comparing abilities but a solid Version Control system is a must for large systems.

2008 69

Conclusion

Any version control will probably do but subversion is well supported and well documented.

And it's free.