Prime Mover / Documentation / Installing Prime Mover into a new project

Installing Prime Mover into a new project

Page Contents

1. Introduction

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.

2. Necessary files

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:


This layout allows the application to be built by simply changing into the project's directory and doing:


Practically every project is going to need; 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.

3. Installing the executable

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_8bitThis 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_uncompressedThis version is the largest, and contains plain text. Can be updated via patch files.
pm_7bitThis 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

4. Installing the plugins

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, 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/ ~/projects/helloworld-0.1/lib/

5. Writing the pmfile

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/"

default = cprogram {
  cfile "src/hello.c",

  install = pm.install("hello")

This is a minimal but complete example that will build our helloworld project.

6. Tips

Here is some random advice on writing pmfiles: