From Lazarus wiki
Revision as of 12:52, 17 February 2011 by Loesje (talk | contribs) (Added information about fppkg listsettings)


Fppkg is the Free Pascal package manager. With this tool you can build and install Free Pascal packages on your system. You can install packages from local sources or they can be downloaded from a central repository. The packages have to be made with FPMake.

Quick-start guide

Note: this section is only valid for fppkg from fpc version 2.5.1 or higher.

Setting up

When you run fppkg for the first time, it will create new configuration files with the default values. To check if these values are ok, run 'fppkg list' in a console window. You should see something like this:

Name                 Installed    Available   
a52                  2.5.1-1      -           
aspell               2.5.1-1      -           
bfd                  2.5.1-1      -           
lnet                 -            0.6.3-0  

A list with all packages which are installed and the packages which are available for download are showed. You can see which version of each package is available and/or installed.

If fppkg only shows available packages and not any installed packages, you have to adapt your fppkg configuration. Run 'fppkg listsettings' to see the current settings and the location of the configuration files. Locate the compiler configuration file and open it in a text-editor. Now change the 'GlobalPrefix' setting to the location where fpc is installed. For example: 'GlobalPrefix=/usr/lib/fpc' or 'c:\pp'. Save the file and run 'fppkg list' again.

If you have still problems please read the section about configuring fppkg.

Installing a package

Installing a package is as simple as 'fppkg install [packagename]'. This will download, compile and install the package. When no error appears, use 'fppkg list' to check if the package is correctly installed. By default the package is installed for the current user only, if you want to force a system-wide installation, use the '-g' parameter. Note however that in that case you need to have the proper rights.

Configuring the compiler

As a last step, the freepascal-compiler has to find the installed packages. By default the packages are installed in a user-specific location and this location is by default not searched by the compiler. To add it, add the following line to your fpc.cfg:

Linux: (/etc/fpc.cfg or ~/.fpc.cfg)


Windows: (fpc.cfg)


Now you can use the units from the installed packages in all your programs. If you place the line at the bottom of the fpc.cfg, you are sure that the compiler will prefer the (locally) installed packages above the globally installed onces. This way you can install newer versions of packages locally, without having to change the global setup.

Commandline arguments

Output of fppkg -h

Usage: .../fppkg [options] <action> [package]
  -c --config        Set compiler configuration to use
  -h --help          This help
  -v --verbose       Show more information
  -d --debug         Show debugging information
  -g --global        Force installation to global (system-wide) directory
  -f --force         Force installation also if the package is already installed
  -r --recovery      Recovery mode, use always internal fpmkunit
  update             Update packages list
  list               List available and installed packages
  build              Build package
  compile            Compile package
  install            Install package
  clean              Clean package
  archive            Create archive of package
  download           Download package
  convertmk          Convert Makefile.fpc to fpmake.pp

All the actions are described below.

The package parameter can mean the following:

  • Packagename:The package name as it appears on the used repository. All available package names are listed by 'fppkg list'.
  • Zipfile: The full name of a zip-file (including the .zip extension) which contains a package.
  • Current directory: When there is no package parameter, fppkg looks for a file called 'fpmake.pp' in the current directory, and if it is found, use the package defined by that file. In this case the compiled files are not placed elsewhere (See the 'BuildDir' setting) but within the 'units' directory in the current directory.



Update packages list


List available and installed packages


Build package


Install package


Download package


Convert Makefile.fpc to fpmake.pp


General configuration

On startup fppkg reads it's settings from fppkg.cfg. If it can not find it, it will try to create one with some default values. In this configuration file the location of the local repository is set. Normally this is in the user's home-directory. It is also possible to add custom options which are always passed when fpmake is called. This can be used by fpmake-addins. For all other options see the global configuration file.

Besides the global configuration file, there is also a file which is specific for a compiler version. You can add as much of these files as you want, using different compiler versions or compiler options. A common use is for cross-compiling. You can specify which configuration file to use on the fppkg command line with the '-c' option. The location of these configuration files is set in fppkg.cfg. when no configuration file is specified, the file called 'default' is used. (This can be set in fppkg.cfg)

Most important settings in these configuration files are the locations of where the packages have to be installed. Fppkg supports two different locations for installed packages. One 'global' location, which normally can be used by all users of the computer. And a 'local' location which in most cases is in a user's home-directory. These locations can be set with the 'localprefix' and 'globalprefix' settings. If you want that fppkg detects which packages are installed by fpc itself, the 'globalprefix' has to be set to match the prefix of your fpc-installation. It is common to use the location of the local repository (set in fppkg.cfg) as setting for the localprefix. For a better explanation of all options see the compiler configuration files.

The 'fppkg listsettings' command will show the values for all settings and the names of the used configuration files. From settings that allow macros the value as it is set by the user and the value when all macros are evaluated are both shown.

The global configuration file

The global configuration file contains general information for fppkg, like the repository to download from and where to place the temporary files. A typical global configuration file looks like this: (linux)


When fppkg is started it first tries to load fppkg.cfg from a user-specific location. If a user-specific version can not be found fppkg searches for a system-wide fppkg.cfg. See the table for the exact location of these files. If both files do not exist a configuration file is created. When the current user is a superuser, a system-wide configuration file is made, else a user-specific one. When creating the configuration file fppkg tries some reasonable defaults for all settings. When you set the location of the fpc-installation in the enviroment-option FPCDIR, fppkg will use this location in the generated configuration files.

When you want to know for sure which configuration files fppkg uses, add the '-d' parameter to fppkg. It will list which configuration files are used and all the used settings.

Location of configuration files on different OS'es
OS User-specific configuration file System-wide configuration file
Unix/Linux ~/.config/fppkg.cfg /etc/fppkg.cfg
Windows %localsettings%\FreePascal\fppkg\fppkg.cfg

The following settings are available:

The location where local repository information is stored. Supports macros.
The location where packages are build when a package is supplied. When the package in the current directory is used, this setting is ignored. Supports macros.
Place where packages downloaded from a remote repository are stored. Supports macros.
Place where the compiler-configuration files can be found. Supports macros.
The URL to a file which contains all mirrors for a remote repository.
Contains the repository which has to be used. Selecting 'auto' will result in a random repository selected from the mirror list.
The filename of the compiler-configuration file which has to be used by default.
The filename of the compiler-configuration file which has to be used by default for compiling the fpmake.pp files.
Select the download-mechanism. lnet is the default.
Specifies options which have to be added to each call to fpmake. Use this if you have fpmake-addons installed that need some specific settings. An example is the lazmkunit-addin, which needs the lazarusdir setting. (FPMakeOptions=--lazarusdir=/path/to/lazarus)
The version number of the used configuration-file format. Is used internally to check if the configuration file is in the format fppkg expects. Do not change.

Configuration for use with Lazarus

Some packages use the lazmkunit to integrate with Lazarus. When these packages are installed they need to know where Lazarus is installed. Add the following line with the path to your lazarus installation to fppkg.cfg:


Compiler configuration files

A compiler configuration file contains all information necessary to select which fpc-compiler to use. A typical compiler-configuration file looks like this:


The following settings are available:

The prefix which has to be used when installing global packages. Normally this is the prefix of where fpc is installed, so that the packages which are installed by fpc are recognised. Supports macros.
Supports macros.
This is the location where the global packages are installed. The default value is {GlobalPrefix}lib/fpc/{compilerversion}/ on unices, and {globalprefix} on other operating systems. Supports macros.
This is the location where the user-specifig (local) packages are installed. Add this path to the search path of the compiler if you want to use one of the packages installed into this location. The default value is {LocalPrefix}lib/fpc/{compilerversion}/ on unices, and {LocalPrefix} on other operating systems. Supports macros.
The executable name of the compiler which has to be used.
The target OS.
The target CPU-family.
The version of the used compiler.
The version number of the used configuration-file format. Is used internally to check if the configuration file is in the format fppkg expects.

Using macros in the configuration files

To make life easier you can use macros within the configuration-files. Macro's are between accolades '{}' and they are substituted on by some dynamic values. The following macros are available:

Returns the location where fppkg stores it's user-specific configuration files. In fact it calls GetAppConfigDir with Global=false.
Returns the location of the user's home-directory. (GetUserDir)
The value of LocalRepository in the global configuration file
The version of the compiler as set in the compile configuration file, or the version detected from the compiler executable. This macro is not available in the global configuration file.