ARM Club 1/ARM_CLUB_CD.iso/contents/apps/program/s/tlib/tlibdoc

Text File | 1990-01-10 | 8.1 KB | 270 lines

tlib - Turbo librarian
======================


Introduction
------------

Maybe this is useful. It's a simple version control system for C source code
(you can use it with basic provided it is stored as text).

Basically you check the source out when you want to change it, and check it
back in when finished. Each time the source changes, the changes are stored.
You can revert to any version at any time.

Any problems or suggestions - drop me a line


How it works
------------

Tlib expects you to have a number of 'projects', called mainfiles for no
good reason. Each of these has a name. For example, if you were to work on a
program called !Glazier, you might call the mainfile glazier.

Now here's the catch. You have to set a system variable called tlib$source
to a directory which holds all the version info. You store all the source
for all your projects in this directory, often something like
'adfs::4.source'. The source for glazier (the shift key isn't working on my
machine) would be stored in adfs::4.source.glazier.

Note that the source is stored in a 'version file' format so you can't just
edit it. You must extract the version you require (generally the latest)
from this version file.


How to use it
-------------

It's all very simple. Firstly you set that variable I mentioned above,
tlib$source to a sensible source directory which you are unlikely to delete
and which is easy to backup.

Secondly you BACK UP ALL YOUR SOURCE so that when tlib completely
obliterates 10 man-years of effort you don't start sending me death threats.
tlib is very stable, and I have used it with lots of projects in the last
couple of years but having said that I haven't yet put S-Base into it.
Mainly bacause S-Base's 4MB of code would take 20MB of disc space by now
with all the changes. Maybe now that 1.0 is done...

Then you set the csd to the directory containing all your source and add a
new mainfile for your project, like this:

   tlib n glazier

This creates a directory source.glazier to hold the source versions. Then
you add each source file to the system one by one (generally clever use of
enumdir and Edit helps here). Make sure you are in the right directory (the
one containing your c & h directories which contain the source you want to
control...)

   dir $.work.glazier
   tlib a glazier c.main
   tlib a glazier h.main
   tlib a glazier h.defs
   tlib a glazier c.wind
   tlib a glazier h.wind
   tlib a glazier c.drag
   tlib a glazier h.drag

etc. you get the idea. You will be asked to describe each source file.
You don't have to be exact. Press <return> on a line by itself to stop
typing comments.

This will create a number of version files called source.glazier.c.main,
source.glazier.h.main, etc. It will also delete the source files (c.main,
h.main) because they are 'checked in'. If you want to modify the files
(perhaps because it's 9am and you're starting work again) you do the
following:

   tlib o glazier

which checks out all the files in glazier. You can check out just one file
if you like:

   tlib o glazier c.main

You can now modify your source as you wish, and at 5pm, type (stick this in
an obey file):

   copy c c/bak
   copy h h/bak
   tlib i glazier

You will be prompted for a comment as to the changes you have made to each
file. Not easy to remember if you haven't checked it in for 3 weeks. You
don't have to enter anything, but it does help you to look back on the
development and locate code you subsequently deleted. Press return on a
blank line to stop entering comments.

This will check in all your changes. Files which haven't changed will just
be deleted. Files which have changed will be compared with the last stored
version and the changes appended to the version file. After the command
completes, all your source will be deleted and the version files will be
updated.

Note you should copy the source to a backup directory in case something goes
wrong. I think this is very unlikely since tlib is careful not to delete the
source unless everything was perfect. But you can get disc errors in the
source files, etc. When you backup, always backup the latest version of the
source as well as the version directory $.source (I don't but I should).
Perhaps tlib should make this easier...

Sometimes you want to look at a source file but don't intend to change it.
You can use

   tlib u glazier c.main

to extract c.main without locking the version file. Obviously you shouldn't
change c.main and you *can't* check it back in with tlib i (since it hasn't
been checked out), but you can look at it.


Listing & regressing
--------------------

After using tlib for a while you will have a number of versions of each
file. You can list the files in the source system using

   tlib l glazier

and you can list the version information with

   tlib v glazier

although individual files á la 'tlib v glazier c.main' is probably more
useful.

If you want to look at how the code looked in an earlier version, type

   tlib r glazier c.main 13

which means to extract a useable (not checked out) of version 13 of the file
to c.main (be careful not to overwrite the real c.main if it is checked
out).



Deleting files
--------------

You can use

   tlib d glazier c.wierd

to delete a source file from sorrce control. This would happen if you want
to rename a source file (there is no proper rename facility) or you find the
file is genuiinely no longer needed. Both these case are fairly rare and you
would normally just leave the file there anyway (it isn't hurting anyone and
it is after all part of the version history of your application.)

Sometimes you get a 'useable' (not checked out) of the whole mainfile and
want to delete it after looking at it. For example:

   tlib u glazier

will extract useable versions of the whole mainfile. To delete this, use

   tlib z glazier.

This will delete c.main, h.main, etc. all the way through. Don't zap a file
if it is checked out (you lose your changes). tlib warns you about this as
it is hardly ever what you want to do.



So...
-----

That's it I think. It should be fairly easy to use. You want two obey files,
one called 'checkout' which says

   tlib o glazier

and one called 'checkin' which says

   copy source to backup directory
   tlib i glazier

You use one at 9am and one at 5pm.



Technical Details
-----------------

From the source...

/* The format for the version files kept in source_dir is:

V           This is the beginning of a new version
T <n>       File type
S <n>       The following n lines contain a comment about this version
I <n>       Insert n lines (which must follow in the version file)
C <a> <b>   Copy lines a to b inclusive in the previous version


eg:


V
S Unix IO library
I 254
wfefwg
wefwefwe
wef
wefwef
... (total of 254 lines)
V
S New function open()
C 1 254
I 45
void open (char *filename, int mode)
wef
wq
q
wq
... (45 lines in total)

*/


So the library file is searchable but it is hard to put a version together
by hand.



Notes
-----

I hope you find this useful. I use it for everything bar S-Base and intend
to use it for that as soon as I get hold of some disc space, so maybe I will
do some enhancements. But I think it is quite useful as it is.

I wrote two other utilities called diff and exdiff which create and
process files containing the C and I stuff. diff creates a difference file
given two text files, exdiff creates the result file given a source file and
a file of differences. If you feel these might be useful I can upload them
as well, but probably you have 50,000 diff utils already which produce a
much more human-readable difference file.

BTW tlib is supposed to be fast, but it does use plenty of memory (~40k +
size of source file + size of version file). It can handle a maximum of 5000
lines in a source file and a maximum line length of 200 characters (for no
reason other than to stop you being a pain, I think). Don't worry, it won't
delete anything if you don't follow these rules, just complain bitterly.



Copyright
---------

(C) 1992 Simon Glass

I retain the copyright on tlib, but you can distribute it of course provided
you supply all the files including this one unmodified.

Any suggestions/bug reports you just never know, I might act on them, to
user 'simon' on Arcade, 081 6542212.