This document walks you through an example use of the Vesta software configuration management system. The tutorial covers the main commands you'll need to know as a Vesta user. Each of these commands has a detailed man page, available both in nroff and HTML format. The HTML man pages have pictures that help to clarify what is going on.
Some of these commands tell you to type long file pathnames. You can of course make symbolic links in your home directory so that you can type shorter names. The "pushd" command, editable history, and tab-completion of filenames (available in some shells) are other handy features that save typing.
For this example, we'll use "jones_hello", where you should replace "jones" by your own user name. Or you could choose any package name that no one else at your site has used yet.
Throughout this tutuorial, you'll notice references to paths starting with "/vesta/play.example.com". You should replace "example.com" with your local site name. This is a name chosen for each Vesta installation which represents your portion of the global Vesta name space, and is traditionally based on a domain you have control over.
The use of "play" is to designate a spearate area for users to experiment (such as when learning Vesta). (Perhaps the data for a real project named "foo" would be stored in "/vesta/foo.example.com" or "/vesta/example.com/foo".) Some sites instead chose to create a "play" directory at a lower level of the hierarchy (e.g. "/vesta/example.com/play"). If you're unsure where your play directory is, try typing:
ls -1d /vesta/play.* /vesta/*/play
If for some reason you can't find one, ask your Vesta administrator. Or, if you are the administrator, become the special wizard user (normally named "vwizard") and type (again, substituting a domain you control for "example.com"):
vmkdir -p /vesta/play.example.com
Type:
vcreate /vesta/play.example.com/jones_hello
vcreate will print out the full path where it creates the package. (Recent versions will first prompt you for a description of the package you are creating.) You should substitue this for "/vesta/play.example.com/jones_hello" throughout this tutorial.
To see what you've done, you can type:
ls -lR /vesta/play.example.com/jones_hello vattrib /vesta/play.example.com/jones_helloThe ls output won't be too interesting: the package has no versions, just an empty directory called "checkout" and a symbolic link called "latest" with nothing to point to. The vattrib output shows you some information about the package.
Aside from the methods mentioned above, you can save yourself a little typing by setting the configuration variable [UserInterface]DefaultPackageParent (in your site's vesta.cfg file) to "/vesta/play.example.com". The repository tools will interpret unqualified paths relative to this, so you could then just type "vcreate jones_hello". If you haven't set it, the default is ".", which means you either need to give the full path on the command line (as above) or change your working directory to where you want to perform an operation:
cd /vesta/play.example.com vcreate ./jones_hello
Type:
vcheckout /vesta/play.example.com/jones_hello
Recent versions will prompt you for a description of the change you're planning on making. To see what you've done, you can type:
ls -lR /vesta/play.example.com/jones_hello vattrib /vesta/play.example.com/jones_hello/1 vattrib /vesta/play.example.com/jones_hello/checkout/1 ls -lR /vesta-work/jones vattrib /vesta-work/jones/jones_hello
This step creates several things: a working directory, a session directory, and a reservation stub.
The working directory is /vesta-work/jones/jones_hello. This is a directory in which you can create and edit files that will go into the package. If you had checked out a package that had existing versions, the directory would have started out with a copy of the last version in it; as it is, the directory starts out empty.
The session directory is a directory for intermediate versions of the package that you make while you are working on it but before you are ready to check it in as version 1. We'll say more about this below.
The reservation stub is /vesta/play.example.com/jones_hello/1. This is a placeholder with the same name that version 1 of the package will have when you check it in. It reserves or "locks" the version number so that two people can't inadvertently work on creating the same new version at the same time.
Type anything that creates one or more files in the working directory; for instance:
cd /vesta-work/jones/jones_hello echo "Hello world" > hello
Type:
vadvance
To see what you've done, you can type:
ls -lR /vesta/play.example.com/jones_hello/checkout/1 diff -r /vesta/play.example.com/jones_hello/checkout/1/1 .
Notice that /vesta/play.example.com/jones_hello/checkout/1/1 is now an exact snapshot of /vesta-work/jones/jones_hello, except that none of the files in the former have write permission. You can make snapshots like this at any time while you have the package checked out. The snapshots are immutable: even if you are vadmin or the superuser, you can't modify the files and directories in them.
Now try typing "vadvance" again without changing anything in the working directory. It's smart enough to notice that no new snapshot is required.
Each time you edit a file in the package and then run vadvance, a new snapshot version is created within the session directory. The directories for the sub-versions are named jones_hello/checkout/1/1, jones_hello/checkout/1/2, jones_hello/checkout/1/3, etc.
Type:
vcheckin
You will be prompted to describe the change you've made. To see what you've done, you can type:
cd ls -lR /vesta-work/jones ls -lR /vesta/play.example.com/jones_hello
What happened? Your working directory was deleted, and the final snapshot from your session directory replaced the stub that was created by vcheckout. Version 1 of your package is now checked in. The checked-in version is immutable, just like the snapshot versions in your session directory.
Type:
vcheckout /vesta/play.example.com/jones_hello
To see what you've done, you can type:
ls -l /vesta-work/jones/jones_hello ls -lR /vesta/play.example.com/jones_hello
Your working directory is back, with its contents initialized to version 1, and you have a session directory and stub for version 2.
cd /vesta-work/jones/jones_hello cp -r /vesta/vestasys.org/examples/hello_c/latest/* . chmod -R u+w . vupdate linux_i386.main.ves
(If you're not using Vesta on Linux i386, substitute the top-level model name for your platform for linux_i386.main.ves. Some of the other standard names used for top-level models include linux_alpha.main.ves, linux_ppc.main.ves, and tru64_alpha.main.ves.)
You can look over the files that are copied in if you like, but we won't explain the model files (linux_i386.main.ves and build.ves) at this point.
The vupdate command shown at the end updates the model files to be sure they import the latest version of the standard development environment at your site. (That is, the compilers, libraries, etc.) It's often a good idea to do this right after you check out a package or copy in some source files that may not have been worked on for a while and may import an older version.
Type:
vmake
If this is the very first time anyone has built anything since you installed Vesta, it may take some time as all the libraries that the program is linked against are built. After that, the Vesta cache will be populated, and only hello.c will be compiled.
The vmake command is really just a convenient shell script that deletes any junk files (like core files and emacs backup files), runs vadvance, and then invokes the Vesta builder (called simply "vesta") on the resulting snapshot. The vadvance is needed because the Vesta builder can build only from immutable sources -- checked in versions or snapshot versions in session directories.
Now try typing "vmake" again. vadvance will notice that nothing has changed, so no new snapshot will be needed. Then the Vesta builder, trying to redo a build it has just done, will get a top-level cache hit and finish almost instantly.
Type:
vmake -shipto /tmp
You could have typed this right away in the previous step, but we wanted to explain building and shipping separately.
This command does the same vmake again, then copies the final output of the build (here the program "hello") into /tmp so that you can try it out. Without the ship flags, vmake (or vesta) simply writes everything you've built into the Vesta cache; it doesn't make any of the output visible in a directory.
Get hello.c into your favorite text editor and make some changes, then repeat the build and/or ship from the last two steps. Do this several times if you like.
If you'd like to build a slightly more complicated program, you can add more .c files to the build.ves model by adding them to the definition of c_files at the top, separated by commas, and if you have .h files, you can add them too. For example:
files
c_files = [ hello.c, goodbye.c ];
h_files = [ greetings.h ];
{
libs = < ./libs/c/libc >;
return ./C/program("hello", c_files, h_files, libs);
}
Suppose that someone else wants to work on the jones_hello package while you have it checked out, or that you want to work on two different sets of changes to the package at once. Perhaps while you're working on some major changes that you aren't ready to check in yet, someone comes to you and asks for a quick bug fix to the latest checked in version. Type:
vbranch /vesta/play.example.com/jones_hello/1.quickfix
To see what you've done, you can type:
ls -lR /vesta/play.example.com/jones_hello
vattrib /vesta/play.example.com/jones_hello/1.quickfix
diff -r /vesta/play.example.com/jones_hello/{1,1.quickfix/0}
The vbranch command creates a branch in the tree of versions for the jones_hello package. The main trunk versions have names like jones_hello/1, jones_hello/2, etc. Versions that branch off of version 1 have names like jones_hello/1.quickfix/1, jones_hello/1.quickfix/2, etc.
The directory jones_hello/1.quickfix is really a new package, but instead of starting out empty like a package made with vcreate does, it starts out with a version 0 that is identical to the version it branched from. This is a simple but powerful concept. You can use vbranch to make any number of branches from any version of any package, including branches from branches.
You check branches in and out just like normal packages. Type:
vcheckout /vesta/play.example.com/jones_hello/1.quickfix
Because you already have another version of the jones_hello package checked out, vcheckout will pick a new working directory name for you. If you've been following the script exactly, the new working directory will be called /vesta-work/jones/jones_hello.1. Here the .1 is just an arbitrary unique number, not related to version numbers.
To see what you've done, type:
ls -l /vesta-work/jones vattrib /vesta-work/jones/jones_hello vattrib /vesta-work/jones/jones_hello.1
Notice how the attributes of the two working directories show you which is which. You are also free to rename your working directories to whatever you like, or to choose names explicitly in the vcheckout command; for the latter, see the description of the -w flag in the vcheckout man page.
Type:
vwhohas /vesta/play.example.com/jones_hello vwhohas -b /vesta/play.example.com/jones_hello
You can also see all active checkouts in your entire repository (though this can take some time if your repository is large) with:
vwhohas
See the vwhohas man page for details on all the options.
Type:
vlatest /vesta/play.example.com/jones_hello ls -l /vesta/play.example.com/jones_hello/latest
These commands use different mechanisms, but both show you what version of jones_hello is the latest. They start to be useful when you have many versions checked in and it becomes tedious to ls the directory and find the highest number by eye. The symbolic link latest is especially handy when you want to look at the latest version in a text editor.
vlatest also has other options:
vlatest -b /vesta/play.example.com/jones_hello
Type:
cd /vesta-work/jones vcheckin jones_hello vcheckin jones_hello.1
Vesta provides no special tools for merging branches. However, because the common base version and the latest version on each branch are kept available as directories, you can use common Unix tools like diff, diff3, and patch to compare versions and merge changes from one branch into another. The common base version of two branches is easy to find given Vesta's version naming conventions. Or, even if you've overridden the default naming convention (which you can do using special flags to the tools) you can trace back from each version to its predecessor by looking at the old-version attributes with vattrib.
If a newly checked-in version logically has two predecessors, because you made it by merging in changes from another branch, you might want to make its old-version attribute show both predecessors. Attribute values are actually sets of strings, so you can do this by adding the second predecessor to the set. For instance, if you copied /vesta/vestasys.org/examples/hello_c/2 into the jones_hello package to make version 2 of jones_hello, you might do this:
vattrib -a old-version /vesta/vestasys.org/examples/hello_c/2 \
/vesta/play.example.com/jones_hello/2
Future Vesta branch merging tools might do this sort of thing automatically.
In general, it's considered bad form to delete anything from the Vesta repository (that is, the part under /vesta, not /vesta-work). The Vesta philosophy is that sources should be immutable and immortal, so that all builds can be reproduced and you can always get back any old code that may be useful later.
Vesta does allow deletion under some very limited circumstances. You can't delete anything from an immutable directory (a version or a subdirectory of a version). You can delete from higher level directories, but a ghost is left behind. A ghost is a null object that prevents a version number from being reused in the future with different contents, which could produce inconsistent builds. A ghost appears in "ls -l" listings with access permissions "---------T".
Usually deletion is restricted to vadmin and the superuser, though you can change that by editing your site's vesta.cfg file.
It is possible to "revive" a ghost by copying the deleted data back into place from another replica; see the vrepl man page referenced in the next section.
Part of the suggested Vesta installation procedure is to replicate a copy of the latest Vesta source code from the public repository. Roughly, that means that the two repositories are the same except for things that are present in one but missing in the other. If the same name is defined in both, it means the same thing in both.
There is a flag on every object in a repository saying whether or not that repository's copy of the object is the master copy. When you have a nonmaster copy of a directory, you are not permitted to insert anything into it except by copying it from another repository. There is a special exception for /vesta itself; you are allowed to create a subdirectory of /vesta using an Internet domain name that belongs to you. Your repository then becomes master for that subdirectory and (by default) everything below it. The Vesta free software project's repository is master for /vesta/vestasys.org, so in your repository, the master flags are off for all directories in that tree. You can see an object's master flag using vattrib.
The vrepl tool is used to copy sources from one repository to another. You can set up semi-automatic replication by running vrepl periodically, using (for example) the Unix cron(8) facility.
As you build new things with Vesta, your cache will grow until it begins to fill up the disk partition you've assigned to it. At that point you'll need to run the weeder to delete some things from the cache. See the VestaWeed man page.
This tutorial should have given you a pretty complete feel for how to use Vesta's source control features. All the commands shown above have many optional flags that modify their behavior, but you will rarely need to give any flags at all.
We've said very little in this tutorial about writing models. You can write models for many simple programs by following the patterns in example/hello_c and example/hello_cxx, extending them to more .c and .h files as shown above. To learn more about writing models, see the SDL programmer's guide.
A good starting point for further reading is the Vesta home page.
Tim Mann (tim@tim-mann.org)
(Corrections are probably better directed to the current maintainer: Ken Schalk <ken@xorian.net>.)