Prime Mover / Frequently Asked Questions

Frequently Asked Questions

Page Contents

1. General

1.1. I don't want my users to have to install Prime Mover to be able to build my application.

You don't have to.

Prime Mover is designed to be simply dropped into your source code package. It is distributed as a self-bootstrapping shell script that's about 80kB long --- roughly on a par with a medium complexity configure script. Your users don't have to install anything; they simply run the script.

1.2. But Prime Mover's written in Lua. My users will have to install a Lua interpreter to run Prime Mover.


When the Prime Mover shell script is first run, it unpacks a copy of the Lua source code into a temporary file and compiles it. The resulting executable is cached and used to run Prime Mover itself.

1.3. But isn't this very inefficient?

Certainly, but the Lua source code is so small (about 50kB, compressed) that the convenience factor far outweighs the cost. Because each application that uses Prime Mover comes with Prime Mover, we don't have to worry about installion, version mismatches, application-specific patches, etc. It really is a case of just run it and go.

1.4. What platforms does Prime Mover run?

Theoretically, Prime Mover should run on any reasonably Unix-like Posix system with gcc or a C compiler called cc. In practice, it has been successfully tested on:

It is known not run on:

If anyone has any reports of working-ness or non-working-ness, please let me know.

2. Using pmfiles

2.1. When I invoke my pmfile, I get this really wierd error message!

Because all pmfiles are valid Lua programs, if you get something wrong that confuses the Lua compiler, you'll get a Lua error message. It's a stack trace. The bit you want is usually at the top.

Making the error messages friendlier is on my to-do list. If you're really stuck, ask on the mailing list.

2.2. When I invoke my pmfile, it hangs!

You've got a recursive loop.

pm dependency graphs may be cyclic; it's possible for A to depend on B which depends on A. This may be useful if the two As are built with different options that causes the second A not to depend on B.

If you get this wrong, pm will just keep happily recursing into the cycle until it runs out of memory, without being able to tell whether you're doing it on purpose or not.

(I'm still deciding with recursive dependency graphs are a good idea or not.)

2.3. When I invoke my pmfile, it only builds some of a rule's children!

You've probably got a typo.

This is a side effect of Prime Mover being written in Lua, I'm afraid. Prime Mover rules are expressed as Lua arrays; Lua defines an array as a list of items terminated in a nil. Unfortunately, unrecognised global symbols evaluate to nil too. So this:

default = group {

...will assume that program2 is the last item in the rule, because proogram3 (which is misspelt) evaluated to nil.

I have a potential workaround for this, that should allow pm to warn you in most cases; it's still on my to-do list.

3. The intermediate cache

3.1. pm claims to have built something, but I don't see any .o files!

When pm builds things, it puts all intermediate files into a private cache directory. The contents of this directory are not really intended for public consumption, and so you have to explicitly tell pm to export files from it. This is done with the install property, which may be added to any rule. See the main documentation for a full discussion.

The intermediate cache is, by default, in ./.pm-cache. It may be deleted at any time with no ill-effects (apart from making the next build take longer).

3.2. What's the equivalent of make clean?

Firstly, if your dependency graph is correct, you should never need to do this --- pm should, automatically, always rebuild all files that need rebuilding whenever you change something. If you can prove that it doesn't, and that you are sure you gave it all the necessary information in the pmfile, then that's a bug; please let me know so I can fix it.

But to answer your question, if you invoke pm with the --purge (or -p) option, it'll delete the intermediate cache and rebuild everything from scratch.

3.3. My cache directory is 47GB and I've just had to buy another hard disk! What's going on?

pm always keeps all intermediate files, even if you no longer need them. For example, if you do a build with debugging on, and then do a build with optimisation on, you'll get two complete sets of object files. This isn't a bug, it's a feature.

You may want to do a -p from time to time to keep the size of the intermediate cache under control.