3.5 Starting a New Source Tree

After following the examples in earlier chapters, you should have a new archive and new hello-world project within that archive.

In this chapter, we'll walk through the steps of preparing a source tree to be part of that project.

3.5.1 The Intial Source

For the sake of example, let's assume that we have an initial, slightly buggy, implementation of hello-world:

             % cd ~/wd

             % ls
             hello-world

             % cd hello-world

             % ls
             hw.c    main.c

             % cat hw.c

             #include <stdio.h>

             void
             hello_world (void)
             {
               (void)printf ("hello warld");
             }

             % cat main.c

             extern void hello_world (void);

             int
             main (int argc, char * argv[])
             {
               hello_world ();
               return 0;
             }

3.5.2 Initializing a Project Tree

The first step of preparing source is to turn the ordinary source tree into a project tree:

             % cd ~/wd/hello-world

             % tla init-tree hello-world--mainline--0.1

             % ls
             hw.c    main.c  {arch}

Note that we passed init-tree the name of the version in the archive that we'll be working on. init-tree created a new subdirectory in the root of the tree ({arch}).

The {arch} subdirectory indicates that this is the root of a project tree:

             % tla tree-root
             /usr/lord/wd/hello-world

tla knows what archive version this tree is for:

             % tla tree-version
             lord@emf.net--2003-example/hello-world--mainline--0.1

Finally, arch has created something called a patch log for the version passed to init-tree:

             % tla log-versions
             lord@emf.net--2003-example/hello-world--mainline--0.1

We'll explain what patch logs are for in later chapters.

3.5.3 Initializing a Tree Does Not Change an Archive

So far, we've only marked the project tree as source: we haven't yet stored anything new in the archive. We'll get there, but before we do that, there's an important topic to cover first: source inventories. We'll cover that in the next chapter.

3.5.4 What if You Make a Mistake With init-tree?

Suppose that in the example above, we had mis-typed:

             % tla init-tree hello-world--mainlin--0.1

One "brute force" solution is just to delete the {arch} subdirectory and start over. Later on, though, that solution is undesirable: the {arch} subdirectory may contain some data you don't want to delete. So, we'll take this opportunity to introduce a few more advanced commands.

There are two problems after the bogus call to init-tree. The output from both of these commands is not what we want:

             % tla tree-version
             lord@emf.net--2003-example/hello-world--mainlin--0.1

             % tla log-versions
             lord@emf.net--2003-example/hello-world--mainlin--0.1

We can change the tree-version of a tree at any time:

             % tla set-tree-version hello-world--mainline--0.1

             % tla tree-version
             lord@emf.net--2003-example/hello-world--mainline--0.1

Patch logs are a little trickier. We have to delete the logs we don't want, and add those that we do want:

             % tla add-log-version hello-world--mainline--0.1

             % tla log-versions
             lord@emf.net--2003-example/hello-world--mainlin--0.1
             lord@emf.net--2003-example/hello-world--mainline--0.1

             % tla remove-log-version hello-world--mainlin--0.1

             % tla log-versions
             lord@emf.net--2003-example/hello-world--mainline--0.1

WARNING: remove-log-version is a dangerous command: it will remove patch logs that you might need if you ask it to. You should only use remove-log-version when you are certain, as we were above, that what is being removed is one you do not want.

3.5.5 How it Works – Initializing a New Tree

init-tree created the {arch} subdirectory at the root of the source tree. What's in there?

             % ls {arch}
             ++default-version       =tagging-method         hello-world

             % cat {arch}/++default-version
             lord@emf.net--2003-example/hello-world--mainline--0.1

             % cat {arch}/=tagging-method
             [... long output ...]

{arch}/hello-world is the root of a fairly deep tree. Patch logs are stored within that tree.

{arch}/=tagging-method is a configuration file that you can use to customize the naming conventions that apply to this tree. It is explained in a later chapter (see Customizing the inventory Naming Conventions).

Note: You should not, of course, edit the contents of the {arch} directory by hand.