SALT and Version Control
How to handle projects using
version controlled SALT
V1.07
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, e.g.
- More room needed in the workspace
- Backup copies (security)
- Modularize code
- Code control
- Etc.
Oct 2008
2
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
Oct 2008
3
Managing applications
Apps have been maintained using a
combination of workspace and external
storage
Code
DB
workspace
Oct 2008
4
How
In APL:
• APL files (most common)
• Other workspaces ([]CY)
• External DBs (e.g. Oracle)
• Etc.
In other (e.g. compiled) languages
• Text files
Oct 2008
5
APL stands out
APL
The rest of the world
Oct 2008
6
Managing applications in APL
This 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
Oct 2008
7
Managing applications in APL
There 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
Oct 2008
8
APL doesn’t have to stand
out
APL The rest of the world
Oct 2008
9
Unicode
With the wider acceptance of Unicode it has
become easier to share code in text files.
• They can be reorganized using Disk Explorer
• APL code can now be cut & pasted and
viewed in Notepad or other Unicode
compliant editor/program
• It can be distributed
Oct 2008
10
Dyalog V11
• This version introduced the scripted
form of classes/namespaces
• Their definitions, including functions in
them, can be edited.
Oct 2008
11
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
Oct 2008
12
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.
Oct 2008
13
Requirements
Of course, once you’ve done that you
may want to:
-
Save multiple copies
Retrieve any of them
List them
Compare them
Etc.
* Basically manage them *
Oct 2008
14
Enter...
Oct 2008
15
OK, so, what is
SALT?
Oct 2008
16
SALT
SALT 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)
Oct 2008
17
SALT
SALT stands for
Simple APL Library Toolkit
It is a source code management system
for functions, Classes and scriptbased Namespaces in Dyalog APL.
Oct 2008
18
SALT basics
• SALT is tucked away in ⎕SE, this
means 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'
Oct 2008
23
Features
SALT can save back a script on file right
after it has been modified.
Modify <test>
After modification you are prompted
to confirm saving over the present
script file:
Oct 2008
24
Storing a script with a stack
This can happen if you modify a function
of a class on the stack.
Stack shows up
Edit the function
After
modification you are prompted to
Error happens
confirm saving over the present script file.
Once saved both the script and the class
are modified and you can resume execution.
Oct 2008
25
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:
Oct 2008
26
Storing multiple version of a script
Every time you modify a script SALT
stores the definition in a new file:
V0
V1
Oct 2008
27
=?
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
Oct 2008
28
=?
Showing differences between
versions
If ‘APL’ is the method chosen to compare,
the output will appear in the session like this:
…
…
→ is used to denote
inserted lines
lines inserted
lines modified
← is used to denote
deleted lines
Oct 2008
29
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
Oct 2008
30
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
Oct 2008
31
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 overview
You usually start by importing an existing
system (a set of files) into a version
control repository:
original
files
import
Oct 2008
repository
33
Version Control overview
The original files can then be forgotten:
original
files
repository
Oct 2008
34
Version Control overview
You then checkout a subset to work with:
original
files
repository
subset
Oct 2008
35
Version Control overview
You then work on the subset for a while:
repository
subset
Oct 2008
36
Version Control overview
If you are using SALT you maintain the
files from APL:
Dyalog APL
subset
Oct 2008
37
Version Control overview
Every once in a while you update the
repository:
repository
subset
Oct 2008
38
Version Control overview
When the repository is in a stable state
you may produce a new release:
new release
export
Oct 2008
repository
39
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.
Oct 2008
40
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.
Oct 2008
41
Enter...
Oct 2008
42
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
Oct 2008
43
subversion
subversion comes in command line (shell) mode.
Most commands involve a single program: svn.
For ex:
svn import ...
svn checkout ...
svn checkin ...
svn export ...
Oct 2008
44
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.
Oct 2008
45
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 will be installed if not there.
Oct 2008
46
subversion
Different people prefer different things:
Windows users may choose the GUI
front-end for subversion.
Unix users may prefer the shell
environment
APL users might prefer to stay in APL
Either way the results will be the same:
better coordination!
Oct 2008
47
subversion: an example
Assuming we have the following
workspace named ROBOTS written in
Dyalog:
It has 2 top level namespaces in which
there are 5 (nested) namespaces:
- namespace Master: 2 namespaces
- namespace Troopers: 3 namespaces
Oct 2008
48
subversion: an example
There are 7 namespaces, 5 of which are nested
Master
Data
game
workspace
Troopers
Pound SDuck Robot1
Oct 2008
49
subversion: an example
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
Oct 2008
50
subversion: an example
We will create the following folder named
\ROBOTS involving Dyalog scripts:
It has 2 folders and 5 scripts:
- folder Master: 2 scripts
- folder Troopers: 3 scripts
Oct 2008
51
subversion: an example
To create \ROBOTS we only need to:
use SALT's <Save> function to store the
scripted namespaces to the \ROBOTS
subfolders
Oct 2008
52
subversion: an example
For example:
To create \ROBOTS\Troopers\Pound.dyalog
we will simply ask <Save> to do it for you:
⎕SE.SALT.Save 'Troopers.Pound
\ROBOTS\Troopers\Pound -convert'
Oct 2008
54
subversion: an example
You then do the other namespaces:
⎕SE.SALT.Save 'Troopers.SDuck
\ROBOTS\Troopers\SDuck -convert‘
⎕SE.SALT.Save 'Troopers.Robot1
\ROBOTS\Troopers\Robot1 -convert'
Oct 2008
55
subversion: an example
If everything in a namespace has to be
SALTed you can do:
⎕CS 'Troopers’
⎕SE.SALT.Snap '\ROBOTS\Troopers –
convert -makedir'
Oct 2008
56
subversion: an example
Here is the final result in Explorer view:
Oct 2008
57
subversion: an example
And here is what 'Pound' looks like:
Oct 2008
58
subversion: an example
If we were to stop here (not use
subversion) we could )SAVE the
workspace as it would remember where
everything (all the namespaces) is.
But we need to move them first to a
repository.
Let’s carry on.
Oct 2008
59
subversion: an example
We first create a repository, here in
\MyRepository:
Oct 2008
60
subversion: an example
We then import our system (ROBOTS) into
it:
Robots
import
Oct 2008
MyRepository
61
subversion: an example
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.
Oct 2008
62
subversion: an example
The original source is no longer required.
We can get rid of it (or back it up  )
Oct 2008
63
subversion: an example
Next we checkout a copy to work with.
We will put our working copy in \aplscripts:
X
Ro
MyRepository
ots
aplscripts
Oct 2008
64
subversion: an example
There is another way to do this if we want to
preserve the original location by checking
out INTO it an empty repository to which
we add the new material:
• svnadmin create \repo
• svn co file:///repo C:\robots\troopers
• svn add C:\robots\troopers\*
Oct 2008
65
subversion: an example
We can now start working in APL.
We have to make sure SALT is enabled:
Oct 2008
66
subversion: an example
We can also state where the working folder is.
Here we specify to use our \aplscripts folder:
Oct 2008
67
subversion: an example
Afterwards, when we start Dyalog, SALT
should be there:
Oct 2008
68
subversion: an example
Our working directory should be set:
Oct 2008
69
subversion: an example
We can now bring in scripts:
Oct 2008
70
subversion: an example
And edit one of them (3 changes):
Oct 2008
72
subversion: an example
After editing we are prompted to replace:
Oct 2008
73
TortoiseSVN : an example
We verify the changes have been made:
Oct 2008
74
subversion: an example
We can see in explorer that all is there:
Oct 2008
75
Restoring the original workspace
We can now go back to the original
workspace to work from there:
)LOAD ROBOTS
)CS Troopers
[]SE.SALT.Load 'Troopers/Pound'
now in updated script form
Oct 2008
76
User Interactions
\aplscripts
They now look like this:
Master
Data
game
workspace
Pound
Troopers
SDuck
Robot1
Oct 2008
77
Many users Interactions
They now look like this:
User 1
working on Pound
Master
User 2
working on Robot1
Data Master
game
Data
game
Pound
workspace
Pound
Troopers SDuck
SDuck
Robot1
Robot1
workspace
Oct 2008
Troopers
78
subversion: an example
When we are happy with all the changes
we can tell subversion to commit the
changes we've made:
MyRepository
aplscripts
Oct 2008
79
subversion: an example
We keep making changes in APL...
Oct 2008
80
subversion: an example
... and committing until happy:
Oct 2008
81
subversion: an example
Finally, to produce a finished version we export to
a folder we'll use to hold the entire project
RobotGame
export
Oct 2008
MyRepository
82
subversion: an example
We can see in Explorer the new
\RobotGame folder:
Oct 2008
83
TortoiseSVN
An integrated disk Explorer
GUI front-end for subversion
Oct 2008
84
TortoiseSVN: an example
Using the same ROBOTS example:
Oct 2008
85
TortoiseSVN: an example
We first create an
empty repository,
here in
\MyRepository:
- right click on the
folder wanted
- TortoiseSVN
- Create repository
here...
Oct 2008
86
TortoiseSVN: an example
Then we import
our current
system into it:
Oct 2008
87
TortoiseSVN: an example
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.
Oct 2008
88
TortoiseSVN : an example
Next we
checkout a
copy to work
with.
We will put our
working copy
in
\aplscripts:
Oct 2008
89
TortoiseSVN: an example
Start Dyalog, SALT should be there:
Oct 2008
90
TortoiseSVN : an example
Our working directory should be set:
Oct 2008
91
TortoiseSVN : an example
We can now bring in scripts:
Oct 2008
92
TortoiseSVN : an example
And edit one of them:
Oct 2008
93
TortoiseSVN : an example
And edit one of them:
Oct 2008
94
TortoiseSVN : an example
We verify the changes have been made:
Oct 2008
95
TortoiseSVN : an example
We can see in explorer that all is there:
Oct 2008
96
TortoiseSVN: an example
We can also
ask to see
the
differences
Oct 2008
98
TortoiseSVN: an example
Here we are using the diff program:
Oct 2008
99
TortoiseSVN: an example
When happy
we commit
the
changes
Oct 2008
100
TortoiseSVN: an example
Finally, to produce
a finished
version we
export to a
folder we'll use
to hold the
entire project
3
Oct 2008
102
TortoiseSVN : an example
We can see in Explorer the new \Army folder:
Oct 2008
103
Control Version environments
Whatever environment suits best your
needs there is another alternative.
The APL alternative: drive svn from APL
This presumes subversion is installed of
course!
Oct 2008
104
Oct 2008
105
Spice
This is a SALT tool.
It uses a special syntax to issue commands
using SALT.
To use it start statements with ], e.g.
]mycmd
Oct 2008
106
Spice Utilities
To get a list of
all available
commands
enter ‘]?’ in
the session:
Oct 2008
110
Spice SVN Utilities
Some of those utilities relate to Version Control.
They are grouped under svn:
Oct 2008
111
Spice SVN Utilities
Syntax is similar to the command line version
Only the names have been changed (slightly)
Oct 2008
112
Spice: an example
Assuming we have the following project
involving Dyalog scripts:
Oct 2008
113
Spice: an example
And suppose
we have a
repository
here
Oct 2008
114
Spice: an example
Then we import our current system
into it:
Oct 2008
115
Spice: an example
Our system is now in the repository and
can be checked out by anyone able to
access it.
subset
subset
repository
subset
subset
Oct 2008
116
Spice : an example
Next we
checkout a
copy to work
with.
We will put our
working copy
in \aplscripts:
Oct 2008
117
Spice : an example
svnco already
sets up our
working
directory for
us
Confirmed by the
settings command
Oct 2008
118
Spice: an example
We can now bring in scripts:
Oct 2008
119
Spice: an example
And edit one of them (3 changes):
Oct 2008
120
Spice: an example
After editing we are prompted to replace:
Oct 2008
121
Spice: an example
When we are
happy with all
the changes
we can tell
subversion to
commit the
changes
we've made.
Oct 2008
122
Conclusion
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.
Oct 2008
125
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.
Oct 2008
126
Descargar

SALT and subversion