Difference between revisions of "fppkg"
(Added section about configuration-file formats) |
m (→Basics) |
||
Line 5: | Line 5: | ||
See also [[FPMake]]. | See also [[FPMake]]. | ||
− | + | == Quick-start guide == | |
− | |||
− | |||
Note: this section is only valid for fppkg from fpc version 2.5.1 or higher. | 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'. You should see something like below. | 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'. You should see something like below. |
Revision as of 16:36, 26 April 2010
Introduction
Fppkg is the freepascal package manager. This tool manages packages from a repository, unzips, builds and installs.
See also 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'. You should see something like below.
Name Installed Available a52 2.5.1-1 - aspell 2.5.1-1 - bfd 2.5.1-1 - lnet - 0.6.3-0
If fppkg does not show any installed packages, you have to adapt the path to your fpc-installation in the default compiler configuration file.
By default this file is named '~/.fppkg/config/default' on Unix/Linux/Posix and '%appdata%\fpc\fppkg\config\default' on windows systems. If you have found this file, open it in your favourite text editor and change the 'GlobalInstallDir' to the location where fpc is installed. For example: 'GlobalInstallDir=/home/joost/fpc-trunk/lib/fpc/2.5.1/'. 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)
#-Fu~/.fppkg/lib/$fpcversion/units/$fpctarget/*
Windows: (fpc.cfg)
#-Fu...
Now you can use the units from the installed packages in all your programs
Commandline arguments
Output of fppkg -h
Usage: .../fppkg [options] <action> <package> Options: -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 Actions: 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
Actions
Update
Update packages list
List
List available and installed packages
Build
Build package
Install
Install package
Download
Download package
Convertmk
Convert Makefile.fpc to fpmake.pp
Configuration
Which configuration file is used?
Fppkg always uses three configuration files. One with some global information and two for the specific compiler that is used. When you have more then one version of freepascal installed you can use different configuration files for each version and select which configuration file you want to use.
When fppkg is started it tries to read it's global configuration first from a user-specific configuration file. See the table for the exact filenames. When this file does not exist it searches for a system-wide configuration file. 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.
OS | User-specific configuration file | System-wide configuration file |
---|---|---|
Unix/Linux | ~/.config/fppkg.cfg | /etc/fppkg.cfg |
Windows | %localsettings%\FreePascal\Packages.cfg |
The location of the compiler-configuration files is given in the global-configuration file. 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.
The global configuration file
The global configuration file contains general information for fppkg, like from which repository to load the packages from and where to place the package files. A typical global configuration file looks like this:
[Defaults] ConfigVersion=4 LocalRepository=~/.fppkg/ BuildDir={LocalRepository}build/ ArchivesDir={LocalRepository}archives/ CompilerConfigDir={LocalRepository}config/ RemoteMirrors=http://www.freepascal.org/repository/mirrors.xml RemoteRepository=auto CompilerConfig=default FPMakeCompilerConfig=default Downloader=lnet
The following settings are available:
- ConfigVersion
- The versionnumber of the used configuration-file format. Is used internally to check if the configuration file is in the format fppkg expects.
- LocalRepository
- The location where local repository information is stored. Supports macros.
- BuildDir
- The location where packages are build. Supports macros.
- ArchivesDir
- Place where packages downloaded from a remote repository are stored. Supports macros.
- CompilerConfigDir
- Place where the compiler-configuration files can be found. Supports macros.
- RemoteMirrors
- The URL to a file which contains all mirrors for a remote repository.
- RemoteRepository
- Contains the repository which has to be used. Selecting 'auto' will result in a random repository selected from the mirror list.
- Compilerconfig
- The filename of the compiler-configuration file which has to be used by default.
- FPMakeCompilerconfig
- The filename of the compiler-configuration file which has to be used by default for compiling the fpmake.pp files.
- Downloader
- Select the download-mechanism. lnet is the default.
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:
[Defaults] ConfigVersion=4 GlobalInstallDir=/usr/local/lib/fpc/2.5.1/ LocalInstallDir={LocalRepository}lib/2.5.1/ Compiler=/usr/local/bin/fpc OS=linux CPU=x86_64 Version=2.5.1
The following settings are available:
- ConfigVersion
- The versionnumber of the used configuration-file format. Is used internally to check if the configuration file is in the format fppkg expects.
- GlobalInstallDir
- This is the location of where the compiler is installed. Supports macros.
- LocalInstallDir
- This is where packages are installed by default. Add this to the search path of the compiler if you want to use one of the packages installed into this location. Supports macros.
- Compiler
- The filename of the compiler which has to be used.
- OS
- The target OS.
- CPU
- The target CPU-family.
- Version
- The version of the used compiler.
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:
- AppConfigDir
- Returns the location where fppkg stores it's user-specific configuration files. In fact it calls GetAppConfigDir with Global=false.
- UserDir
- Returns the location of the user's home-directory. (GetUserDir)
- LocalRepository
- The value of LocalRepository in the global configuration file