muddle and its directories - part 2 - example build

Contents

• A simple example build
• The .muddle directory
  • The Description file
  • The RootRepository file
  • The tags/ directory
  • Other contents
• The src/builds directory

A simple example build

The muddle repository has a variety of example build descriptions, of varying complexity.

Perhaps inevitably, not all of the examples are maintained as well as they should be. If you do find problems with any of them, please raise an issue about it on the muddle issues page.

We shall use the "cpio" example.

We start with a new, empty directory:

$ mkdir example
$ cd example

and then use the muddle init command:

$ m3 init svn+http://muddle.googlecode.com/svn/trunk/muddle/examples/cpio builds/01.py
> Make directory /home/tibs/sw/m3/example/.muddle
Initialised build tree in /home/tibs/sw/m3/example
Repository: svn+http://muddle.googlecode.com/svn/trunk/muddle/examples/cpio
Build description: builds/01.py


Checking out build description ..

> Make directory /home/tibs/sw/m3/example/src
> svn checkout  http://muddle.googlecode.com/svn/trunk/muddle/examples/cpio/builds builds
A    builds/01.py
Checked out revision 458.
> Make directory /home/tibs/sw/m3/example/.muddle/tags/checkout/builds
Done.

This leaves us with two new directories:

$ ls -AF
.muddle/  src/

Or, in more detail (with the .svn/ directory in src/builds/ shown as a "stub"):

.
|-- .muddle/
|   |-- Description
|   |-- RootRepository
|   `-- tags/
|       `-- checkout/
|           `-- builds/
|               `-- checked_out
`-- src/
    `-- builds/
        |-- 01.py
        |-- 01.pyc
        `-- .svn/

Whilst the name and content of the src/builds directory might differ, this is the normal state of a muddle build tree after the init command.

The .muddle directory

The .muddle/ directory is, in many ways, the heart of the muddle build tree.

In the first place, it identifies a directory as the top-level of a muddle build. Indeed, the muddle command line tool looks in the current directory, and then upwards through the filesystem, to find a .muddle/ directory. If it cannot find one, then it decides that it is not in a muddle build tree, and behaves accordingly (depending on what action it was asked to do).

The .muddle/ directory always contains at least two files and one directory:

The Description file

$ cat .muddle/Description
builds/01.py

which should be recognisable from the init command. It tells muddle where its build description was checked out (in the src/ directory, since that is where checkouts go).

You should not normally need to edit this file, but if you do, the next time you run muddle, it will believe that the build description is in the new location.

The RootRepository file

$ cat .muddle/RootRepository
svn+http://muddle.googlecode.com/svn/trunk/muddle/examples/cpio

Again, this should be recognisable from the init command. This specifies the default repository, which muddle will assume is being used for checkouts unless the build description says otherwise.

You should not normally need to edit this file either, but again muddle will believe its contents after a change.

The tags/ directory

The tags/ directory contains the current state of the build - it is essentially a database of "labels satisfied", stored in the filesystem.

In the current state:

.muddle/tags
`-- checkout/
    `-- builds/
        `-- checked_out

we can see that the label checkout:builds/checked_out has been "built" (or has had its target satisfied). This corresponds to having checked out the builds checkout, which is indeed what has been done. We shall see later that it is possible to change the build state by deleting or "touch"ing tag files.

The checked_out file created by muddle does have content - it contains a timestamp:

$ cat .muddle/tags/checkout/builds/checked_out
2010-09-28 11:14:34

but this content is never actually used for anything, and if you do add a tag file, it is quite sufficient to use touch to create an empty file.

If we ask muddle what checkouts it knows about:

$ m3 query checkouts
builds
cpio_co

we see two checkouts. The absence of any tag files for the "cpio_co" checkout tells us that it hasn't been checked out yet.

Other contents

There may also be other things in the .muddle/ directory, notably an instructions/ directory (used for deployment instructions), and an am_subdomain file (described when we talk about domains), but we shall ignore these for now.

The src/builds directory

The other directory present is the src/ directory, which, so far, contains a single subdirectory for the build description.

`src/
 `-- builds/
     |-- 01.py
     |-- 01.pyc
     `-- .svn/