Prime Mover / Documentation / The C and C++ plugin

The C and C++ plugin

Page Contents

1. Introduction

The c.pm plugin allows Prime Mover to build C and C++ files into standard applications and simple static libraries. It supports automatic dependency calculation on C-like files, and is reasonably configurable.

Shared libraries are, unfortunately, not supported. This is because the process for making shared libraries is extremely unportable; there are tools such as GNU libtool available, but they tend to be very large and complex. The libtool script is bigger than most Prime Mover executables.

There is a strong possibility that at some point in the future Prime Mover will support libtool directly, or else have its own equivalent functionality, but for now, c.pm does not know how to make shared libraries.

2. Global settings

By default, c.pm is set up to use the gcc tool chain. The commands gcc, g++, ar and ranlib are used. These can all be modified by changing the appropriate properties.

2.1. For building C

CC

The command used to compile a single C source file into an object file. Defaults to:

%CCOMPILER% %CBUILDFLAGS% %CDYNINCLUDES:cincludes% %CINCLUDES:cincludes% %CDEFINES:cdefines% %CEXTRAFLAGS% -c -o %out% %in%

This may be overridden completely, or customised by modifying the variables that it refers to.

CPROGRAM

The command used to compile object files into a runnable executable. Defaults to:

%CCOMPILER% %CBUILDFLAGS% %CLINKFLAGS% %CEXTRAFLAGS% -o %out% %in% %CLIBRARIES:clibraries%
CCOMPILER

The name of the C compiler executable. Defaults to:

gcc

2.2. For building C++

CXXThe command used to compile a single C++ source file into an object file. Defaults to:
%CXXCOMPILER% %CBUILDFLAGS% %CDYNINCLUDES:cincludes% %CINCLUDES:cincludes% %CDEFINES:cdefines% %CEXTRAFLAGS% -c -o %out% %in%

This may be overridden completely, or customised by modifying the variables that it refers to.

CXXPROGRAMThe command used to compile object files into a runnable executable. Defaults to:
%CXXCOMPILER% %CBUILDFLAGS% %CLINKFLAGS% %CEXTRAFLAGS% -o %out% %in% %CLIBRARIES:clibraries%
CXXCOMPILERThe name of the C compiler executable. Defaults to:
g++

2.3. For both

CLIBRARY

The command used to build C or C++ static libraries. Defaults to:

rm -f %out% && ar cr %out% %in% && ranlib %out%
CBUILDFLAGS

A list of strings containing flags that change the way the compiler behaves. This is typically used to change debugging and optimisation settings. Defaults to:

{"-g"}

(As this is a list, flags may be appended by using the {PARENT, "..."} syntax.)

CDYNINCLUDES

This is replaced at run time with a list of paths determined by the dynamicheaders property of the simple_with_clike_dependencies rule. It is not overridable and has no default.

CINCLUDES

A list of paths where the compiler should look for include files. Defaults to EMPTY.

CDEFINES

A set of strings of the format KEY or KEY=VALUE that specify preprocessor constants that should be defined by the compiler. Defaults to EMPTY.

CEXTRAFLAGS

A list of any additional flags that should be passed to the compiler. Defaults to EMPTY.

3. String modifiers

A number of custom string modifiers are defined by the C plugin for massaging lists. These may be overridden as necessary, but only on a global basis.

3.1. cincludes

Used to convert a list of paths into a set of arguments suitable for passing to the compiler. Defaults to prefixing -I to each item.

3.2. cdefines

Used to convert a list of KEY=VALUE tuples into a set of arguments suitable for passing to the compiler. Defaults to prefixing -D to each item.

3.3. clibraries

Used to convert a list of library names into a set of arguments suitable for passing to the compiler.

For each item, if the item ends in .a, it is left untouched; otherwise -l is prefixed.

4. Rules

4.1. For building C

4.1.1. cfile

Compiles a C source file into an object file.

Superclass

simple_with_clike_dependencies

Inputs

Exactly one C source file.

Outputs

Exactly one object file.

Recognised properties

CCThe command used to compile the source file.

4.1.2. cprogram

Compiles multiple C object files into a single executable program.

It is possible to mix object files built with cfile and cxxfile, but this rule will assume that all the source files were in C, and so will not include the C++ run time libraries.

Superclass

simple

Inputs

One or more object files.

Outputs

Exactly one executable.

Recognised properties

CPROGRAMThe command used to link the application.

4.2. For building C++

4.2.1. cxxfile

Compiles a C++ source file into an object file.

Superclass

simple_with_clike_dependencies

Inputs

Exactly one C++ source file.

Outputs

Exactly one object file.

Recognised properties

CXXThe command used to compile the source file.

4.2.2. cxxprogram

Compiles multiple C++ object files into a single executable program.

It is possible to mix object files built with cfile and cxxfile.

Superclass

simple

Inputs

One or more object files.

Outputs

Exactly one executable.

Recognised properties

CXXPROGRAMThe command used to link the application.

4.3. General

4.3.1. clibrary

Creates a static library from multiple object files.

This can be used with any combination of object files created with cfile or cxxfile.

Superclass

simple

Inputs

One or more object files.

Outputs

Exactly one static library.

Recognised properties

CLIBRARYThe command used to link the library.

4.3.2. simple_with_clike_dependencies

Performs like simple, but takes into account any included files used by its argument. This rule is not intended to be used directly, and is more appropriate for use as an abstract base class.

The dependency analysis is rather simple. The source files are studied recursively for #include lines. References to missing include files are ignored. If any of the included files is newer than the object file, then the source file will be rebuilt; however, no attempt will be made to build the included files themselves. (See dynamicheaders below.)

Superclass

simple

Inputs

Exactly one source file destined to be run through the C preprocessor.

Outputs

As for simple.

Recognised properties

dynamicheaders

This property should contain a list of rule instantiations, which are intended to be used for building any dynamic header files that the source file will need to refer to. This rules will be considered as part of the dependency calculations, and they will be rebuilt if necessary, but their result will be ignored by Prime Mover. (It is assumed that the source file is going to refer to the result using a mechanism that Prime Mover does not know about.)

If this property is used, then the CDYNINCLUDES property will be automatically set up to contain a list of the directories containing the results of the rules in dynamicheaders. This allows the C preprocessor to find any generated files.

The main use of this property is to tell pm how to build dynamically generated header files. For example:

include "lib/c.pm"

make_dynamic_h = simple {
  command = {
    "echo '#define DYNAMIC' > %out%"
  },
  outputs = {"%U%/dynamic.h"},
}

default = cprogram {
  cfile "test.c",
  cfile {
    "includes-dynamic.c",
    dynamicheaders = make_dynamic_h,
  }
}