SALT and Version Control

SALT and Version Control

How to handle projects using version controlled SALT

V1.09

Reasons for external storage

Ever since large IT projects have been going on there has been a need to keep code out of the workspace and manage it.

Whether the code is small or big.

2Sep 2009


Programs evolve and distributed copies should be kept separately, even if small

3Sep 2009


- More room needed in the workspace- Backup copies (security)- Modularize code- Code control- Trace history- Find culprits- Etc.

4Sep 2009

Managing applications• Larger applications have to be

maintained whether they are written in APL or not

• You have to keep track of changes to know who's done what and when

• You must be able to undo changes

• Generally cope with (large) system related problems

5Sep 2009

Managing applications

Apps have been maintained using a combination of workspace and external storage

CodeDB

workspace

6Sep 2009

HowIn APL:• APL files (most common way)• Other workspaces ([]CY)• External DBs (e.g. Oracle)• Etc.In other (e.g. compiled) languages• Text files (distributed, e.g. file

system)

7Sep 2009

The rest of the world

APL stands out

APLAPL

8Sep 2009

Managing applications in APLThis makes porting code or even

sharing snippets of it difficult.

- You cannot transport it

- Hard to compare changes

- You need the (proper) interpreter just to VIEW the code

9Sep 2009

Managing applications in APL- You need to maintain the code

management system (CMS) itself

- Employees need time to learn it

- They go away with “useless” skills when they leave

- The IT dptm sees APL as a problem, an outcast

10Sep 2009

Managing applications in APLThere is another way: Unicode text

files

- You can transport them

- You don’t need any interpreter to VIEW them

- They integrate with any text file based control system

11Sep 2009

Managing applications in APL

With existing text based CMS

- You don’t need to write your own CMS

- Employees may already know about it

- They go away with useful skills

- The IT department doesn’t see APL as a non team player

12Sep 2009

The rest of the world

APL doesn’t have to stand out

APLAPL

13Sep 2009

UnicodeWith the wider acceptance of Unicode it has

become easier to share code in text files.

• They can be reorganized e.g. Disk Explorer

• APL code can now be cut & pasted and viewed in Notepad or other Unicode compliant editor/program

• They can be exchanged easily

14Sep 2009

Dyalog V11

• This version introduced the scripted form of classes/namespaces

• Their definitions, including functions in them, can be edited.

15Sep 2009

Dyalog V11

• The definition of objects like classes can be retrieved and manipulated like the definition of functions

• And, like the ⎕CR of a function, it can be stored outside the workspace, e.g. in a text (Unicode) file

16Sep 2009

Requirements

All that is needed to store and retrieve text to any Operating System is a pair of functions to

- Store code to a text file- Read a text file into the workspace

Easy enough to do.

17Sep 2009

Requirements

Of course, once you’ve done that you may want to:

- Save multiple versions- Retrieve any of them- List them- Compare them- Etc.

* Basically manage them *

18Sep 2009

Enter...

19Sep 2009

OK, so, what is SALT?

20Sep 2009

SALTSALT is exactly that:

- A pair of functions to store/retrieve - + other functions to list/compare/etc.- + utility functions (e.g. ease

migration of namespaces to text format)

21Sep 2009

SALT

SALT stands for Simple APL Library Toolkit

It is a source code management system for functions, Classes and script-based Namespaces in Dyalog APL.

22Sep 2009

SALT basics

• SALT is tucked away in ⎕SE - you can )LOAD and run any workspace anytime

• To save a namespace use Save: ⎕SE.SALT.Save 'myns \path\myfile'

• To bring in a namespace use Load: ⎕SE.SALT.Load '\path\myfile'

27Sep 2009

Features

- The editor can be rigged to react on edition of SALTed objects

- The user commands include all the SALT functions, e.g.

]save myns \path\myfile

28Sep 2009

FeaturesSALT can save back a script on file

right after it has been modified.

After modification you are promptedto confirm saving over the present

script file:

Modify <test>

29Sep 2009

Storing a script with a stackThis can happen if you modify a

function of a class on the stack.

After modification you are prompted toconfirm saving over the present script file.Once saved both the script and the class

are modified and you can resume execution.

Error happens

Stack shows upEdit the function

30Sep 2009

Storing multiple version of a script• You can store and KEEP several

versions of a script.• By using the –version modifier

you tell SALT to start using version numbering:

31Sep 2009

Storing multiple version of a script

Every time you modify a script SALTstores the definition in a new file:

V0 V1

32Sep 2009

=?Showing differences between versions

SALT can show the difference between 2 versions of a script, either

- natively, using APL, or

- using a 3rd party Unicode comparison program

33Sep 2009

=?Showing differences between versions

If ‘APL’ is the method chosen to compare,

the output will appear in the session like this: …

…

lines inserted

lines modified

→ is used to denoteinserted lines

← is used to denotedeleted lines

34Sep 2009

SALT features

SALT has many more features

It is UNIX ready

It comes with tools of its own

It can be extended easily by adding

your own utilities

35Sep 2009

SALT limitations

For small applications it may be

sufficient to keep all code on file

managed by SALT

For larger apps this is clearly

inadequate, you need Version

Control on a grander scale

36Sep 2009

What is Version Control (VC)?

VC is a good way to ensure team members of a project don't step over each others' toes.

On a large project it is imperative to use VC.

Otherwise, time (and money) will be lost trying to recover from coordination problems.

Version Control overviewYou usually start by importing an

existing system (a set of files) into a version control repository:

repositoryoriginal

filesimport

38Sep 2009

Version Control overviewThe original files can then be

forgotten:

repositoryoriginal

files

39Sep 2009

Version Control overviewYou then checkout a subset to work

with:

repository

subset

checkout

originalfiles

40Sep 2009

Version Control overviewYou then work on the subset for a

while:

repository

subset

41Sep 2009

Version Control overviewIf you are using SALT you maintain

the files from APL:

subset

Dyalog APL

42Sep 2009

Version Control overviewEvery once in a while you update the

repository:

repository

subset

Checkin

43Sep 2009

Version Control overviewWhen the repository is in a stable

state you may produce a new release:

repositorynew release export

44Sep 2009

VC systems

There are several VC systems out there.

To mention a few: PerForce, ClearCase, Visual SourceSafe, CVS and SubVersion.

There are pros & cons for each.

45Sep 2009

VC systems

In the following slides we'll use subversion as an example.

subversion is a popular open source program.

It is well documented, has a large user base and it's free.

46Sep 2009

Enter...

47Sep 2009

subversion

subversion is a version control system for Unix and Windows.

It is independent of any file system or file types to manage

It is easy to install

48Sep 2009

subversionsubversion comes in command line (shell)

mode.Most commands involve a single program: svn.

For ex:svn import ...svn checkout ...svn checkin ...svn export ...

49Sep 2009

subversion

There are many more commands in subversion.

They handle updates, conflicts, allow to see differences between versions.

The complete list is extensive but well documented.

50Sep 2009

subversion

There is also a GUI front-end for subversion.

This front-end is completely separate but closely integrated to the GUI.

It's name is TortoiseSVN. subversion is integrated.

51Sep 2009

subversionDifferent people prefer different

things:Windows users may choose the GUI

front-end for subversion.Unix users may prefer the shell

environmentAPL users might prefer to stay in APLEither way the results will be the

same: better coordination!52Sep 2009

subversion: an exampleAssuming we have the following

workspace named ROBOTSROBOTS written in Dyalog:

It has 2 top level namespaces in which there are 5 (nested) namespaces:

- namespace Master: 2 namespaces- namespace Troopers: 3 namespaces

53Sep 2009

subversion: an example

workspace

Data game

Pound Robot1SDuck

Troopers

Master

There are 7 namespaces, 5 of which are nested

54Sep 2009


We’ve seen the benefits of using text files for the namespaces:

- easier to visualize the code- easier to maintain- easier to share- no need to have the interpreter to

see it

55Sep 2009

subversion: an exampleWe will create the following folder

named \ROBOTSROBOTS involving Dyalog scripts:

It has 2 folders and 5 scripts:- folder Master: 2 scripts- folder Troopers: 3 scripts

56Sep 2009

subversion: an exampleTo create \ROBOTS we only need to:

use SALT's <Save> function to store the scripted namespaces to the \ROBOTS subfolders (or use the ]save UCMD)

57Sep 2009

subversion: an exampleFor example:To create \ROBOTS\Troopers\Pound.dyalog

all we need to do is]Save Troopers.Pound \ROBOTS\Troopers\

Pound -make –convert-make creates the folder if necessary-convert converts the namespace to []SRC

form

58Sep 2009

subversion: an exampleYou then do the other namespaces:

⎕SE.SALT.Save 'Troopers.SDuck \ROBOTS\Troopers\SDuck -convert '

]Save Troopers.Robot1 \ROBOTS\Troopers\Robot1 -convert

59Sep 2009

subversion: an exampleIf everything in a namespace has to be

SALTed you can do:

⎕CS 'Troopers’

⎕SE.SALT.Snap '\ROBOTS\Troopers -convert -makedir'

60Sep 2009

subversion: an exampleHere is the final result in Explorer

view:

61Sep 2009

subversion: an exampleAnd here is what 'Pound' looks like:

62Sep 2009

At this point we have 2 copies:- The copy in the workspace- The copy on file

They are linked


63Sep 2009

Workspace .dyalogfiles

If we were to stop here (not use subversion) we could )SAVE the workspace and it would remember where everything (all the namespaces) is.

But we need to move them first to a repository.

Let’s carry on.


64Sep 2009

subversion: an exampleWe first create a repository, here in \

MyRepository:

65Sep 2009

We then import our system (ROBOTS) into it:


MyRepositoryRobots import

66Sep 2009

Our system is now in the repository and can be checked out by anyone able to access it.

This can be on the same machine or on the same network.

It can also be across the internet with proper credentials.


67Sep 2009

The original source is no longer required.

We can get rid of it (or back it up )


68Sep 2009

Next we checkout a copy to work with.subversion: an example

MyRepository

aplscripts

checkout

RoXots

We will put our working copy in \aplscripts:

69Sep 2009

If we want to preserve the original location we can check out the empty repository into it after which we add the new material:

• svnadmin create \repo• svn co file:///repo C:\robots\troopers• svn add C:\robots\troopers\*


70Sep 2009

We can now start working in APL.We can also state where the working

folder is.Here we specify to use our \aplscripts

folder:


72Sep 2009

Afterwards, when we start Dyalog, SALT should be there:


73Sep 2009

Our working directory should be set:


74Sep 2009

We can now bring in scripts:


75Sep 2009

And edit one of them (3 changes):


77Sep 2009

After editing we are prompted to replace:


78Sep 2009

We verify the changes have been made:

TortoiseSVN : an example

79Sep 2009

We can see in explorer that all is there:


80Sep 2009

If the workspace is only used by one person at a time it can be saved with the links:)load ROBOTS

)save (when finished editing)


81Sep 2009

ROBOTS .dyalogfiles

Restoring the original workspace

If the workspace is out of sync and needs refreshing)LOAD ROBOTS

And bring back the out of sync code, e.g.:)CS Troopers]load Troopers/Pound)save

82Sep 2009

Restoring the original workspace

If an attempt is made to use an out of sync object SALT will warn you of the fact and confirm your intentions before saving:

83Sep 2009

User InteractionsThey now look like this:

workspace Pound

Robot1

SDuckTroopers

Data

gameMaster

\aplscripts

84Sep 2009

Many users InteractionsThey now look like this:

User 1working on Pound

User 2working on Robot1

workspace Pound

Robot1

SDuckTroopers

Datagame

Master

workspace Pound

Robot1

SDuck Troopers

Datagame

Master

85Sep 2009

If the workspace is used by more than one person at a time it should reconstruct the links at load time:)load ROBOTS


86Sep 2009

Workspace .dyalogfiles

When we are happy with all the changes we can tell subversion to commit the changes we've made:


MyRepository

aplscripts

Checkin

87Sep 2009

We keep making changes in APL...


88Sep 2009

... and committing until happy:


89Sep 2009

Finally, to produce a finished version we export to a folder we'll use to hold the entire project


MyRepositoryRobotGame export

90Sep 2009

We can see in Explorer the new \RobotGame folder:


91Sep 2009

TortoiseSVN

An integrated disk ExplorerGUI front-end for subversion

92Sep 2009

TortoiseSVN: an exampleUsing the same ROBOTS example:

93Sep 2009

TortoiseSVN: an example

We first create an empty repository, here in \MyRepository:

- right click on the folder wanted

- TortoiseSVN- Create repository

here...

94Sep 2009

Then we import our current system into it:


95Sep 2009


This can be on the same machine or on the same network.

It can also be across the internet with proper credentials.


96Sep 2009

Next we checkout a copy to work with.



97Sep 2009

Start Dyalog, SALT should be there:


98Sep 2009

Our working directory should be set:


99Sep 2009



100Sep 2009

And edit one of them:


101Sep 2009

And edit one of them:


102Sep 2009

We verify the changes have been made:


103Sep 2009

We can see in explorer that all is there:


104Sep 2009

We can also ask to see the differences


106Sep 2009

Here we are using the diff program:


107Sep 2009

When happy we commit the changes


108Sep 2009

Finally, to produce a finished version we export to a folder we'll use to hold the entire project


3

110Sep 2009

We can see in Explorer the new \Army folder:


111Sep 2009

Control Version environmentsWhatever environment suits best your

needs there is another alternative.

The APL alternative: drive svn from APL

This presumes subversion is installed of course!

112Sep 2009

113Sep 2009

Spice

This is a separate tool.

It uses a special syntax to issue commands.

To use it start statements with ], e.g.]mycmd

114Sep 2009

Spice Utilities

To get a list of all available commands enter ‘]?’ in the session:

118Sep 2009

Spice SVN UtilitiesSome of those utilities relate to Version

Control.They are grouped under svn:

119Sep 2009

Spice SVN UtilitiesSyntax is similar to the command line versionOnly the names have been changed (slightly)

120Sep 2009

Spice: an exampleAssuming we have the following

project involving Dyalog scripts:

121Sep 2009

Spice: an example

And suppose we have a repository here

122Sep 2009

Then we import our current system into it:

Spice: an example

123Sep 2009


Spice: an example

repository

checkout

subset

checkout

subset

subset

subset

checkoutcheckout

124Sep 2009

Next we checkout a copy to work with.


Spice : an example

125Sep 2009

svnco already sets up our working directory for us

Spice : an example

Confirmed by the settings command

126Sep 2009


Spice: an example

127Sep 2009

And edit one of them (3 changes):

Spice: an example

128Sep 2009

After editing we are prompted to replace:

Spice: an example

129Sep 2009

When we are happy with all the changes we can tell subversion to commit the changes we've made.

Spice: an example

130Sep 2009

The use of svn under Spice is just another possibility.

The choice to use the shell commands, TortoiseSVN or Spice is a personal matter.

What is important is to ensure proper synchronisation between team members and subversion provides just that.

Conclusion

133Sep 2009

Wait, how do I use this?

Subversion and TortoiseSVN are available from the Net.

SALT/Spice come with Dyalog ready for use.

You will find on your memory stick a presentation on how to port an APL application into SALT.

134Sep 2009

Documents

SALT and Version Control