Installing Prime Mover into a new project

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 Prime Mover executable itself;
• any optional plugins used by Prime Mover.
• the project's pmfile;

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.

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.

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:

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

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:

• Include your plugins, using the right filename, in the right order.
• Define a default rule.
• Remember that unless you explicitly tell Prime Mover to install things using the install property, you will not see the results of your build.

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.

6. Tips

Here is some random advice on writing pmfiles:

• If you have a big application, try using include to split your pmfile up into little files spread throughout your application. This way the rules describing how to build each directory are in the directory itself.
• Paths are always relative to the current directory when pm was run.