Prime Mover / Documentation / Using Prime Mover

Using Prime Mover

Page Contents

1. Introduction

This document describes how to use the Prime Mover command line tool to invoke pmfiles, build things, and how to manage the intermediate cache.

It does not tell you how to write a pmfile; see The core pmfile language for that. It also does not tell you how to install Prime Mover in a new package; see Installing Prime Mover into a new project for instructions on how to do that.

2. Running Prime Mover

Prime Mover is deployed as a single, small shell script. On most systems, run it by doing:

./pm [options] [rules]

The minimum possible command is simply:


This will load the default pmfile, which is called pmfile, and attempt to build the rule called default from that pmfile.

pm must be able to write to the current working directory.

3. Options

If pm is run with the -h or --help options, it will produce the following summary:

pm: Prime Mover version X.X © 2006 David Given
Syntax: pm [<options...>] [<targets>]
   -h    --help        Displays this message.
         --license     List Prime Mover's redistribution license.
   -cX   --cachedir X  Sets the object file cache to directory X.
   -p    --purge       Purges the cache before execution.
                       WARNING: will remove *everything* in the cache dir!
   -fX   --file X      Reads in the pmfile X. May be specified multiple times.
   -DX=Y --define X=Y  Defines variable X to value Y (or true if Y omitted)
   -n    --no-execute  Don't actually execute anything
   -v    --verbose     Be more verbose
   -q    --quiet       Be more quiet

If no pmfiles are explicitly specified, 'pmfile' is read.
If no targets are explicitly specified, 'default' is built.
Options and targets may be specified in any order.

Option parameters are accepted in any of the formats -lFNORD, -l FNORD, and --long-option FNORD. Options are read in and processed in the order in which they are specified.

The options are described in more detail here.

-h or --helpProduces the above help summary.
--licenseEmits Prime Mover's redistribution license to the terminal and exits immediately. Prime Mover may be distributed under the terms of the MIT public license, which is one of the 'classic' licenses approved by the Open Source Initiative; see the OSI's license page for more information.
-c dir or --cachedir dirChanges the location of Prime Mover's intermediate cache to dir. This should point at the directory where Prime Mover should place all of its working files, including the results of all builds. It is not intended to be human readable, and defaults to .pm-cache; it will be automatically created if necessary.
-p or --purgeCauses the intermediate cache directory to be removed before proceeding; this will cause it to be automatically recreated. This will remove all files in the directory, including ones that Prime Mover does not know about.
-f filename or --file filenameReads in the pmfile filename. This option may be supplied several times; each pmfile will be read in in order.

Each pmfile will be executed immediately as a Lua script, but Prime Mover will only start the rule engine once all the pmfiles have been loaded. This means that any Lua extension code will be executed even if a subsequent error cause Prime Mover to fail its startup.

-D name=value or --define name=valueDefines a global property name, with value value.

value must be a valid constant; if a string, it must be quoted. (The quotation marks may need to be escaped to prevent the shell from touching them.) value may be omitted, in which case it defaults to true.

-n or --no-executeCause Prime Mover to go through the motions of doing a build, but without actually doing anything. This can be occasionally useful for debugging.

Any Lua extension code will still be executed.

The commands generated by --no-execute may differ slightly from those done by a normal build if there are any dynamically generated source files being used.

-v or --verboseCauses Prime Mover to produce quite a lot of debug tracing describing exactly what it is doing.
-q or --quietCauses Prime Mover to suppress some of its normal status messages, including the echoing of the command being executed.

(It is possible, but not very useful, to specify --verbose and --quiet together.)

4. Using Prime Mover as a Lua interpreter

It is possible to use the pm executable as a stand-alone Lua interpreter, without invoking the rules engine. This can be particularly useful for writing helper scripts for using during a build; having the full power of the Lua language available can simplify matters considerably, as well as helping avoid dependencies on third party tools.

To do this, invoke your Lua program as if it were a pmfile:

./pm -f script.lua

The script must explicitly terminate using os.exit(). If it does not, then the rules engine will start, which can cause extremely odd behaviour. For example:

-- This is an example Lua script.
print "Enter your name:"
name =
for i = 1, string.len(name) do
  print(string.sub(name, 1, i))

The arguments used to invoke pm are available in the arg table; however, all the arguments are available there, even the ones irrelevant to the script.

The version of Lua used is 5.0, patched to use integers only. A slightly modified version of Luiz Henrique de Figueiredo's lposix library is available in the posix table; explicitly requiring it is not necessary.

5. Troubleshooting

5.1. The bootstrap process

You do not need to know anything from this section to use Prime Mover. This is provided for technical background and to assist if things go wrong.

The pm executable is actually a shell script containing two packed files. One of these files is the code that actually makes up Prime Mover, which is written in Lua; the other file is C source code for a patched version of the Lua interpreter.

In order to run Prime Mover, the Lua interpreter must be compiled. The first time pm is run for a particular architecture, it will unpack the C file and compile it using gcc, if available, or cc if not. The executable is then cached in the file .pm-architecture, where architecture identifies the machine architecture (so multiple architectures can use pm from the same source directory). Subsequent invocations of pm will used this cached version.

The architecture is determined by trying these three commands, in order, until one of them succeeds:

uname -m

If none of these succeeds, the pm will emit a warning and continue, using unknown as the architecture name.

To determine what compiler is available, pm will attempt to look up gcc on the path. If it is available, then the Lua interpreter will be compiled with the following interpreter:

gcc -O -s $in.c -o $out

If it is not available, this will be used instead:

cc $in.c -o $out

($in is replaced with the name of the temporary file containing the Lua interpreter source code, and $out is replaced with the name of the cached executable.

If neither C compiler is available, or the available C compiler does not use the standard syntax, then pm will fail in an obscure manner. This is a known issue.