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

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. 2Oct 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 3Oct 2008

4. Managing applications Apps have been maintained using a combination of workspace and external storage Code DB workspace 4Oct 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 5Oct 2008

6. The rest of the world APL stands out APL 6Oct 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 7Oct 2008

8. 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 8Oct 2008

9. The rest of the world APL doesn’t have to stand out APL 9Oct 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 10Oct 2008

11. Dyalog V11 This version introduced the scripted form of classes/namespaces Their definitions, including functions in them, can be edited. 11Oct 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 12Oct 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. 13Oct 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 * 14Oct 2008

15. Enter... 15Oct 2008

16. OK, so, what is SALT? 16Oct 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) 17Oct 2008

18. 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. 18Oct 2008

19. Facts -SALT consists in a series of functions stored in ⎕ SE to manipulate the source ( ⎕ SRC) of objects. -The source code for each APL object is stored in a single Unicode text file with a file extension of “.dyalog”. -All functions take a string to do their work. -This string describes completely the arguments for the function 19Oct 2008

20. Commands SALT functions are monadic. They -Save classes in files -List files -Explore them -Load them -and more 20Oct 2008

21. SALT stores source in Unicode (UCS-2) files whose extension is.Dyalog.Dyalog files are configured to be opened automatically with Notepad under Windows upon V11 installation Under Unix the naming of the files is case sensitive. Storage 21Oct 2008

22. Requirements There are NO special requirements (not even.Net) V11 is the minimum version SALT will run under It needs to be enabled to use it SALT is packaged and comes in already available with V11 22Oct 2008

23. 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' 23Oct 2008

24. Features SALT can save back a script on file right after it has been modified. After modification you are prompted to confirm saving over the present script file: Modify 24Oct 2008

25. Storing a script with a stack This can happen if you modify a function of a class on the stack. 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 Stack shows up Edit the function 25Oct 2008

26. 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: 26Oct 2008

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

28. =? Showing differences between versions SALT can show the difference between 2 versions of a script, either -natively, using APL, or -using a 3 rd party Unicode comparison program 28Oct 2008

29. =? 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 denote inserted lines ← is used to denote deleted lines 29Oct 2008

30. 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 30Oct 2008

31. 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 31Oct 2008

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

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

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

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

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

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

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

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

40. 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. 40Oct 2008

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

42. Enter... 42Oct 2008

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

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

45. 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. 45Oct 2008

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

47. 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! 47Oct 2008

48. subversion: an example ROBOTS 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 48Oct 2008

49. subversion: an example workspace Datagame PoundRobot1SDuck Troopers Master There are 7 namespaces, 5 of which are nested 49Oct 2008

50. 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 50Oct 2008

51. subversion: an example ROBOTS 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 51Oct 2008

52. subversion: an example To create \ROBOTS we only need to: use SALT's function to store the scripted namespaces to the \ROBOTS subfolders 52Oct 2008

53. subversion: an example For example: To create \ROBOTS\Troopers\Pound.dyalog we will 1. ⎕ SE.SALT.Load ’lib/NStoScript’ 2.ConvertCode.Convert Troopers.Pound 3. ⎕ SE.SALT.Save 'Troopers.Pound \ROBOTS\Troopers\Pound' 53Oct 2008

54. subversion: an example For example: To create \ROBOTS\Troopers\Pound.dyalog we will simply ask to do it for you: ⎕ SE.SALT.Save 'Troopers.Pound \ROBOTS\Troopers\Pound -convert' 54Oct 2008

55. 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' 55Oct 2008

56. subversion: an example If everything in a namespace has to be SALTed you can do: ⎕ CS 'Troopers’ ⎕ SE.SALT.Snap '\ROBOTS\Troopers – convert -makedir' 56Oct 2008

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

58. subversion: an example And here is what 'Pound' looks like: 58Oct 2008

59. 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 200859 subversion: an example

60. We first create a repository, here in \MyRepository: 60Oct 2008

61. We then import our system (ROBOTS) into it: subversion: an example MyRepository Robots import 61Oct 2008

62. 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. subversion: an example 62Oct 2008

63. The original source is no longer required. We can get rid of it (or back it up ) subversion: an example 63Oct 2008

64. Next we checkout a copy to work with. subversion: an example MyRepository aplscripts checkout Ro X ots We will put our working copy in \aplscripts: 64Oct 2008

65. 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\troopersfile:///repo svn add C:\robots\troopers\* subversion: an example 65Oct 2008

66. We can now start working in APL. We have to make sure SALT is enabled: subversion: an example 66Oct 2008

67. We can also state where the working folder is. Here we specify to use our \aplscripts folder: subversion: an example 67Oct 2008

68. Afterwards, when we start Dyalog, SALT should be there: subversion: an example 68Oct 2008

69. Our working directory should be set: subversion: an example 69Oct 2008

70. We can now bring in scripts: subversion: an example 70Oct 2008

71. And edit one of them: subversion: an example 71Oct 2008

72. And edit one of them (3 changes): subversion: an example 72Oct 2008

73. After editing we are prompted to replace: subversion: an example 73Oct 2008

74. We verify the changes have been made: TortoiseSVN : an example 74Oct 2008

75. We can see in explorer that all is there: subversion: an example 75Oct 2008

76. 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 76Oct 2008

77. User Interactions They now look like this: workspace Pound Robot1 SDuck Troopers Data game Master \aplscripts 77Oct 2008

78. Many users Interactions They now look like this: User 1 working on Pound User 2 working on Robot1 workspace Pound Robot1 SDuck Troopers Data game Master workspace Pound Robot1 SDuck Troopers Data game Master 78Oct 2008

79. When we are happy with all the changes we can tell subversion to commit the changes we've made: subversion: an example MyRepository aplscripts Checkin 79Oct 2008

80. We keep making changes in APL... subversion: an example 80Oct 2008

81. ... and committing until happy: subversion: an example 81Oct 2008

82. Finally, to produce a finished version we export to a folder we'll use to hold the entire project subversion: an example MyRepository RobotGame export 82Oct 2008

83. We can see in Explorer the new \RobotGame folder: subversion: an example 83Oct 2008

84. TortoiseSVN An integrated disk Explorer GUI front-end for subversion 84Oct 2008

85. TortoiseSVN: an example Using the same ROBOTS example: 85Oct 2008

86. TortoiseSVN: an example We first create an empty repository, here in \MyRepository: -right click on the folder wanted -TortoiseSVN -Create repository here... 86Oct 2008

87. Then we import our current system into it: TortoiseSVN: an example 87Oct 2008

88. 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. TortoiseSVN: an example 88Oct 2008

89. Next we checkout a copy to work with. We will put our working copy in \aplscripts: TortoiseSVN : an example 89Oct 2008

90. Start Dyalog, SALT should be there: TortoiseSVN: an example 90Oct 2008

91. Our working directory should be set: TortoiseSVN : an example 91Oct 2008

92. We can now bring in scripts: TortoiseSVN : an example 92Oct 2008

93. And edit one of them: TortoiseSVN : an example 93Oct 2008

94. And edit one of them: TortoiseSVN : an example 94Oct 2008

95. We verify the changes have been made: TortoiseSVN : an example 95Oct 2008

96. We can see in explorer that all is there: TortoiseSVN : an example 96Oct 2008

97. The files modified are marked using a special icon TortoiseSVN: an example 97Oct 2008

98. We can also ask to see the differences TortoiseSVN: an example 98Oct 2008

99. Here we are using the diff program: TortoiseSVN: an example 99Oct 2008

100. When happy we commit the changes TortoiseSVN: an example 100Oct 2008

101. We keep making changes in APL and committing until happy: TortoiseSVN: an example 101Oct 2008

102. Finally, to produce a finished version we export to a folder we'll use to hold the entire project TortoiseSVN: an example 102Oct 2008 3

103. We can see in Explorer the new \Army folder: TortoiseSVN : an example 103Oct 2008

104. 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! 104Oct 2008

105. 105Oct 2008

106. Spice It uses a special syntax to issue commands using SALT. To use it start statements with ], e.g. ]mycmd This is a SALT tool. 106Oct 2008

107. Spice It creates an input area at the bottom of the screen to issue commands using SALT. Spice can be initialized directly from APL: This is a SALT tool. 107Oct 2008

108. Spice In V12 use the options menu: This is a cover for SALT. 108Oct 2008

109. Spice Spice can also be started automatically by setting SALT registry key AddSPICE to ‘1’ 109Oct 2008

110. Spice Utilities To get a list of all available commands enter ‘]?’ in the session: 110Oct 2008

111. Spice SVN Utilities Some of those utilities relate to Version Control. They are grouped under svn: 111Oct 2008

112. Spice SVN Utilities Syntax is similar to the command line version Only the names have been changed (slightly) 112Oct 2008

113. Spice: an example Assuming we have the following project involving Dyalog scripts: 113Oct 2008

114. Spice: an example And suppose we have a repository here 114Oct 2008

115. Then we import our current system into it: Spice: an example 115Oct 2008

116. Our system is now in the repository and can be checked out by anyone able to access it. Spice: an example repository checkout subset checkout subset checkout 116Oct 2008

117. Next we checkout a copy to work with. We will put our working copy in \aplscripts: Spice : an example 117Oct 2008

118. svnco already sets up our working directory for us Spice : an example Confirmed by the settings command 118Oct 2008

119. We can now bring in scripts: Spice: an example 119Oct 2008

120. And edit one of them (3 changes): 120Oct 2008 Spice: an example

121. After editing we are prompted to replace: 121Oct 2008 Spice: an example

122. When we are happy with all the changes we can tell subversion to commit the changes we've made. Spice: an example 122Oct 2008

123. Real life examples SALT and An international APL code repository

124. The Project The entire SALT project is in a public repository. It is available at http://salt.svn.beanstalkapp.com/ Another project for sharing code is under way. 124Oct 2008

125. 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 125Oct 2008

126. 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. 126Oct 2008