SALT and Version Control

1. SALT and Version Control How to handle projects using version controlled SALT V1.06

2. 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

3. 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

4. workspace Code DB Managing applications Apps have been maintained using a combination of workspace and external storage Oct 2008

5. 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

6. APL stands out The rest of the world APL Oct 2008

7. 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

8. Managing applications in APL There is another way: 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

9. APL doesn’t have to stand out The rest of the world APL Oct 2008

10. 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

11. Dyalog V11 • This version introduced the scripted form of classes/namespaces • Their definitions, including functions in them, can be edited. Oct 2008

12. 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

13. 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

14. 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

15. Enter... SALT Oct 2008

16. OK, so, what is SALT? Oct 2008

17. 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

18. SALT SALT stands for Simple APL Library Toolkit Itis a source code management system for functions, Classes and script-based Namespaces in Dyalog APL. Oct 2008

19. 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

20. 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

21. 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 confirm saving over the present script file. Once saved both the script and the class are modified and you can resume execution. Error happens Oct 2008

22. 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

23. Storing multiple version of a script Every time you modify a script SALT stores the definition in a new file: V0 V1 Oct 2008

24. =? 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

25. → is used to denote inserted lines ← is used to denote deleted lines =? lines inserted lines modified Showing differences between versions If ‘APL’ is the method chosen to compare, the output will appear in the session like this: Oct 2008

26. 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

27. 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 may need Version Control on a grander scale Oct 2008

28. 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.

29. original files repository import Version Control overview You usually start by importing an existing system (a set of files) into a version control repository: Oct 2008

30. Version Control overview The original files can then be forgotten: original files repository Oct 2008

31. original files repository checkout subset Version Control overview You then checkout a subset to work with: Oct 2008

32. Version Control overview You then work on the subset for a while: repository subset Oct 2008

33. Version Control overview If you are using SALT you maintain the files from APL: Dyalog APL subset Oct 2008

34. Version Control overview Every once in a while you update the repository: repository Checkin subset Oct 2008

35. repository new release export Version Control overview When the repository is in a stable state you may produce a new release: Oct 2008

36. 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

37. 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

38. Enter... subversion Oct 2008

39. subversion subversion is a version control system for Unix and Windows. It is independent of any file system or file types to manage Oct 2008

40. subversion subversion comes in command line (shell) mode. Most commands involve program svn. For ex: svn import ... svn checkout ... svn checkin ... svn export ... Oct 2008

41. 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

42. 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

43. 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

44. 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

45. workspace Master Data game Troopers Pound SDuck Robot1 subversion: an example There are 7 namespaces, 5 of which are nested Oct 2008

46. 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

47. 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

48. subversion: an example To create \ROBOTS we will • use SALT's conversion tools to transform the non-scripted namespaces into scripted form • use SALT's <Save> function to store the scripted namespaces to the \ROBOTS subfolders Oct 2008

49. subversion: an example For example: To create \ROBOTS\Troopers\Pound.dyalog we will • ConvertCode.ConvertTroopers.Pound • ⎕SE.SALT.Save 'Troopers.Pound \ROBOTS\Troopers\Pound' Oct 2008

50. subversion: an example Here is the final result in Explorer view: Oct 2008