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

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. Whether the code is small or big. 2Sep 2009

3. Reasons for external storage Programs evolve and distributed copies should be kept separately, even if small 3Sep 2009

4. Reasons for external storage -More room needed in the workspace -Backup copies (security) -Modularize code -Code control -Trace history -Find culprits -Etc. 4Sep 2009

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

6. Managing applications Apps have been maintained using a combination of workspace and external storage Code DB workspace 6Sep 2009

7. 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) 7Sep 2009

8. The rest of the world APL stands out APL 8Sep 2009

9. 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 9Sep 2009

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

11. 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 11Sep 2009

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

13. The rest of the world APL doesn’t have to stand out APL 13Sep 2009

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

15. Dyalog V11 This version introduced the scripted form of classes/namespaces Their definitions, including functions in them, can be edited. 15Sep 2009

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

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

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

19. Enter... 19Sep 2009

20. OK, so, what is SALT? 20Sep 2009

21. 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) 21Sep 2009

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

23. Facts -SALT consists in a series of functions stored in ⎕ SE to manipulate the source ( ⎕ SRC & ⎕ CR) 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 23Sep 2009

24. Commands SALT functions are monadic. They -Save classes in files -List files -Explore them -Load them -and more 24Sep 2009

25. SALT stores source in Unicode files whose extension is.dyalog by default.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 25Sep 2009

26. Requirements There are NO special requirements (not even.Net) V11 is the minimum version SALT will run under SALT is packaged and comes in already available with APL 26Sep 2009

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

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

29. 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 29Sep 2009

30. 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 30Sep 2009

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

32. Storing multiple version of a script Every time you modify a script SALT stores the definition in a new file: V0V1 32Sep 2009

33. =? 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 33Sep 2009

34. =? 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 34Sep 2009

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

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

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

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

39. Version Control overview The original files can then be forgotten: repository original files 39Sep 2009

40. Version Control overview You then checkout a subset to work with: repository subset checkout original files 40Sep 2009

41. Version Control overview You then work on the subset for a while: repository subset 41Sep 2009

42. Version Control overview If you are using SALT you maintain the files from APL: subset Dyalog APL 42Sep 2009

43. Version Control overview Every once in a while you update the repository: repository subset Checkin 43Sep 2009

44. Version Control overview When the repository is in a stable state you may produce a new release: repository new release export 44Sep 2009

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

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

47. Enter... 47Sep 2009

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

49. 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... 49Sep 2009

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

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

52. 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! 52Sep 2009

53. 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 53Sep 2009

54. subversion: an example workspace Datagame PoundRobot1SDuck Troopers Master There are 7 namespaces, 5 of which are nested 54Sep 2009

55. 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 55Sep 2009

56. 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 56Sep 2009

57. subversion: an example To create \ROBOTS we only need to: use SALT's function to store the scripted namespaces to the \ROBOTS subfolders (or use the ]save UCMD) 57Sep 2009

58. 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 -makecreates the folder if necessary -convertconverts the namespace to []SRC form 58Sep 2009

59. 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 59Sep 2009

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

61. subversion: an example Here is the final result in Explorer view: 61Sep 2009

62. subversion: an example And here is what 'Pound' looks like: 62Sep 2009

63. At this point we have 2 copies: -The copy in the workspace -The copy on file They are linked subversion: an example 63Sep 2009 Workspace.dyalog files

64. 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. subversion: an example 64Sep 2009

65. subversion: an example We first create a repository, here in \MyRepository: 65Sep 2009

66. We then import our system (ROBOTS) into it: subversion: an example MyRepository Robots import 66Sep 2009

67. 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 67Sep 2009

68. The original source is no longer required. We can get rid of it (or back it up ) subversion: an example 68Sep 2009

69. 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: 69Sep 2009

70. 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\troopersfile:///repo svn add C:\robots\troopers\* subversion: an example 70Sep 2009

71. We can now start working in APL. We have to make sure SALT is enabled: subversion: an example 71Sep 2009

72. We can now start working in APL. We can also state where the working folder is. Here we specify to use our \aplscripts folder: subversion: an example 72Sep 2009

73. Afterwards, when we start Dyalog, SALT should be there: subversion: an example 73Sep 2009

74. Our working directory should be set: subversion: an example 74Sep 2009

75. We can now bring in scripts: subversion: an example 75Sep 2009

76. And edit one of them: subversion: an example 76Sep 2009

77. And edit one of them (3 changes): subversion: an example 77Sep 2009

78. After editing we are prompted to replace: subversion: an example 78Sep 2009

79. We verify the changes have been made: TortoiseSVN : an example 79Sep 2009

80. We can see in explorer that all is there: subversion: an example 80Sep 2009

81. 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) subversion: an example 81Sep 2009 ROBOTS.dyalog files

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

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

84. User Interactions They now look like this: workspace Pound Robot1 SDuck Troopers Data game Master \aplscripts 84Sep 2009

85. 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 85Sep 2009

86. If the workspace is used by more than one person at a time it should reconstruct the links at load time: )load ROBOTS subversion: an example 86Sep 2009 Workspace.dyalog files

87. 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 87Sep 2009

88. We keep making changes in APL... subversion: an example 88Sep 2009

89. ... and committing until happy: subversion: an example 89Sep 2009

90. 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 90Sep 2009

91. We can see in Explorer the new \RobotGame folder: subversion: an example 91Sep 2009

92. TortoiseSVN An integrated disk Explorer GUI front-end for subversion 92Sep 2009

93. TortoiseSVN: an example Using the same ROBOTS example: 93Sep 2009

94. TortoiseSVN: an example We first create an empty repository, here in \MyRepository: -right click on the folder wanted -TortoiseSVN -Create repository here... 94Sep 2009

95. Then we import our current system into it: TortoiseSVN: an example 95Sep 2009

96. 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 96Sep 2009

97. Next we checkout a copy to work with. We will put our working copy in \aplscripts: TortoiseSVN : an example 97Sep 2009

98. Start Dyalog, SALT should be there: TortoiseSVN: an example 98Sep 2009

99. Our working directory should be set: TortoiseSVN : an example 99Sep 2009

100. We can now bring in scripts: TortoiseSVN : an example 100Sep 2009

101. And edit one of them: TortoiseSVN : an example 101Sep 2009

102. And edit one of them: TortoiseSVN : an example 102Sep 2009

103. We verify the changes have been made: TortoiseSVN : an example 103Sep 2009

104. We can see in explorer that all is there: TortoiseSVN : an example 104Sep 2009

105. The files modified are marked using a special icon TortoiseSVN: an example 105Sep 2009

106. We can also ask to see the differences TortoiseSVN: an example 106Sep 2009

107. Here we are using the diff program: TortoiseSVN: an example 107Sep 2009

108. When happy we commit the changes TortoiseSVN: an example 108Sep 2009

109. We keep making changes in APL and committing until happy: TortoiseSVN: an example 109Sep 2009

110. Finally, to produce a finished version we export to a folder we'll use to hold the entire project TortoiseSVN: an example 3 110Sep 2009

111. We can see in Explorer the new \Army folder: TortoiseSVN : an example 111Sep 2009

112. 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! 112Sep 2009

113. 113Sep 2009

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

115. Spice It creates an input area at the bottom of the screen to issue commands using SALT. Spice can be initialized directly from APL: 115Sep 2009

116. Spice In V12 use the options menu: 116Sep 2009

117. Spice Spice can also be started automatically by setting SALT registry key AddSPICE to ‘1’ 117Sep 2009

118. Spice Utilities To get a list of all available commands enter ‘]?’ in the session: 118Sep 2009

119. Spice SVN Utilities Some of those utilities relate to Version Control. They are grouped under svn: 119Sep 2009

120. Spice SVN Utilities Syntax is similar to the command line version Only the names have been changed (slightly) 120Sep 2009

121. Spice: an example Assuming we have the following project involving Dyalog scripts: 121Sep 2009

122. Spice: an example And suppose we have a repository here 122Sep 2009

123. Then we import our current system into it: Spice: an example 123Sep 2009

124. 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 124Sep 2009

125. Next we checkout a copy to work with. We will put our working copy in \aplscripts: Spice : an example 125Sep 2009

126. svnco already sets up our working directory for us Spice : an example Confirmed by the settings command 126Sep 2009

127. We can now bring in scripts: Spice: an example 127Sep 2009

128. And edit one of them (3 changes): Spice: an example 128Sep 2009

129. After editing we are prompted to replace: Spice: an example 129Sep 2009

130. When we are happy with all the changes we can tell subversion to commit the changes we've made. Spice: an example 130Sep 2009

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

132. 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. 132Sep 2009

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

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