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.

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;
        }

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.

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.

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.

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.