Quick start: so you’ve been asked to work on a project using muddle¶
This is intended as a short introduction to the absolute minimum you’re likely to need.
Step 1: getting muddle¶
The very first thing you need is muddle itself.
Getting muddle needs git. If you don’t have git on your system, and you’re on a Debian based system (Debian, Ubuntu, Linux Mint, etc.), then you can do:
$ sudo apt-get install git gitk
(the gitk
program is an invaluable UI for looking at the state of git
checkouts - it’s always worth checking it out as well as git itself).
Then decide where to put muddle. I have a sw
directory for useful software
checkouts, so I would do:
$ cd sw
$ git clone https://code.google.com/p/muddle/
which creates me a directory ~/sw/muddle
.
Note
Sometimes (luckily not often) the Google code repositories give errors. If you can’t clone muddle from code.google.com, try using the mirror on github, which should normally be up-to-date:
git clone https://github.com/tibs/muddle.mirror.git muddle
To use muddle, you can then either:
just type
~/sw/muddle/muddle
- this is the simplest thing to do, but the longest to type.add an alias to your
.bashrc
or equivalent:alias muddle="${HOME}/sw/muddle/muddle"
add
~/sw/muddle
to your PATH:export PATH=${PATH}:${HOME}/sw/muddle
add a link - for instance, if you have
~/bin
on your path, do:cd ~/bin ln -s ~/sw/muddle/muddle .
Personally, I use the second option, but all are sensible.
You should now be able to do:
$ muddle help
and get meaningful output. To find help on a particular muddle command, you can, for instance, do:
$ muddle help checkout
Note
Some people also like to keep muddle in /opt
- for instance,
as /opt/muddle
.
Note
Muddle is actively developed, and we normally assume that you will
keep it up-to-date with the current state of that development. Unless your
project says to do otherwise, it’s normally worth doing a git pull
once a week or so – for instance:
$ pushd ~/sw/muddle
$ git pull
Step 2: getting your project’s build description¶
You should have been given a muddle init
line to use to bootstrap your
project.
For simplicity in explaining things, I’m going to assume that you keep your
current projects in a directory called ~/work
, and this new project is
project99
.
Muddle wants each project to live in its own directory, so we would do:
$ mkdir ~/work/project99
$ cd ~/work/project99
and then type the muddle init
line, something of the form:
$ muddle init git+https://code.google.com/p/raw-cctv-replay builds/01.py
The first argument to git init
says where the project build description is
kept (for the RAW project, that’s on Google code), and the second argument
says where the build description can be found within the src
directory.
Note
Please use the muddle init
command for your own project, unless
you want to work on RAW, which is a rather large project.
Note
Some builds check for particular software on the system, and use
sudo apt-get
to install things if necessary. The build documentation
should always tell you about this.
After muddle init
has succeeded, you should have two directories in your
project directory:
.muddle
which contains the “state” of the muddle build, andsrc
, which will typically containbuilds/01.py
(or whatever else was named by that final argument tomuddle init
.
Note
If the muddle init
command goes wrong, then you will need to
delete both directories before trying it again.
The build description is a Python file (for some projects, more than one)
which describes the build to muddle. It is traditionally kept in the
src/builds
directory, and for historical reasons the main build
description file is called 01.py
.
Step 3: building the project the first time¶
The simplest way of building the project for the first time is just to use the “muddle” command directly - it will realise that it needs to checkout all the source code and build it from scratch. So:
$ cd ~/sw/project99
$ muddle
Alternatively, some people prefer to separate the checkout and build phases, so that all the internet access is done in one go. This can be done with:
$ cd ~/sw/project99
$ muddle checkout _all
$ muddle
After this has finished, you should have a much fuller src
directory, and
also obj
, install
and deploy
directories. If you’re building
software to put on an embedded system, that will generally be in one or more
of the deploy
directories, and your project documentation should tell you
what to do next.
The muddle directories and its phases¶
Muddle keeps the build tree in several different directories.
.muddle
is where information about the build tree is kept, for instance which packages have been built.src
is where the source code is kept, as checked out withmuddle checkout _all
.obj
is where muddle builds things. A well-behaved muddle build always builds “out of tree” inobj
, so that building things doesn’t change anything in thesrc
directory.install
is where the muddle build puts its results, those programs, libraries and so on that are going to be used to make a deployment.deploy
is where deployments are assembled. These are the parts of the final system that will be put onto the target hardware.
This means that muddle has three phases to its work:
- Checkout, which populates the
src
directories. - Build, which builds in
obj
and puts the results intoinstall
. Building will also check things out intosrc
if necessary. - Deploy, which puts together things from
install
and stores the results indeploy
. Deployment will also build things if necessary.
Warning
Remember that building (phase 2) does not do deployment (phase 3). It is up to the user to decide when the packages have built correctly and are in a suitable state for deployment.
Step 4: getting the latest version of code and rebuilding¶
Eventually, some of the software in your project will be updated, and you will need to retrieve the new versions of the source code, and rebuild it.
This is typically done from the “top level” directory - i.e., the directory
containing the src
and .muddle
directories. So, with our project:
$ cd ~/work/project99
$ muddle pull _all
Hopefully that will succeed without any problems. If there are any problems, they will be summarised at the end of the command output.
Once the source code is updated, you can then rebuild all packages by doing:
$ muddle distrebuild _all
or just rebuild everything affected by the updated sources:
$ muddle distrebuild _just_pulled
If you also want to redeploy - that is, rebuild the deploy
directories -
then you can:
Redeploy all deployments:
$ muddle redeploy _all
Redeploy the default deployments, the same as the very first
muddle
command:$ muddle redeploy _default_deployments
Redeploy something specific:
$ muddle redeploy <some-specific-deployment>
Step 5: editing code and rebuilding¶
If you need to edit code, then it may be worth your getting a deeper knowledge of how muddle works, and a good starting point is probably the “Muddle and its directories” chapter.
There is more than one way to use muddle - this very short introduction is only that.
Throughout this section, we assume that you are in a checkout source directory - for instance:
$ cd ~/work/project99
$ cd src/some_program-v1.9
Edit and rebuild¶
The normal edit/rebuild cycle is fairly simple - edit:
$ gvim sourcecode.c
and then rebuild:
$ muddle rebuild
Muddle knows what package uses this source checkout (if the checkout is
some_program-v1.9
then the package is probably some_program
), and so
it will rebuild the package that uses that source code.
Note
Inside src/
, just typing muddle
does a build, not a
rebuild. Muddle cannot tell that you’ve changed the source code, so it
still thinks that the last build of the code is valid, so you need to
tell it explicitly to do a rebuild.
Doing a rebuild
also tells muddle that any packages that depend on this
one will also need rebuilding - this is important in the next section.
If you also need to reconfigure the package, then you need to “distclean” it first. So:
$ muddle distclean
$ muddle rebuild
There’s a convenient command that does those together:
$ muddle distrebuild
Build anything else that needs it¶
Once you’ve finished the “edit, compile” loop, and are happy with the state of the package, there may be other things needing building.
You could just do muddle rebuild _all
, but that would rebuild every
single package. However, muddle knows which packages depend on the package
you’ve just been working on, and so:
$ muddle build _all
should just build those packages that need it.
Commit your changes¶
Once the code for your checkout is correct, you can commit it using the
appropairte version control commands (there is a muddle commit
, but I tend
just to use the VCS directly) - for instance:
$ git add sourcecode.c
$ git commit
and then push it back to the far repository:
$ muddle push
You could, of course, also use the approriate version control command
directly, but muddle push
keeps track of which remote repository the build
description says should be used, which may or may not be the same as the
repository that was originally pulled from.
Consider redeploying¶
Building does not redeploy. This is easy to forget, but deployment is deployment of a system for use on the target hardware, and it is not normally appropriate to do it every time some component of the system is rebuilt (not least because the overall system may not work again until more than one checkout/package is altered).
So it is up to the user to decide when to redeploy, at which time:
$ muddle redeploy
will redeploy the deployment containing the package that uses this source checkout (i.e., what should be the minimum necessary redeployment), whilst:
$ muddle redeploy _all
will redeploy everything, and:
$ muddle redeploy _default_deployments
will redeploy, well, the default deployments, just as the very first
muddle
command would have done.
Step 6: finding out more¶
If you want to progress to the next level of use of muddle, then reading the chapter “Muddle and its directories” is a useful next step. There are various “frequently asked questions” answered in the “Jottings” section as well.