Usage description

The fpmkunit unit is meant to be used to create a program that handles compilation, archiving and installation of a set of pascal sources, collected in so-called packages. The unit can handle multiple packages, and will manage dependencies of packages automatically. Customarily this program is called fpmake. When using fppkg or in the FPC sources, use of this name is mandatory.

The unit supports the following operations:

• Compilation of units, programs or libraries.
• installation of the compiled results to standard locations.
• Creation of a .zip file with the sources of the files.
• Generation of documentation with fpdoc.
• Execution of custom commands when compiling, installing or packaging

The unit consists of a series of classes which are designed to work together. An instance of these classes is created for you, they are ready to be used.

Installer

This function returns the main TCustomInstaller instance. This class is the entry point for all functionality: it manages settings and package definitions and processes command-line options

Defaults

The main TCustomDefaults Instance. Here you can set compiler options such as CPU, OS, all kinds of search paths, executable paths and directories

Installer.BuildEngine

This is the engine that does all the work.

For the majority of cases, it suffices to define some packages using Installer.Packages, and to call Installer.Run. The Run method will examine the RunMode property to determine what action is expected, and then it proceeds to execute the action using the BuildEngine. The latter does all the work, and contains all the logic to launch commands in the correct order to execute the specified action.

To demonstrate this, a simple program can be made:

program fpmake1;

uses fpmkunit;

var
  P: TPackage;
  
begin
  With Installer do
    begin
    P:=Packages.AddPackage('mypackage');
    P.Dependencies.Clear;
    P.Targets.AddUnit('src/unit1.pp');
    Run;
    end;
end.

The TCustomInstaller class maintains a collection of Packages. At least 1 package must be defined. Every package has a list of files that must be compiled, and possibly a list of files that needs to be installed together with installed programs.

Every file that needs to be compiled, is a TTarget, and all targets are in the Targets property of the TPackage class. Installer will compile the targets in the order that they are specified, unless dependencies have been set up (see also Dependencies), in which case the order will be changed to compile dependencies of a target first, for any given target.

After compiling the fpmake1.pp program, it can be used to compile the unit1.pp when run with the compile command;

>  ./fpmake1 compile
Start compiling package mypackage for target x86_64-linux.
       Compiling src/unit1.pp
[100%] Compiled package mypackage

To pass extra options to the compiler, we can use the Defaults variable, which is valid as soon as the installer is created:

program fpmake2;

uses fpmkunit;

var
  P: TPackage;
  
begin
  With Installer do
    begin
    Defaults.Options.Add('-O2');
    P:=Packages.AddPackage('mypackage');
    P.Dependencies.Clear;
    P.Targets.AddUnit('src/unit1.pp');
    Run;
    end;
end;    

This program can be compiled, and when run with the -v option, you can see that the compiler is called with the extra option:

./fpmake2 compile -v
Start compiling package mypackage for target x86_64-linux.
  Compiling target unit1
    Executing command "/home/michael/bin/fpc  \
                       -Tlinux -Px86_64 \
                       -FUunits/x86_64-linux/ \
                       -O2 src/unit1.pp"
Generating "mypackage-x86_64-linux.fpm"
[100%] Compiled package mypackage

(the lines have been split for readability. On the console the log would be on one line)

To make life easier, if you are using the 3.3.1 or higher version of fpmkunit, you can use the AddPackageFromDir call.

uses fpmkunit;

begin
  With Installer do
    begin
    AddPackageFromDir('mypackage','src');
    Run;
    end;
end.

> ./fpmake3 compile -v
Adding unit src/unit1.pp to targets of mypackage
Switching to buildunit compilation of package mypackage
Start compiling package mypackage for target x86_64-linux.
  Compiling target unit1
Compiling target BuildUnit_mypackage
Not using buildunit
  Executing command "/home/michael/bin/fpc \
                     -Tlinux -Px86_64 \
                     -FUunits/x86_64-linux/ \
                     -Fusrc \
                     units/x86_64-linux/BuildUnit_mypackage.pp"
Deleted file "units/x86_64-linux/BuildUnit_mypackage.ppu"
Deleted file "units/x86_64-linux/BuildUnit_mypackage.pp"
Generating "mypackage-x86_64-linux.fpm"
[100%] Compiled package mypackage

Note that the installer switched to using a build unit: the AddPackageFromDir command does not check dependencies of the units. Instead, it switches to using a build unit (a unit that simply uses all units to be compiled) and then compiles the buildunit: in that case, the compiler will compile all files in the correct order.

See also