This document describes how to install Prime Mover into a new project.
This is intended to be used by application authors who wish to adopt Prime Mover as their build tool. 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 use Prime Mover itself; Using Prime Mover for instructions on how to do that.
A project using Prime Mover must have at least two files, and probably a few more. These consist of:
The typical layout for a project using Prime Mover is to have the pm executable in the project root directory, along with the default pmfile, and to have the plugins in a subdirectory somewhere. For example:
helloworld-0.1/README helloworld-0.1/pm helloworld-0.1/pmfile helloworld-0.1/src/hello.c helloworld-0.1/lib/c.pm
This layout allows the application to be built by simply changing into the project's directory and doing:
./pm
Practically every project is going to need c.pm; it contains the additional rules necessary to allow Prime Mover to build C and C++ files. See The C and C++ plugin for detailed information.
The Prime Mover distribution contains three different versions of the main executable, which are in the bin directory in the Prime Mover distribution. These are all functionally identical, but have been encoded differently.
pm_8bit | This version is the smallest, and contains gzip compressed data. As a result, it is not 8-bit clean. Can not be updated via patch files. |
pm_uncompressed | This version is the largest, and contains plain text. Can be updated via patch files. |
pm_7bit | This is version is a compromise between the above two versions; it contains data that has been gzip compressed and then uuencoded. It is 8-bit clean. Can be updated via patch files, but may produce extremely large patches. |
Which version you use depends on your exact situation. In particular, if your package is to be distributed as a tar.gz or tar.bz2 file, then using pm_uncompressed may actually reduce the size of your distribution file; the extra overhead in pm_7bit or pm_8bit causes it to compress less well.
The exact figures:
Version | Uncompressed | Compressed with gzip -9 | Compressed with bzip -9 |
---|---|---|---|
pm_uncompressed | 178kB | 63kB | 58kB |
pm_8bit | 63kB | 63kB | 64kB |
pm_7bit | 87kB | 66kB | 66kB |
To use a particular version, simply copy the file and rename it to pm.
cp pm_uncompressed ~/projects/helloworld-0.1/pm
Plugins are stored in the Prime Mover distribution's lib directory; see the documentation index for a list of the supported plugins. Most projects will want c.pm, as that will allow them to compile C and C++ programs.
To use a plugin, simply copy it into your project somewhere. You may, if you wish, put it in the root directory along with pm and your pmfile, but this is not recommended as it can clutter things.
cp lib/c.pm ~/projects/helloworld-0.1/lib/c.pm
The final stage is to write your application's pmfile. See The core pmfile language for a full description of this, but the key points are:
For example:
include "lib/c.pm" default = cprogram { cfile "src/hello.c", install = pm.install("hello") }
This is a minimal but complete example that will build our helloworld project.
Here is some random advice on writing pmfiles:
All content © 2000-2007 David Given unless otherwise stated.