Projects - Getting Started With Arch

This page attempts to make the process of getting a project started with Arch a bit less painful. It is slanted for helping those who want to help contribute to Emacs Muse, but hopefully it may be found helpful for other uses.

[ Top: Arch Tutorial ]
[ This is Part 1: Getting Started With Arch ]
[ Next is Part 2: Developing With Arch ]

Installing Arch

Please see the instructions on Arch Wiki: Getting Arch and Arch Wiki: Installing Arch.

Introducing yourself

When you commit changes to an archive, Arch will need to know who you are. It puts this information at the beginning of the change log for each entry you commit.

tla my-id 'Jane Doe <email@address.org>'

Setting up your own Arch archive

Before you can work on your own stuff with Arch, you will need to create an archive. An archive is the place where all of your different projects are installed. You might want to make separate archives for your private and public projects. You might also want to put the current year in the name of the archive so that you can have a fresh start every year.

Terminology note

I often use the word repository in place of archive, sometimes by accident. I like the term repository because it seems to convey a sense of "upper level holding place" for projects. Maybe that's my experience with CVS coming out.

• First, pick a good location for it. You will probably want to keep all of your archives under a common directory, like {archives}. If you don't like the curly braces in that name, you can use whatever you like — the name is not significant.
• Decide what you want to call this archive. I strongly recommend having it be composed of your email address, 2 dashes, and the current year. For example: mwolson@gnu.org--2005.
• Run tla to set up this archive.

tla make-archive <name> <location>

• To verify that you have done this right, do the following. You should see your archive's name and location in the list.

tla archives

Default archive

Most tla commands require you to specify the current archive with the -A switch. If you the do the following command, it will set the default archive so that you do not need to use that option.

tla my-default-archive <name-of-archive>

Adding a project to the archive

Step 1: Preparing the archive

This step tells tla to make the necessary metadata and directory structure for your new project in the archive you just made.

You should select a branch name for your project. This usually consists of something like name_of_project--type--NN. If you are making a custom version of another project, use your initials for "type", or some other similar nomenclature. NN can be either the name of the version of this project, or just "0" or "1.0" if you don't want to bother with it too much.

tla archive-setup <branch name>

For example, say your name is Jane A. Doe and you want to make a branch of Projects: Emacs Muse. You'd do something like the following.

tla archive-setup muse--jad--1.0

Step 2: Adding a source tree

This step adds Arch metadata to the directory structure where your source code is located.

Option 1: Branching off of an existing project

Terminology note

The word branch has several intertwined meanings for me. It can refer to the second (middle) part of a branch name. It can also mean your custom Arch-managed version of an existing project.

To make your own customized branch of Muse, follow these steps.

• Get my Muse stuff by using Arch. See Project Distribution, and follow the Arch instructions. A brief example is given.

tla register-archive http://www.mwolson.org/archives/2006
tla get -A mwolson@gnu.org--2006 muse--main--1.0 muse

• Tag my latest development version. This means that you will define my project as your starting point, and Arch will allow for changes back and forth between our archives. Do the following, substituting appropriately for "your@archive.com", "YYYY", "jad", and "1.0" so that it is the same name as what you used in Step 1.

tla tag mwolson@gnu.org--2006/muse--main--1.0 \
    your@archive.com--YYYY/muse--jad--1.0

At this point, you can begin hacking on your custom branch and adding changes.

If you don't like what I did in a certain patch, say "patch-31" for example, do something like the following instead of the previous example invocation.

tla tag mwolson@gnu.org--2006/muse--main--1.0--patch-30 \
    your@archive.com--YYYY/muse--jad--1.0

This only gets up to patch-30 from the source code.

Option 2: Starting a new project

Say you have a directory for a project that you've already started. You will use a different method to get your project working with Arch. The directory that contains your project is called a source tree.

• Use the branch name that you selected in Step 1 to initialize the source tree. To do this, move into the directory that contains your source tree and do the following. Replace all of the "your@archive.com" and "myproject" stuff appropriately.

tla init-tree your@archive.com--YYYY/myproject--main--1.0

• Now that you've added Arch metadata to this directory, it's time to make Arch aware of which files and directories it should manage. If everything in your directory is to be considered a source code type of file, like documentation, scripts, and source code, then you need to do the following.

tla add name-of-source-directory
cd name-of-source-directory
tla add-id *.[ch]
cd ..

tla add-id name-of-doc-directory
cd name-of-doc-directory
tla add-id *.txt another_file yet_another_file
cd ..

...

In other words, you need to run tla add-id on every directory and file that is contained in your source tree. Skip the {arch} and .arch-ids directories — those are created automatically by Arch.

If your needs are more complicated, like having to include a binary file with your project (no idea why you would want to do that though), check out http://regexps.srparish.net/tutorial-tla/inventories.html#Project_Tree_Inventories.

• To make sure that you did not miss anything, run tla tree-lint in the top-level directory of your source tree. If you see files listed in the output of that command, Arch does not know what to do with them. It's best to add them before moving on to the next step.
• At this point, you're ready to begin the revision history of your project. To mark this state as the initial one, do the following in the top level of your source tree. The -s option tells Arch what the summary field of the first ChangeLog entry should look like.

tla import -s "Initial import"

Checking out other Arch projects

Getting software

To check out an archive, run the following command, substituting the branch name for {branch-name} and the destination directory for {dest-dir}.

tla get -A mwolson@gnu.org--2006 {branch-name} {dest-dir}

or, equivalently:

tla get mwolson@gnu.org--2006/{branch-name} {dest-dir}

This will check out a copy of the given project and put it in the {dest-dir} subdirectory of your current directory.

Keeping up to date

To keep up to date on the latest changes, navigate to the directory that you specified when checking out the project and do the following.

tla missing

tla update

The first command will show what changesets you are missing from me. The second command will download and merge those changes for you, preserving any local changes that you have made. I usually just skip the first command when I update from the Arch repositories of other projects.

What happens next

By now, you have successfully set up an Arch project of some sort.

If you would like to learn how to put Arch to use on a daily basis and integrate it with Emacs, Part 2 of the tutorial is Developing With Arch.

[ This is Part 1: Getting Started With Arch ]
[ Next is Part 2: Developing With Arch ]

Arch Tutorial

---

[ Front | Projects | Index | Source ] Last updated Aug. 12, 2007