The APL Wiki Repository

Contents

  1. The APL Wiki Repository
    1. Overview
    2. Installing SubVersion
    3. Information about SubVersion
    4. Using SubVersion
      1. Exploring the Repository
        1. trunk
        2. branches
        3. tags
        4. Space considerations
    5. Getting hold of ADOC
      1. Checking out
      2. Test cases
    6. Conclusion

Overview

SubVersion, the software the APL wiki repository is based on, is a code management system. By definition, code management systems don't forget anything. When a particular version of a software gets saved, it can be restored with little effort, even when hundreds of new versions got saved since.

But Code Management Systems allow much more than only serving as a kind of backup:

Setting a SubVersion server up and make it running is nothing you can do in half an hour, but you don't have to - It's already available on the APL wiki server.

Installing SubVersion

To install SubVersion for client purposes is easy. You can download it from:

http://www.collab.net/downloads/subversion/

After having installed SubVersion (no options, no silly questions, nothing to worry about!) make sure that you add the path of the svn.exe to your PATH variable, so you can call svn from any directory.

Information about SubVersion

The SubVersion guys do offer a book themselves which can be downloaded for free. To be honest: it's not the very best choice. Understandably they have to mention any detail, but that's probably not what you are looking for, you simply need some basic commands which are just fine for your every day work.

Therefore, I recommend Mike Mason's "Pragmatic Version Control" which can be downloaded from

http://svnbook.red-bean.com/en/1.1/svn-book.pdf

It's based on SubVersion 1.1, but don't worry, anything you need hasn't changed at all.

Using SubVersion

Once you have installed SubVersion and set the PATH variable properly, you can start to use SubVersion.

Exploring the Repository

To find out what's available, open a console window and enter: 

      svn list svn://aplwiki.com/os
apl2/
aplwin/
aplx/
dyalog/

Your list might actually look different: in the meantime somebody might have added something.

Note that:

  1. "svn" is the command, it calls svn.exe.

  2. "list" is a parameter that tells svn that we want to list the contents of the repository. "list" might be called a sub-command.

  3. "svn://" defines the protocol. SubVersion does not use http but it's own protocol to communicate with the server.

  4. "aplwiki.com" is the domain of the repository we are interested in
  5. "os" specifies the top-level-directory within the repository we are interested in. "os" stands for "Open Source".

Let's look into the "dyalog" sub-project. Don't write "Dyalog" - SubVersion is fussy about that. Enter this command: 

      svn list svn://aplwiki.com/os/dyalog
ADOC/
APLTeamUtils/
Hash/
IniFiles/
Logger/
ShowChmHelp/
WinFile/
WinReg/
WindowsEventLog/

Again, your list might look different.

Now, if you are interested in ADOC, you have to enter this: 

      svn list svn://aplwiki.com/os/dyalog/ADOC
branches/
tags/
trunk/

but what's that?!

You will see these sub-directories in every sub-project. They are a kind of standard, not only in the APL wiki or even in the SubVersion universe but in virtually all code management systems in the world.

Of course they have a well-defined meaning:

trunk

Contains the current development thread. Therefore this should be used only if you want to contribute to the current development thread because this version might well be a bit dodgy right now. With the obvious exception that a developer may ask you to use this version because it's close to release anyway.

branches

At a particular point in time, the trunk is copied into branches/.

That happens when the decision is made that for a particular version, say 1.2, developing new features is now stopped. Of course bugs still need to get fixed, but in terms of new features it's frozen.

After taking a copy, Development can be continued in the trunk, say for a future version 2.0.

tags

When finally the decision is made that version 1.2 is ready to go to the customers, you certainly want to make sure that you can reproduce a snapshot of all files belonging to that version.

By definition no changes are made to any tags after being created, since otherwise it would effectively become a branch.

Space considerations

What exactly is the impact on disk space when we take a copy of the trunk to either tags or branches? Very little, actually. Instead of copying anything at all, SubVersion remembers the version number. This is called "smart copy".

Only when a particular file is actually changed (by definition this can happen only to branches but not tags), that file is copied over. In other words: SubVersion does not waste any disk space.

Getting hold of ADOC

For using ADOC it is simpler to download the script from it's wiki page (ADOC). However, if you are going to integrate any of the sub-projects from the Open Source directory, you need the test cases as well.

For this you must check out ADOC from the SubVersion repository. That's what we are going to do now.

Note that so far everything we mentioned was vendor independent. The remaining stuff in this article uses ADOC, which is a class written in Dyalog APL. So actually trying the example is Dyalog specific. However, the SubVersion part remains the same with any other APL dialect.

Checking out

To actually download the latest development version of the ADOC script and all the stuff associated with it you have to CheckOut it in SubVersion speak.

To do so follow these steps:

  1. Create an new empty directory. Of course you can also use an existing one, but it must be empty, otherwise svn refuses to cooperate. We will assume that the name of new directory is myADOC.

  2. Open a console window inside the directory myADOC

  3. Enter this command: 

svn checkout svn://aplwiki.com/os/dyalog/ADOC/trunk .

Important: Note the dot at the end of the command line. Without the dot you will find that SubVersion copies the ADOC stuff into a sub-directory "trunk". 

C:\aplapl\myADOC>dir
 Volume in drive C has no label.
 Volume Serial Number is E43C-2925

 Directory of C:\aplapl\myADOC

08/08/2009  10:26    <DIR>          .
08/08/2009  10:26    <DIR>          ..
08/08/2009  10:26         2,412,700 ADOC.dws
08/08/2009  10:26           103,785 ADOC.dyalog
08/08/2009  10:26    <DIR>          demo
08/08/2009  10:26           142,848 Introduction.doc
08/08/2009  10:26             1,721 print.css
08/08/2009  10:26               375 readme.txt
08/08/2009  10:26             2,382 screen.css
08/08/2009  10:26    <DIR>          testcases
               6 File(s)      2,663,811 bytes
               4 Dir(s)  18,688,147,456 bytes free

The list might differ from what you see, since new files might have been added or deleted since this article was written.

Test cases

Start Dyalog APL, load the workspace ADOC and then run: 

#.TestCases.RunAll 1

The right argument is supposed to be a Boolean. A 1 runs all test cases under error trapping, a 0 doesn't, so a failing test makes the program stop.

Note that all sub-projects of APLAPL are supposed to offer test cases except in the rare cases were test cases simply are to difficult/expensive or even impossible to implement. Preferably the test cases should be implemented in the same way; that makes it easier to get into this.

Conclusion

That's what you need to know about the APL wiki code repository from a "consumers" point of view.

As a developer/contributor you need further information. See SubVersionForDevelopers for details.

Author: KaiJaeger

CategoryAplRepository

AplWikiRepository (last edited 2010-04-21 08:30:06 by KaiJaeger)