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.
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:
./pm
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.
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>]
Options:
-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 --help | Produces the above help summary. |
| --license | Emits 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 dir | Changes 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 --purge | Causes 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 filename | Reads in the pmfile filename. This option may be supplied
several times; each pmfile will be read in in order.
|
| -D name=value or --define name=value | Defines 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-execute | Cause Prime Mover to go through the motions of doing a build, but
without actually doing anything. This can be occasionally useful for
debugging.
|
| -v or --verbose | Causes Prime Mover to produce quite a lot of debug tracing describing exactly what it is doing. |
| -q or --quiet | Causes 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.) |
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 = io.read() for i = 1, string.len(name) do print(string.sub(name, 1, i)) end os.exit(0)
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.
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:
arch machine 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.
All content © 2000-2007 David Given unless otherwise stated.