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.
Sep 2009
2
Reasons for external storage
Programs evolve and distributed copies
should be kept separately, even if small
Sep 2009
3
Reasons for external storage
-
More room needed in the workspace
Backup copies (security)
Modularize code
Code control
Trace history
Find culprits
Etc.
Sep 2009
4
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
Sep 2009
5
Managing applications
Apps have been maintained using a
combination of workspace and external
storage
Code
DB
workspace
Sep 2009
6
How
In 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)
Sep 2009
7
APL stands out
APL
The rest of the world
Sep 2009
8
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
Sep 2009
9
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
Sep 2009
10
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
Sep 2009
11
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
Sep 2009
12
APL doesn’t have to stand
out
APL The rest of the world
Sep 2009
13
Unicode
With 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
Sep 2009
14
Dyalog V11
• This version introduced the scripted
form of classes/namespaces
• Their definitions, including functions in
them, can be edited.
Sep 2009
15
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
Sep 2009
16
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.
Sep 2009
17
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 *
Sep 2009
18
Enter...
Sep 2009
19
OK, so, what is
SALT?
Sep 2009
20
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)
Sep 2009
21
SALT
SALT stands for
Simple APL Library Toolkit
It is a source code management system
for functions, Classes and scriptbased Namespaces in Dyalog APL.
Sep 2009
22
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'
Sep 2009
27
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
Sep 2009
28
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:
Sep 2009
29
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.
Sep 2009
30
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:
Sep 2009
31
Storing multiple version of a script
Every time you modify a script SALT
stores the definition in a new file:
V0
V1
Sep 2009
32
=?
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
Sep 2009
33
=?
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
Sep 2009
34
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
Sep 2009
35
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
Sep 2009
36
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
Sep 2009
repository
38
Version Control overview
The original files can then be forgotten:
original
files
repository
Sep 2009
39
Version Control overview
You then checkout a subset to work with:
original
files
repository
subset
Sep 2009
40
Version Control overview
You then work on the subset for a while:
repository
subset
Sep 2009
41
Version Control overview
If you are using SALT you maintain the
files from APL:
Dyalog APL
subset
Sep 2009
42
Version Control overview
Every once in a while you update the
repository:
repository
subset
Sep 2009
43
Version Control overview
When the repository is in a stable state
you may produce a new release:
new release
export
Sep 2009
repository
44
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.
Sep 2009
45
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.
Sep 2009
46
Enter...
Sep 2009
47
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
Sep 2009
48
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 ...
Sep 2009
49
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.
Sep 2009
50
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.
Sep 2009
51
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!
Sep 2009
52
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
Sep 2009
53
subversion: an example
There are 7 namespaces, 5 of which are nested
Master
Data
game
workspace
Troopers
Pound SDuck Robot1
Sep 2009
54
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
Sep 2009
55
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
Sep 2009
56
subversion: an example
To 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)
Sep 2009
57
subversion: an example
For 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
Sep 2009
58
subversion: an example
You then do the other namespaces:
⎕SE.SALT.Save 'Troopers.SDuck
\ROBOTS\Troopers\SDuck -convert '
]Save Troopers.Robot1
\ROBOTS\Troopers\Robot1 -convert
Sep 2009
59
subversion: an example
If everything in a namespace has to be
SALTed you can do:
⎕CS 'Troopers’
⎕SE.SALT.Snap '\ROBOTS\Troopers
-convert -makedir'
Sep 2009
60
subversion: an example
Here is the final result in Explorer view:
Sep 2009
61
subversion: an example
And here is what 'Pound' looks like:
Sep 2009
62
subversion: an example
At this point we have 2 copies:
- The copy in the workspace
- The copy on file
Workspace
.dyalog
files
They are linked
Sep 2009
63
subversion: an example
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.
Sep 2009
64
subversion: an example
We first create a repository, here in
\MyRepository:
Sep 2009
65
subversion: an example
We then import our system (ROBOTS) into
it:
Robots
import
Sep 2009
MyRepository
66
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.
Sep 2009
67
subversion: an example
The original source is no longer required.
We can get rid of it (or back it up  )
Sep 2009
68
subversion: an example
Next we checkout a copy to work with.
We will put our working copy in \aplscripts:
X
Ro
MyRepository
ots
aplscripts
Sep 2009
69
subversion: an example
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\*
Sep 2009
70
subversion: an example
We can now start working in APL.
We can also state where the working folder is.
Here we specify to use our \aplscripts folder:
Sep 2009
72
subversion: an example
Afterwards, when we start Dyalog, SALT
should be there:
Sep 2009
73
subversion: an example
Our working directory should be set:
Sep 2009
74
subversion: an example
We can now bring in scripts:
Sep 2009
75
subversion: an example
And edit one of them (3 changes):
Sep 2009
77
subversion: an example
After editing we are prompted to replace:
Sep 2009
78
TortoiseSVN : an example
We verify the changes have been made:
Sep 2009
79
subversion: an example
We can see in explorer that all is there:
Sep 2009
80
subversion: an example
If the workspace is only used by one
person at a time it can be saved with
the links:
)load ROBOTS
ROBOTS
.dyalog
files
)save (when finished editing)
Sep 2009
81
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
Sep 2009
82
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:
Sep 2009
83
User Interactions
\aplscripts
They now look like this:
Master
Data
game
workspace
Pound
Troopers
SDuck
Robot1
Sep 2009
84
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
Sep 2009
Troopers
85
subversion: an example
If the workspace is used by more than
one person at a time it should
reconstruct the links at load time:
)load ROBOTS
Workspace
.dyalog
files
Sep 2009
86
subversion: an example
When we are happy with all the changes
we can tell subversion to commit the
changes we've made:
MyRepository
aplscripts
Sep 2009
87
subversion: an example
We keep making changes in APL...
Sep 2009
88
subversion: an example
... and committing until happy:
Sep 2009
89
subversion: an example
Finally, to produce a finished version we export to
a folder we'll use to hold the entire project
RobotGame
export
Sep 2009
MyRepository
90
subversion: an example
We can see in Explorer the new
\RobotGame folder:
Sep 2009
91
TortoiseSVN
An integrated disk Explorer
GUI front-end for subversion
Sep 2009
92
TortoiseSVN: an example
Using the same ROBOTS example:
Sep 2009
93
TortoiseSVN: an example
We first create an
empty repository,
here in
\MyRepository:
- right click on the
folder wanted
- TortoiseSVN
- Create repository
here...
Sep 2009
94
TortoiseSVN: an example
Then we import
our current
system into it:
Sep 2009
95
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.
Sep 2009
96
TortoiseSVN : an example
Next we
checkout a
copy to work
with.
We will put our
working copy
in
\aplscripts:
Sep 2009
97
TortoiseSVN: an example
Start Dyalog, SALT should be there:
Sep 2009
98
TortoiseSVN : an example
Our working directory should be set:
Sep 2009
99
TortoiseSVN : an example
We can now bring in scripts:
Sep 2009
100
TortoiseSVN : an example
And edit one of them:
Sep 2009
101
TortoiseSVN : an example
And edit one of them:
Sep 2009
102
TortoiseSVN : an example
We verify the changes have been made:
Sep 2009
103
TortoiseSVN : an example
We can see in explorer that all is there:
Sep 2009
104
TortoiseSVN: an example
We can also
ask to see
the
differences
Sep 2009
106
TortoiseSVN: an example
Here we are using the diff program:
Sep 2009
107
TortoiseSVN: an example
When happy
we commit
the
changes
Sep 2009
108
TortoiseSVN: an example
Finally, to produce
a finished
version we
export to a
folder we'll use
to hold the
entire project
3
Sep 2009
110
TortoiseSVN : an example
We can see in Explorer the new \Army folder:
Sep 2009
111
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!
Sep 2009
112
Sep 2009
113
Spice
This is a separate tool.
It uses a special syntax to issue commands.
To use it start statements with ], e.g.
]mycmd
Sep 2009
114
Spice Utilities
To get a list of
all available
commands
enter ‘]?’ in
the session:
Sep 2009
118
Spice SVN Utilities
Some of those utilities relate to Version Control.
They are grouped under svn:
Sep 2009
119
Spice SVN Utilities
Syntax is similar to the command line version
Only the names have been changed (slightly)
Sep 2009
120
Spice: an example
Assuming we have the following project
involving Dyalog scripts:
Sep 2009
121
Spice: an example
And suppose
we have a
repository
here
Sep 2009
122
Spice: an example
Then we import our current system
into it:
Sep 2009
123
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
Sep 2009
124
Spice : an example
Next we
checkout a
copy to work
with.
We will put our
working copy
in \aplscripts:
Sep 2009
125
Spice : an example
svnco already
sets up our
working
directory for
us
Confirmed by the
settings command
Sep 2009
126
Spice: an example
We can now bring in scripts:
Sep 2009
127
Spice: an example
And edit one of them (3 changes):
Sep 2009
128
Spice: an example
After editing we are prompted to replace:
Sep 2009
129
Spice: an example
When we are
happy with all
the changes
we can tell
subversion to
commit the
changes
we've made.
Sep 2009
130
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.
Sep 2009
133
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.
Sep 2009
134
Descargar

SALT and subversion