muddle and its directories - part 1 - introduction

This is a look at how muddle works, specifically looking at the directory structure of a muddle build.

Since it is quite long, I am splitting it into a series of 7 posts, of varying lengths. The whole thing will also ultimately be integrated into the "proper" muddle documentation.

If you are just going to use muddle to check out and build an existing build tree, then this will probably be much too much information, although the short section An overview of the directory structure (at the end of this introductory post) may be useful.

If you are going to be developing new muddle builds, then this text should enable you to do so more effectively.

If you are going to be reading the muddle source code, or developing muddle itself, then it should explain much of the intent behind muddle's workings.

Contents

• Introduction
• Notation in this text
• An overview of the directory structure

Introduction

muddle is three or four different things, entwined:

• It is a command line tool, providing useful tools for managing build trees on Linux.
• It is a Python package, muddled
• It is a simple dependency tracking and analysis tool, with its state made evident via the file structure.
• It is a binding of the above to the common tasks required for managing, building and preparing deployments of Linux software from common sources to multiple architectures and platforms.

In a perfect world (perhaps the eventual "muddle 3") these would be better separated. In particular, it would be nice if it was obvious that muddle can be adapted for things other than Linux build trees.

The best short introduction to muddle is still that written by Richard Watts (its primary author), the README for the project, titled "Welcome to Muddle", which can be found online at:

http://muddle.googlecode.com/svn/trunk/muddle/docs/_build/html/README.html

I recommend it for further study.

This document is meant to be a longer and more discursive introduction to some of the basics of muddle, with a concentration on how the muddle build tree works as a directory tree, and with worked examples.

Notation in this text

• Directory names are consistently shown with a trailing /, as by ls -F. Since I'm talking about directories and files a lot, I think this makes it easier to tell which is which.

• The "tree" listings of directory structures are produced with the command tree, normally as:

  $ tree -aF -I .svn --noreport
  

  i.e., showing files and directories that start with a dot, suffixing directory names with /, not showing .svn/ directories, and not reporting on the number of files and directories. In a few places the "stub" of a .svn/ directory (that is, just its name) may be shown - this should be obvious from context.

• When referrring to the parts of a label (type:(domain)name{role}/tag) it is useful to keep the punctuation that indicates that part (so, type:, (domain), name (no punctuation!), {role} and /tag).

  Remember that, in the current scheme of things, only package: labels use {role}, and "normal" builds do not use (domain).

• In this document I use the command m3 instead of muddle.

  The simple reason for this is that I made the examples using the version of muddle I'm currently working on, the muddle3_labels ("labels all the way down") development branch, and I'm using m3 to distinguish it from the "normal" muddle.

  (For the purposes of these examples this should not matter, as the functionality is substantially the same, although the output of some of the commands may be slightly different.)

  However, it is also a useful reminder that the muddle command need not be called muddle. This is particularly important to remember when writing makefiles that call back to muddle - they should use $(shell $(MUDDLE) ...) rather than the tempting $(shell muddle ...), for that very reason.

An overview of the directory structure

Normal practice is to keep a muddle build in its own directory. This is not a requirement, but it helps keep it more obvious that it is a build.

The muddle directories are as follows:

.muddle/

contains information about the build state, and signifies that this is a muddle build.

src/

contains the build description and any other checkouts.

obj/

generated by muddle to hold the results of building packages.

install/

generated by muddle to hold the results of "installing" packages (this will be explained later on).

deploy/

generated by muddle to hold the results of "deploying" things in install/.

versions/

generated by muddle to hold the result of muddle stamp version.

domains/

present if there are sub-domains, muddle will create this directory if it is needed.

instructions/

present if there are instruction files for use in deployment. muddle will create this directory if it is needed.

am_subdomain

generated by muddle in subdomains. Ignore it.