@need 3200

@node Starting a New Source Tree
@chapter Starting a New Source Tree

@geindex init-tree

@geindex tree-root

@geindex tree-version

@geindex log-versions

@geindex set-tree-version

@geindex remove-log-version

@geindex add-log-version



After following the examples in earlier chapters, you should have a
new archive and new @code{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.

@need 3200

@section The Intial Source

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

@example
@group
        % cd ~/wd
@end group
@group

@end group
@group
        % ls
        hello-world
@end group
@group

@end group
@group
        % cd hello-world
@end group
@group

@end group
@group
        % ls
        hw.c    main.c
@end group
@group
        
@end group
@group
        % cat hw.c
@end group
@group
        
@end group
@group
        #include <stdio.h>
@end group
@group
        
@end group
@group
        void
        hello_world (void)
        @{
          (void)printf ("hello warld");
        @}
@end group
@group
        
        
@end group
@group
        % cat main.c
@end group
@group
        
@end group
@group
        extern void hello_world (void);
@end group
@group
        
@end group
@group
        int
        main (int argc, char * argv[])
        @{
          hello_world ();
          return 0;
        @}
@end group
@group
@end group
@end example



@need 3200

@section Initializing a Project Tree

The first step of preparing source is to turn the ordinary source tree
into a @geindex project tree
@dfn{project tree}:

@example
@group
        % cd ~/wd/hello-world
@end group
@group

@end group
@group
        % tla init-tree hello-world--mainline--0.1
@end group
@group

@end group
@group
        % ls
        hw.c    main.c  @{arch@}
@end group
@group

@end group
@end example

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


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

@example
@group
        % tla tree-root
        /usr/lord/wd/hello-world
@end group
@group
@end group
@end example

@code{tla} knows what archive version this tree is for:

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

Finally, @code{arch} has created something called a @emph{patch log} for 
the version passed to @code{init-tree}:

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

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




@need 3200

@section 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: @emph{source
inventories}.   We'll cover that in the next chapter.




@need 3200

@section What if You Make a Mistake With init-tree?

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

@example
@group
        % tla init-tree hello-world--mainlin--0.1
@end group
@group
@end group
@end example

One "brute force" solution is just to delete the @code{@{arch@}}
subdirectory and start over.  Later on, though, that solution 
is undesirable: the @code{@{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 @code{init-tree}.  The
output from both of these commands is not what we want:

@example
@group

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

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

@end group
@end example

We can change the @code{tree-version} of a tree at any time:

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

@end group
@end example

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

@example
@group
        % tla add-log-version hello-world--mainline--0.1
@end group
@group

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

@end group
@group
        % tla remove-log-version hello-world--mainlin--0.1
@end group
@group

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

@end group
@end example

@strong{WARNING:} @code{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
@code{remove-log-version} when you are certain, as we were above, that what
is being removed is one you do not want.




@need 3200

@section How it Works -- Initializing a New Tree

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

@example
@group
        % ls @{arch@}
        ++default-version       =tagging-method         hello-world
@end group
@group

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

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

@end group
@end example

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


@code{@{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 @ref{Customizing the inventory Naming Conventions}).


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







