Available Languages: | English | Français | 日本語 (Nihongo) | 中文 (简) (Simplified Chinese) |

Creating Fink Packages

This manual documents how to create package descriptions for the Fink package manager. It also provides a policy and guidelines for the Fink distribution. Both the description format and the distribution policy are still evolving, so watch the "Last changed" info and the CVS tag on this page to detect updates. What you're reading right now is a description of the format and policy used in post-0.9.0 development versions of the fink package manager.

If you create packages for Fink, you may want to subscribe to the fink-devel mailing list. If you are looking for a way to help out with Fink, and you have skills in this area, you might consider adopting a package which currently has no maintainer.

Contents

1 Introduction

1.1 What is a Package?

A package is a piece of software that forms an atomic unit. A typical package contains an executable program, the data files it needs, message catalogs for internationalisation and documentation. In Fink, packages can exist in two forms: the package description and the ready-to-install binary package file.

The package description is a human readable text file that contains everything needed to build a package, i.e. to create the binary package file. The information includes meta-data (like the package's name and a prose description of its purpose), the URL of the source code and the instructions necessary to configure, compile and wrap up the package. The description may be accompanied by a patch file.

A binary package file is a file archive that contains the actual files that make up the package, i.e. executables, data files, message catalogs, libraries, include files, etc. The package file also contains some meta-data for the package. Installing a binary package mainly consists of unpacking its contents as it is already in a ready-to-use form. Since Fink builds on the dpkg package manager, the binary package files are in the dpkg format and have the extension .deb.

1.2 Identifying a Package

A package is identified by three strings: the package name, the version and the revision. All of these may contain lower-case letters (a-z), numbers (0-9), dashes (-; note: not allowed in the revision), plus signs (+) and dots (.). Other characters are not allowed. In particular, capital letters and underscores are not allowed.

The package name is simply the name of the software, e.g. openssh. The version, also called the upstream version, is the version identifier of the original software package. It is okay to use letters in the version, e.g. 2.9p1. Both fink and dpkg know how to sort these correctly. The revision is a counter that is increased when the package description changes. It starts at 1 and should be reset to 1 when the upstream version changes. The revision must not contain dashes. The full name of a package is all three items concatenated, with dashes in between, e.g. openssh-2.9p1-2.

2 Package Descriptions

2.1 Tree Layout

Package descriptions are read from the finkinfo directories below the /sw/fink/dists directory. The "Trees" setting in /sw/etc/fink.conf controls which directories are read. The name of package description files must be the full package name plus the extension ".info". As of fink 0.26.0, there are several different ways to specify the filename: it is recommended to use the shortest version which is consistent with other needed package files. The filename takes the form: the invariant packagename, optionally followed by the architecture, optionally followed by the distribution, optionally followed by either version or version-revision, each delimited by hyphens, concluding with ".info". The "architecture" and "distribution" components are only allowed if the corresponding field is present in the package, and if it specifies exactly one value.

The package description tree is organized with several levels of directories. The directories in top-down order:

2.2 File Format

The description files are simple lists of key-value pairs, also called 'fields'. Each line starts with a key, terminated by a colon (:) and followed by the value, like this:

Key: Value

There are two notations for fields that must span multiple lines.

The preferred notation is based on the here-document syntax in shell scripts. In this syntax, the first line consists of the key, followed by << as the value. All following lines are treated as the actual value, until a line with just << on it is encountered. The example from above now looks like this:

InstallScript: <<
mkdir -p %i/share/man
make install prefix=%i mandir=%i/share/man
mkdir -p %i/share/doc/%n
install -m 644 COPYING %i/share/doc/%n
<<

Indentation using this format is optional, but it can be used to improve readability.

The here-document syntax can be nested. This is often used in a SplitOff or SplitOffN field. These fields contain other fields (multiple lines), and this syntax allows these sub-fields to have multiple lines themselves. The same terminator << is used for the sub-here-document. Here is an example:

SplitOff: <<
  Package: %N-shlibs
  InstallScript: <<
    ln -s %p/lib/libfoo.2.dylib %i/lib/libfoo.%v.dylib
  <<
<<

In this format, empty lines and lines starting with a hash (#) are ignored. Keys (field names) are case-insensitive in Fink, so you can write InstallScript, installscript or INSTALLSCRIPT as you please. The first capitalization form is preferred for readability, though. Some fields take a boolean value - any of "true", "yes", "on", "1" (case-insensitive) are treated as true, all other values are treated as false.

2.3 Percent Expansion

To make life easier, Fink supports a set of expansions that are performed on some fields. In order to prevent ambiguity, you can use curly-braces to denote exactly what character(s) should be considered for a percent expansion. For example, %{n} has the same meaning as %n. The available expansions are:

%n

the name of the current package

%N

the Name of the parent package (the same as %n unless within a SplitOff)

Note: If a parent Package field contains %type_*[], those percent expansion values will be included in %N in a SplitOff block (since they are included in %n in the parent).

%e

the package epoch

%v

the package version. Note that the Epoch is not part of %v.

%V

the full package Version, which automatically includes the Epoch if present. Note that this percent expansion is only available for packages whose InfoN level is at least 4.

%r

the package revision

%f

the full package name (%n-%v-%r). Note that the Epoch is not part of %f.

%p, %P

the prefix where Fink is installed, e.g. /sw. You must not assume all users have Fink installed in /sw; use %p to get the correct path.

%d

the destination directory where the tree to be packaged is built, e.g. /sw/src/fink.build/root-gimp-1.2.1-1. This temporary directory serves as root during the installation phase of compiling a package. You must not assume that root-%f will be in %p/src since a user can change that directory using the Buildpath field in /sw/etc/fink.conf.

%D

the Destination for the parent package (the same as %d unless within a SplitOff)

%i

the full install-phase prefix, equivalent to %d%p

%I

the Install prefix of the parent package, equivalent to %D%P (the same as %i unless within a SplitOff)

%a

the path where the patches can be found. As of fink-0.29.0, this variable should not be used. Use %{PatchFile} to access the .patch file. Support for %a will be removed in the future.

%b

the build directory, e.g. /sw/src/fink.build/gimp-1.2.1-1/gimp-1.2.1. You must not assume that %f will be in %p/src since a user can change that directory using the Buildpath field in /sw/etc/fink.conf. The innermost directory is named based on the Source filename, or is the value of the SourceDirectory field (if present), or is not used if NoSourceDirectory is true.

Note: Use this only when there is no other way. The build directory is the current directory when scripts are executed; you should use relative path names in commands.

%c

the parameters for configure: --prefix=%p plus anything specified with ConfigureParams. (The behavior is different when the package has Type: perl; in that case, the default flags for building a perl package are used instead of --prefix=%p in the definition of %c.)

%m

the machine architecture string. This is no longer strictly dictated by the type of machine, but is rather a choice made by the user upon fink installation among those architectures which will run on the user's hardware. Current possible values are 'powerpc' for ppc machines and either 'i386' or 'x86_64' for x86 machines. The choice 'x86_64' is only available if the machine is capable of running 64-bit libraries and executables. (This item was introduced in the fink-0.12 era; the current description is valid for fink-0.29.5 and later.)

%%

the percent character (one that will not be expanded according to whatever follows it). Expansion occurs strictly left-to-right, so %%n is not anything related to the package name, but rather is the string %n. (Introduced in fink-0.18.0)

%type_raw[type], %type_pkg[type], %type_num[type]

pseudo-hashes returning the subtype for the given type. See documentation for the Type field later in this document. The _raw form is the exact subtype string, while the _pkg form has all period characters removed (as per Fink's language-version package naming convention and for other clever uses). (Introduced in a post-0.19.2 CVS version of fink.) The _num form was introduced in fink-0.26.0 and removes all non-digits from the Type field.

Note that when the Type field defines type to be "Boolean", then (%type_pkg[type]) can be used directly in conditional expressions. (Its boolean value is true or false, corresponding to the subtype is being evaluated.)

%{ni}, %{Ni}

the package name invariant portion. These are like %n and %N, except all %type_pkg[] and %type_raw[] are blanked out. (Introduced in a post-0.19.2 CVS version of fink) You should use %{ni} and %{Ni} to avoid confusion with the %n and %N expansions.

%{default_script}

Valid only in PatchScript, CompileScript, and InstallScript fields, the default contents of that type of field. The value is often dependent on the Type field, and is always defined (though it may be blank). When used in the InstallScript of a SplitOff (or SplitOffN), this expansion will yield the parent's default, even though the default for InstallScript in a SplitOff package is blank. (Introduced in fink-0.20.6)

%{PatchFile}

The full path to the file given in the PatchFile field. (Introduced in fink-0.24.12)

%{PatchFileN}

The full path to the file given in the PatchFileN field. (Introduced in fink-0.30.0)

%lib

If Type: -64bit is defined to be -64bit, this expands to lib/ppc64 under the powerpc architecture, and to lib/x86_64 under the i386 architecture (the proper storage locations for 64-bit libraries on 32-bit systems); otherwise, this expands to lib. (Introduced in fink-0.26.0)

Note that %lib is not permitted in the ConfigureParams field unless the InfoN level is at least 4.

3 Packaging Policy

3.1 Package Licenses

The packages included in Fink come with a wide variety of licenses. Most of them place restrictions on redistributing the full source and especially on distributing binaries. Some packages can not be included in the binary distribution of Fink because of these license restrictions. Thus it is very important that package maintainers check the license of their package carefully.

Every package that is to be distributed as a binary package must contain a copy of the license. It must be installed in the doc directory, i.e. in %p/share/doc/%n. (In the InstallScript, %i must be used instead of %p, of course. The DocFiles field takes care of the details automatically.) If there is no explicit license in the original source, include a small text file with a note about the status of the package. Most licenses require that the license accompanies any distribution. Fink's policy is to always do this, even if it is not explicitly required.

To make an automated maintenance of the binary distribution possible, any package that is to be distributed must have a License field. This field denotes the nature of the license and is used to decide which packages make it into the binary distribution and which must be held back. The field may only be present if the actual license terms are included in the binary package, as explained above.

To make the License field useful, only one of the following pre-defined values may be used. If you're packaging something that doesn't fit into these categories, ask for help on the developer mailing list.

3.2 The GPL and OpenSSL

(Policy change effective April, 2005.)

Due to the apparent incompatibility of the OpenSSL license with the GPL and LGPL licenses, fink packages which link to openssl but are licensed under the GPL or LGPL are marked as "Restrictive." As a consequence, the Fink project will not distribute binaries of such packages, although users are free to compile them from source at their discretion.

Package maintainers are encouraged to record the original package license in the DescPackaging field.

3.3 Base System Interference

Fink is an add-on distribution that is installed in a directory separate from the base system. It is crucial that a package does not install files outside of Fink's directory.

Exceptions can be made when there is no other possibility, e.g. with XFree86. In this case the package must check for existing files before installation and refuse to install if it would overwrite existing files. The package must make sure that all files it installed outside of the Fink directory are deleted when the package is removed, or that they cause no harm if they are left there (i.e. they need to check binaries for existence before calling them and the like).

3.4 Shared Libraries

Fink's policy about shared libraries became effective in February 2002. This section of the documentation discusses version 4 of the policy (which coincides with the release of Fink's 0.5.0 distribution), as modified in December, 2006 to handle 64-bit libraries and from January, 2008 to handle private shared libraries. (In addition, the discussion was updated in June, 2008 to eliminate obsolete references to a transitional period for implementing the shared libraries policy.) We begin with a quick summary, and then discuss things in more detail.

Any package which builds shared libraries should treat its shared libraries according to Fink's policy. This means:

Note that a package may also install private shared libraries, which are not intended to be linked from any other package. In this case, the libraries need not go into a separate package, but a Shlibs field must still be part of the package containing shared libraries. Also, maintainers should try to avoid storing a final link from libfoo.dylib in the main library directory %i/lib (or its 64-bit equivalent), to prevent other programs from accidentally linking to this library.

A maintainer who has reasons to deviate from this policy and not split the package should explain the reasons in the DescPackaging field.

For some packages, everything can be accomplished with a main package and a -shlibs package; in other cases you also need a third package. The new SplitOff field actually makes this quite easy.

When three packages are needed, there are two different ways they could be named, depending on whether the libraries (option 1) or the binaries (option 2) are the most important feature of the package. For option 1, use the layout:

PackageContents
foo-shlibs

Shared libraries

foo

Headers

foo-bin

Binaries, etc.

while for option 2, use the layout:

PackageContents
foo-shlibs

Shared libraries

foo-dev

Headers

foo

Binaries, etc.

The policy in detail

We now discuss things in more detail; for examples of the policy in action, see the libpng, libjpeg and libtiff packages.

Software which has been ported to Darwin should build shared libraries whenever possible. (Package maintainers are also free to build static libraries as well, if appropriate for their packages; or they may submit packages containing only static libraries if they wish.) Whenever shared libraries are being built that are expected to be used by other packages, two closely related fink packages should be made, named foo and foo-shlibs. The shared libraries go in foo-shlibs, and the header files go in foo. These two packages can be made with a single .info file, using the SplitOff field, as described below. (In fact, it is often necessary to make more than two packages from the source, and this can be done using SplitOff2, SplitOff3, etc.)

Each software package for which public shared libraries are built must have a major version number N, which is included in the shared library's filename (for example, libbar.N.dylib). The major version number is only supposed to change when a backwards-incompatible change in the library's API has been made. Fink uses the following naming convention: if the upstream name of the package is bar, then the fink packages are called barN and barN-shlibs. (This is only strictly applied to new packages, or when the major version number changes.) For example, the major version number for the pre-existing libpng package was 2, but recent versions of the library have major version number 3. So there are now four fink packages to handle this: libpng, libpng-shlibs, libpng3, libpng3-shlibs. Only one of libpng and libpng3 can be installed at any given time, but libpng-shlibs and libpng3-shlibs can be installed at the same time. (Note that only two .info files are required to build these four packages.)

The shared library itself and certain related files will be put into the package barN-shlibs; the "include" files and certain other files will be put into the package barN. There can be no overlapping files between these two packages, and everything stored in barN-shlibs must have a pathname which somehow includes the major version number N. In many instances, your package will need some files at runtime which are typically installed into %i/lib/bar/ or %i/share/bar/ ; you should adjust the installation paths to %i/lib/bar/N/ or %i/share/bar/N/.

All other packages which depend on bar, major version N, will be asked to use the dependencies

  Depends: barN-shlibs
  BuildDepends: barN

It is not be permitted for another package to depend on barN itself. (Although there may still be a few such dependencies involving packages which were in place prior to February, 2002.) This is signaled to other developers by a boolean field

  BuildDependsOnly: True

within the package description for barN.

If your package includes both shared libraries and binary files, and if the binary files need to be present at runtime (not just at build time), then the binaries must be split off into a third package, which could be called barN-bin. Other packages are allowed to depend on barN-bin as well as barN-shlibs.

When building shared libraries under major version N, it is important that the "install_name" of the library be %p/lib/libbar.N.dylib. (You can find the install_name by running otool -L on your library, or otool64 -L for 64-bit libraries on 10.4.) The actual library file may be installed at another location, such as

  %i/lib/libbar.N.x.y.dylib

and your packages should create symbolic links

  %i/lib/libbar.N.dylib -> %p/lib/libbar.N.x.y.dylib
  %i/lib/libbar.dylib -> %p/lib/libbar.N.x.y.dylib

from the install_name path and from the linking path to the actual library. (The first will not be needed if the library is in fact installed at the install_name path, which is becoming more common.)

If the static library is also built, then it will be installed at

  %i/lib/libbar.a

If the package uses libtool, these things are usually handled automatically, but in any event you should check that they have been done correctly in your case. You should also check that current_version and compatibility_version were defined appropriately for your shared libraries. (These are also shown with the otool -L query, or otool64 -L for 64-bit libraries.)

Files are then divided between the two packages as follows

Notice that both packages are required to have some documentation about the license, but that the directories containing the DocFiles will be different.

Doing this is quite easy in practice, using the SplitOff field. Here is how the example above would be implemented (in part):

Package: barN
Version: N.x.y
Revision: 1
License: GPL
Depends: barN-shlibs (= %v-%r)
BuildDependsOnly: True
DocFiles: COPYING
SplitOff: <<
  Package: barN-shlibs
  Files: lib/libbar.N.x.y.dylib lib/libbar.N.dylib lib/bar/N
  DocFiles: COPYING
<<

During the execution of the SplitOff field, the specified files and directories are moved from the install directory %I of the main package to the install directory %i of the splitoff package. (There is a similar convention for names: %N is the name of the main package, and %n is the name of the current package.) The DocFiles command then puts a copy of the documentation into %i/share/doc/barN-shlibs.

Notice that we have included the exact current version of barN-shlibs as a dependency of the main package barN (which can be abbreviated %N-shlibs (= %v-%r) ). This ensures that the versions match, and also guarantees that barN automatically "inherits" all the dependencies of barN-shlibs.

The BuildDependsOnly field

When libraries are being upgraded over time, it is often necessary to have two versions of the header files available during a transition period, with one version used for compiling some things and the other version used for compiling others. For this reason, the packages containing header files must be constructed with some care. If both foo-dev and bar-dev contain overlapping headers, then foo-dev should declare

  Conflicts: bar-dev
  Replaces: bar-dev

and similarly bar-dev declares Conflicts/Replaces on foo-dev.

In addition, both packages should declare

  BuildDependsOnly: True

This inhibits others from writing packages which depend on foo-dev or bar-dev, since any such dependency will prevent the smooth operation of the Conflicts/Replaces method.

There are some packages containing header files for which it's not appropriate to declare BuildDependsOnly to be true. In that case, the package should declare

  BuildDependsOnly: False

and the reason must be given in the DescPackaging field.

The BuildDependsOnly field should only be mentioned in the package's .info file if the package contains header files, installed into %i/include (or subdirectories thereof).

As of fink 0.20.5, "fink validate" will issue a warning for any .deb which contains header files and at least one dylib, and does not declare BuildDependsOnly to be either true or false. (It is possible that in future versions of fink, this warning will be expanded to cover the case of a .deb with header files and a static library as well.)

The goal of the Shared Library Policy is to allow assure compatibility between libraries supplied by one package and libraries or programs that use them in a different package. Some packages may have shared libraries that are not designed to be used by other packages. Common situations include a suite of programs that come with a back-end library of utility functions or a program that comes with plugins to handle various features. Because these libraries are "private" to the package that has them, they do not require being packaged with separate -shlibs or BuildDependsOnly SplitOffs.

The Shlibs field

In addition to putting the shared libraries in the correct package, as of version 4 of this policy, you must also declare all of the shared libraries using the Shlibs field. This field has one line for each shared library, which contains the -install_name of the library. If the library is public, its Shlibs entry also lists the -compatibility_version, versioned dependency information specifying the Fink package which provides this library at this compatibility version, and the library architecture. (The library architecture may either be "32", "64", or "32-64", and may be absent. If the library architecture is not explicitly listed, it defaults to the standard value for the current architecture of Fink; these standard values are "32" for the powerpc and i386 architectures, and "64" for the x86_64 architecture.) The dependency should be stated in the form foo (>= version-revision) where version-revision refers to the first version of a Fink package which made this library (with this compatibility version) available. For example, a declaration

  Shlibs: <<
    %p/lib/libbar.1.dylib 2.1.0 bar1 (>= 1.1-2) 32
  <<

indicates that a (32-bit) library with -install_name %p/lib/libbar.1.dylib and -compatibility_version 2.1.0 has been installed since version 1.1-2 of the bar1 package. In addition, this declaration amounts to a promise from the maintainer that a 32-bit library with this name and a compatibility-version of at least 2.1.0 will always be found in later versions of the bar1 package.

Note the use of %p in the name of the library, which allows the correct -install_name to be found by all users of Fink, no matter what prefix they have chosen.

When a package is updated, usually the Shlibs field can simply be copied to the next version/revision of the package. The exception to this is if the -compatibility_version increases: in that case, the version number in the dependency information should be changed to the current version/revision (which is the first version/revision to provide the library with the new compatibility version number).

The Shlibs entry for a private library uses a different syntax:

  Shlibs: <<
    !%p/lib/%N/libbar.1.dylib
  <<

The leading exclamation point indicates that this is a private library, and since the other information is not relevant in this case, it is not included.

Note that in this example, the private shared library has been placed in its own subdirectory %N of the %i/lib directory (which was named after the package). This is a recommended procedure for private libraries, as an additional safety measure, to prevent other packages from accidentally linking to this library.

What to do when the major version number changes:

If the major version number changes from N to M, you will create two new packages barM and barM-shlibs. The package barM-shlibs can have no overlap with the package barN-shlibs, since many users will have both of these installed simultaneously. In package barM, you should use dependencies

  Conflicts: barN
  Replaces: barN

and similarly, you should revise barN to include dependencies

  Conflicts: barM
  Replaces: barM

Users will then see barN and barM shuffling in and out as various other packages are built which depend on one version or another of the shared library, while barN-shlibs and barM-shlibs remain permanently installed.

Packages containing both binary files and libraries:

When an upstream package contains both binary files and public libraries, some care must be exercised in constructing fink packages. In some cases, the only binary files will be things like foo-config which are presumably only used at build time and never at run time. In these cases, the binaries can go with the header files in the foo package.

In other cases, the binary files will be needed by other packages at runtime, and they must be split off into a separate fink package with a name something like foo-bin. The foo-bin package should depend on the foo-shlibs package, and maintainers of other packages should be encouraged to use

  Depends: foo-bin
  BuildDepends: foo

which will take care of foo-shlibs implicitly.

Upgrading presents a problem in this situation, however, since users won't be prompted to install foo-bin. To work around this, until all other package maintainers have revised their packages as above, your foo package can say

  Depends: foo-shlibs (= exact.version), foo-bin

This will force the installation of foo-bin on most users' systems, until such time as the other package maintainers have upgraded their packages which depend on foo.

As of fink-0.28.0 (released in January 2008), the format of the Shlibs entry for a "private" shared library has changed (see earlier discussion of the difference between a public and a private shared library). Note that the Shared Library Policy has always required all shared libraries to be listed; the change here is only in the syntax of the Shlibs field. Because this type of shared library is not designed to be used by external packages, there is no need to document its compatilibity or other versioning. Instead, an exclamation-mark is used. For example, if libquux.3.dylib is the install_name of a private shared library, it would be listed as follows:

  Shlibs: <<
    !%p/lib/libquux.3.dylib
  <<

3.5 Perl Modules

Fink's policy about perl modules, originally implemented in May 2003, has been revised as of April 2004.

Traditionally, the Fink packages for perl modules had the suffix -pm, and were built using the Type: perl directive, which stores the perl module's files in /sw/lib/perl5 and/or /sw/lib/perl5/darwin. Under the policy now in place, this storage location is only permitted for perl modules which are independent of the version of perl being used to compile them (and which do not depend on other perl modules that lack this independence-of-version).

The perl modules which are version-dependent are the so-called XS modules, which frequently contain compiled C code as well as pure perl routines. There are a number of ways of recognizing these, including the presence of a file with a suffix .bundle.

A version-dependent perl module must be built using a versioned binary of perl, such as perl5.12.3, and must store its files in versioned subdirectories of the standard perl directories, such as /sw/lib/perl5/5.12.3 and /sw/lib/perl5/5.12.3/darwin. By convention, package names use the suffix -pm5123 for a perl module of version 5.12.3. Similar storage and naming conventions are in force for other versions of perl, which include perl 5.10.0 (in the 10.6 tree only), perl 5.12.4 (in the 10.7 tree only), and perl 5.16.2 (in the 10.7 tree only).

The directive Type: perl 5.12.3 automatically uses the versioned perl binary and stores the files in the correct subdirectories. (This directive is available starting with version 0.13.0 of fink.)

Under the May 2003 policy, it was permitted to create a -pm package which is essentially a "bundle" package that loads the -pm560 variant or any others which may be exist. Under the April 2004 policy this is discouraged, and after a transitional period was outlawed entirely.

As of fink 0.20.2, the system-perl virtual package automatically "Provides" certain perl modules depending on the system-perl version. The code generating the list of provided perl modules is found in the VirtPackage.pm file that is part of the fink package.

As different system perls provide different modules, package maintainers are encouraged to check to be sure that they are assuming the correct list when using provided perl modules.

Effective with version 0.13.0 of fink, the fink validate command when applied to a .deb file will check to see if the fink package is an XS module which has been installed in a non-versioned directory, and will issue a warning if so.

Users may have more than one version of perl installed at a time, so any perl-versioned module packages must be written to allow more than one version of themselves to be installed concurrently. One must use care when installing manpages and binary or other script executables in these packages in order to prevent installation conflicts due to filename collisions. You are not allowed to have any files in a package whose name ends with -pmXYZ that would have an identical pathname across different XYZ. Using Replaces to allow the same-named files to overwrite each other in different perl-versions of these perl-module packages is no longer acceptable. As a simple solution for manpages, starting in March 2005, Fink has defined alternate locations in MANPATH: %p/lib/perl5/X.Y.Z/man for each perl-X.Y.Z. You no longer need to create mutually-exclusive -man or -doc SplitOff packages. For example, to avoid conflicts between uri-pm5124 and uri-pm5162, the same-named URI.3pm manpage is installed as %p/lib/perl5/5.12.4/man/man3/URI.3pm and %p/lib/perl5/5.16.2/man/man3/URI.3pm, respectively. Note that the default scripts provided by Type: perl X.Y.Z have not changed, so you will have to locate the manpages here manually in your InstallScript. If you don't have a highly customized script, you can still use the default one, and then simply move the files manually:

%{default_script}
mv %i/share/man %i/lib/perl5/5.12.4

That will move all manpages. If you wish to move only one section of manpages (for example, only section 3, the module manpages, not script manpages in section 1), a similar approach works:

%{default_script}
mkdir -p %i/lib/perl5/5.12.4/man
mv %i/share/man/man3 %i/lib/perl5/5.12.4/man

If you have executables, for example, demo or utility scripts in %p/bin, you have several options. One example is to put these files (and their associated manpages and/or other related files) in a %N-bin splitoff package. Use of Conflicts and Replaces fields ensures that installation of different perl-version forms of these packages, which contain files of the same name, is mutually exclusive. The user can install many different perl-versions of the runtime modules, and then choose whichever one perl-version of the scripts he wants at a given time. For example, Tk.pm comes with an executable ptksh, so the set of tk-pm* packages could be constructed as follows:

Info2: <<
Package: tk-pm%type_pkg[perl]
Type: perl (5.12.3 5.12.4 5.16.2)
InstallScript: <<
  %{default_script}
  mkdir -p %i/lib/perl5/%type_raw[perl]/man
  mv %i/share/man/man3 %i/lib/perl5/%type_raw[perl]/man
<<
SplitOff: <<
  Package: %N-bin
  Depends: %N
  Conflicts: %{Ni}5.12.3, %{Ni}5.12.4, %{Ni}5.16.2
  Replaces: %{Ni}5.12.3, %{Ni}5.12.4, %{Ni}5.16.2
  Files: bin share/man/man1
<<
<<

An alternative arrangement is to rename the scripts and their manpages to include perl-version information. This method means there is no naming conflict at all, so one does not need the mutually-exclusive %N-bin splitoffs:

Info2: <<
Package: tk-pm%type_pkg[perl]
Type: perl (5.12.3 5.12.4 5.16.2)
InstallScript: <<
  %{default_script}
  mkdir -p %i/lib/perl5/%type_raw[perl]/man
  mv %i/share/man/man3 %i/lib/perl5/%type_raw[perl]/man
  mv %i/bin/ptksh %i/bin/ptksh%type_raw[perl]
  mv %i/share/man/man1/ptksh.1 %i/share/man/man1/ptksh%type_raw[perl].1
<<
<<

The user accesses ptksh for whichever perl she wants. For convenience, one could use update-alternatives to allow users to be able to access these by their generic (no perl-version) names as well.

Also as of March 2005, the location of manpages and modules installed by fink packages for perl itself (packages perlXYZ and perlXYZ-core other than the perl-version provided by Apple) has changed. As a result of this relocation, other fink packages that supply updated versions of core perl modules should not list any perlXYZ or perlXYZ-core packages in the Replaces field.

3.6 Emacs Policy

The Fink project has chosen to follow the Debian project's policy regarding emacs, with a few small differences. (The Debian policy document can be found at http://www.debian.org/doc/packaging-manuals/debian-emacs-policy.) There are two differences in the Fink policy. First, this policy only applies to the emacs21, emacs22, and emacs23 packages in fink at the moment, not to the xemacs package. (This may change some day in the future.) And second, unlike the Debian policy, Fink packages are allowed to install things directly into /sw/share/emacs/site-lisp.

3.7 Source Policy

Sources should normally be downloaded from the location(s) that the upstream developer(s) use, and any modifications for Fink should be done through the use of a PatchFile and/or a PatchScript. Do not make changes manually and use a changed source archive as a Source in your Fink packaging.

If a VCS checkout (e.g. from git or svn) is to be used, e.g. because a project doesn't do formal releases, or a fix for a particular issue has been added between releases of a package, an acceptable source can be generated via the following method:

  1. Check out the package, preferably at a definite revision of the VCS.
  2. Make an archive from the VCS checkout (e.g. zip, tar, tar.gz, or tar.bz2).

    Give the tarball a unique version. For example, you can include the VCS revision in the archive name, e.g. foo-0svn1234.tar.gz for a package that doesn't make releases, or bar-1.2.3+svn4567.tar.bz2 for a Fink package which is between upstream releases.

  3. Use the same Version in your .info file.
  4. It is also useful to put the commands that you ran to generate the source tarball in the DescPackaging field.
  5. Upload the tarball to a public download site where users can use fink to download it. If you don't have ready access to one, ask on the Fink developers mailing list or the #fink IRC channel, and someone should be able to help.

3.8 File Download Policy

Packages are not to download any files during the unpack, patch, compile, install, or build phases of the build process. Any large patches (i.e. larger than can be accommodated conveniently in a PatchFile) that need to be applied should set up as additional Sources in accordance with the Source Policy.

Packages may download data in a PostInstScript after they have been installed on the system, under some limited circumstances:

If you are unsure, contact the Fink Core Team.

4 Filesystem Layout

The following file system layout guidelines are part of the Fink packaging policy.

4.1 The Filesystem Hierarchy Standard

Fink follows the spirit of the Filesystem Hierarchy Standard, or FHS for short. It can only follow it in spirit because the FHS was created for system vendors that have control over the / and /usr hierarchies. Fink is an add-on distribution that controls only its install directory (or prefix). The examples use the default prefix of /sw.

4.2 The Directories

Files should go into the following subdirectories of the hierarchy:

FieldValue
/sw/bin

This directory is for general executable programs. There are no subdirectories.

/sw/sbin

This directory is for executable programs that are intended to be used by administrators only. Background daemons go here. There are no subdirectories.

/sw/include

This directory is for C and C++ header files. Subdirectories can be created as necessary. If a package installs header files that can be confused with standard C headers, those headers must go to a subdirectory.

/sw/lib

This directory is for architecture-dependent data files and libraries. Static and shared libraries should be placed directly in /sw/lib unless there is a good reason not to. This is also the place for executables that should not be executed directly by the user (which would otherwise be placed in libexec).

A package is free to create a subdirectory to store private data or loadable modules. Make sure to use directory names that make sense for compatibility. It is wise to use the package major version in the directory name or as an additional hierarchy level, e.g. /sw/lib/perl5 or /sw/lib/apache/1.3. Care should be taken when the host type is used to create directories. A powerpc-apple-darwin1.3.3 directory is bad for compatibility, powerpc-apple-darwin1.3 or just powerpc-apple-darwin are better choices.

/sw/lib/ppc64 /sw/lib/x86_64

This directory is for 64-bit libraries on 32-bit systems, with /sw/lib/ppc64 being used under powerpc architecture, and /sw/lib/x86_64 being used under i386 architecture. Libraries which have been built 'fat' should be stored in /sw/lib instead, and should be so indicated by using '32-64' in the corresponding Shlibs entry. Note that under the x86_64 architecture, 64-bit libraries are to be stored in /sw/lib.

/sw/share

This directory is for architecture-independent data files. The same rules as for /sw/lib apply. Some common subdirectories are described below.

/sw/share/man

This directory contains manual pages. It is organized into the usual section tree. Every program in /sw/bin and /sw/sbin should have an associated manual page here.

/sw/share/info

This directory contains documentation in the Info format (produced from Texinfo sources). Maintenance of the dir file is automated through Debian's version of install-info (part of the dpkg package). Use the InfoDocs description field to automatically generate appropriate code for the postinst and prerm package scripts. Fink makes sure that no package installs a dir file of its own. There are no subdirectories.

/sw/share/doc

This directory contains documentation that is neither a man page nor an Info document. README, LICENSE and COPYING files go here. Every package must create a subdirectory here, named after the package. The subdirectory name must not contain any version numbers (unless they are a part of the package name proper). Hint: Just use %n.

/sw/share/locale

This directory contains message catalogs for internationalization.

/sw/opt

The opt directory stores "add-on" software packages, which for some reason cannot use the standard /sw/bin, /sw/lib, /sw/include, etc. directories. A package to be installed in /sw/opt must locate its static files in a separate /sw/opt/<package> directory tree, where <package> is a name that describes the software package. (Available in fink 0.29.7 or later.)

/sw/var

The var directory stores variable data. This includes spool directories, lock files, state databases, game high scores and log files.

/sw/etc

This directory holds configuration files. For packages that have more than one or two files here a subdirectory should be made. The subdirectory must have the name of the package or program in it so that it is identifiable.

/sw/src

This directory is for storing and building source code. Nothing should be installed here by a package.

/sw/Applications

This directory is for storing OS X-style applications which are launched by double-clicking rather than from the command line.

/sw/Library/Frameworks

This directory is for storing OS X-style frameworks, sometimes used by OS X-style applications.

4.3 Things to Avoid

No other directories than the ones mentioned above should exist in /sw. In particular, the following should not be used: /sw/man, /sw/info, /sw/doc, /sw/libexec, /sw/lib/locale.

5 Compilers

Fink uses the gcc family of compilers, as provided by Apple computer through the Apple Developer Connection. Different versions of gcc exist, and usually more than one is available on a Mac OS X system.

This section explains some of the ways Fink deals with these different versions of gcc. An email to the Fink mailing list has more explanation.

5.1 Compiler Versions

As GCC has evolved, there have been different fink "distributions" to cope with the changes.

Each Fink distribution has had certain default values for the gcc and g++ compilers, which any user compiling from source is expected to have installed. You can expect that direct calls to "gcc" and "g++" from within your package will use these default values. If you need to use a different value (for example, during a transition to a new distribution, your packages .info file must specify this using the versioned binaries provided by Apple. Exactly how you will do this depends on the build system of your software, but for many packages, the SetCC and SetCXX fink fields can be used for this purpose. For example, you might change the g++ compiler to version 3.3 by the setting SetCXX: g++-3.3. Examine the output when building your package to make sure that the correct compiler is being used.

The 10.1 distribution assumes that the compiler version is 2.95; the 10.2 distribution assumes that the compiler version is 3.1; the 10.2-gcc3.3 and 10.3 distributions assume that the compiler version is 3.3. The compiler for the 10.4-transitional distribution is complicated: g++-3.3 is being used along with gcc-4.0. The 10.4 and 10.5 distributions use both gcc-4.0 and g++-4.0. The 10.6 distribution uses gcc-4.2, while the 10.7 through 10.9 distributions use clang and clang++ as the default compilers. The 10.9 distribution has a further change in that it has migrated from libstdc++ to libc++.

A new method for ensuring the correct g++ compiler was introduced with the 10.4-transitional distribution. During compilation, a directory /sw/var/lib/fink/path-prefix-g++-XXX (where XXX is the version number) is added to the PATH during compilation. This directory contains shell scripts which ensure that the correct compiler and version of g++ is used.

5.2 The g++ ABI

The g++ ABI has changed 3 times during the lifetime of OS X: the ABI is different for versions 2.95, 3.1, 3.3 and 4.0. These different ABIs are not compatible with each other, and any libraries which use C++ code and are linked to by your project must be compiled with the same ABI as the one currently being used.

Fink keeps track of the g++ ABI by means of the GCC field. This field should be defined for any package which invokes the g++ or c++ compilers. (It should NOT be defined for packages which don't invoke those compilers.) Whenever an ABI upgrade occurs, all the dependencies of the packages must be checked for their own GCC field. When all of the dependencies have been upgraded, the package itself may be upgraded. The versions of the dependencies must be changed to guarantee that users will have the correct, updated, dependencies in place before they attempt to build the new version of your package.

A small group of packages which depend only on each other can be left at the previous version of the ABI when the distribution changes, if they are not ready to be upgraded. When the upgrade is eventually done, they must be all upgraded together with the correct versioning on all the packages. For this reason, it is best to upgrade most packages at the time the distribution changes.

Fink uses the GCC field to ensure that users have the correct version of the g++ compiler installed. If the GCC field is defined by the package, fink checks to see if the value matches that expected for the OS X version. The correct value is 3.3 for the 10.2 and 10.3 versions of OS X, and 4.0 for OS X 10.4 through OS X 10.9.

6 Reference

6.1 The Build Process

To understand some of the fields, you need some knowledge of the build process Fink uses. It consists of five phases: unpack, patch, compile, install and build. The example paths below are for an installation in /sw and the package gimp-1.2.1-1.

In the unpack phase the directory /sw/src/fink.build/gimp-1.2.1-1 is created and the source tarball(s) are unpacked there. In most cases, this will create a directory gimp-1.2.1 with the source in it; all following steps will be executed in that directory (i.e. /sw/src/fink.build/gimp-1.2.1-1/gimp-1.2.1). Details can be controlled with the SourceDirectory, NoSourceDirectory and SourceNExtractDir fields.

In the patch phase the source is patched so that it will build on Darwin. The actions specified by the UpdateConfigGuess, UpdateLibtool, Patch and PatchScript fields will be executed, in that order.

In the compile phase the source is configured and compiled. Usually this means calling the configure script with some parameters and then issuing a make command. See the CompileScript field description for details. If test suites are enabled for the build (a new feature in fink 0.25, currently achieved by building in maintainer mode), the TestScript will be run immediately after the CompileScript.

In the install phase the package is installed to a temporary directory, /sw/src/fink.build/root-gimp-1.2.1-1 (= %d). (Note the "root-" part.) All files that would normally be installed to /sw are installed in /sw/src/fink.build/root-gimp-1.2.1-1/sw (= %i = %d%p) instead. See the InstallScript field description for details.

(Introduced in fink 0.9.9. It is possible to generate several packages from a single package description using the SplitOff field. Towards the end of the install phase, separate install directories are created for each package being created, and files are moved to the appropriate directory.)

In the build phase a binary package file (.deb) is built from the temporary directory. You can't influence this step directly, but various information from the package description is used to generate a control file for dpkg.

6.2 Fields

We have divided the list of fields into several categories. The list of fields is not necessarily complete. :-)

Initial Data:

FieldValue
Package

The package name. May contain lowercase letters, numbers and the special characters '.', '+' and '-'. No underscores ('_'), no capital letters. Required field.

Percent expansion is applied to this field for %N, %{Ni}, %type_raw[], and %type_pkg[] only.

As per Fink packaging policy, a given package must always compile with the same options enabled. If you have multiple variants for a package (see documentation for the Type field), you must encode the specific variant info into the Package field (see documentation for the %type_pkg[] percent expansion). That way each variant has a unique name the package name indicates which variant option(s) are included. Note that use of the %type_pkg[] and %type_raw[] percent expansions in the Package field is new and severely incompatible with older versions of fink, so such package descriptions must be embedded in a InfoN field with N>=2.

Version

The upstream version number. Same limitations as the Package field. Required field.

Note that some programs use nonstandard version numbering schemes that may cause sorting confusion or that contain characters that are not allowed in this field. In these situations, when writing the Fink package, you must convert the upstream value to one that is acceptable and that allows the versions to be arranged in the correct order. When in doubt about how version strings will be sorted, you can use the dpkg command at a shell prompt. For example,

  dpkg --compare-versions 1.2.1 lt 1.3 && echo "true"

will print "true" because version string "1.2.1" is less than "1.3". See the dpkg manpage for more details.

Revision

The package revision. Increase this when you make a new description for the same upstream version. Revision numbers start at 1. Required field.

Fink's policy is that any time you make a change to the .info file that results in changes to the binary (compiled) form of a package (the .deb file), you must increase Revision. This includes changing the Depends or other package lists, and adding, removing, or renaming splitoff packages or shifting files among them. When migrating a package to a new tree (from 10.2 to 10.3, for example) involves such changes, you should increase Revision by 10 (or some other large number) in the newer tree in order to leave space for future updates to the package in the older tree.

Architecture

A comma-separated list of fink architecture(s) for which the package (and any splitoff packages) are intended. As of fink-0.29.5, the valid values for architecture are powerpc, i386, and x86_64. If this field is present and not blank after conditional handling, fink will ignore the package description(s) if the local fink architecture is not listed. If the field is omitted or the value is blank, all architectures are assumed.

One common use of this field will be for packages which require a compiler earlier than gcc-4.0 (or packages which depend on such packages), which should be declared to have architecture powerpc.

This field supports the standard conditional syntax for any value in the value list and percent-expansions can be used (see the Depends field for more information). In this manner, certain variants can be restricted to certain architectures. For example:

  Package: foo-pm%type_pkg[perl]
  Type: perl (5.8.8 5.10.0)
  Architecture: (%type_pkg[perl] = 5100) x86_64

will result in the field for the foo-pm5100 variant being x86_64 and the field being blank for the foo-pm588 variant. Remember that when the field is blank, all architectures are permitted.

The example above gives a very common use of this field: since some modules for system-perl 5.10.0 on 10.6 do not build as 32-bit (i386), this field allows limiting multiple-type perl packages to specific systems.

Distribution

A comma-separated list of distribution(s) for which the package (and any splitoff packages) are intended. At present, the only valid values for distribution are 10.4, 10.5, 10.6, 10.7, 10.8, and 10.9 . If this field is present and not blank after conditional handling, fink will ignore the package description(s) if the local machine distribution is not listed. If the field is omitted or the value is blank, all distributions are assumed. (Introduced in fink 0.26.0.)

Since Fink's 10.7, 10.8, and 10.9 distributions share a common set of finkinfo files, the most common use of this field will be for packages which are suitable for one of those distributions but not the other.

This field supports the standard conditional syntax for any value in the value list and percent-expansions can be used (see the Depends field for more information). In this manner, certain variants can be restricted to certain distributions. For example:

  Package: foo-pm%type_pkg[perl]
  Type: perl (5.12.3 5.12.4)
  Distribution: (%type_pkg[perl] = 5123) 10.7, (%type_pkg[perl] = 5123) 10.8

will result in the Distribution field for the foo-pm5123 variant being 10.7, 10.8 and the field being blank for the foo-pm5124 variant.

Since python 2.5 is not available in the 10.7+ distributions, and the available perl versions vary by distribution, these package types provide a common use of this field. For reference, we note the availabilty of various perl versions in the 10.3 through 10.9 distributions (bolded systems indicate system-perl at that version):

    perl 5.6.0:  10.3
    perl 5.8.0:  10.3
    perl 5.8.1:  10.3, 10.4
    perl 5.8.4:  10.3, 10.4
    perl 5.8.6:  10.3, 10.4, 10.5
    perl 5.8.8:        10.4, 10.5, 10.6
    perl 5.10.0:             10.5, 10.6
    perl 5.12.3:                         10.7, 10.8, 10.9
    perl 5.12.4:                         10.7, 10.8, 10.9
    perl 5.16.2:                         10.7, 10.8, 10.9

A way to include all supported variants in a single finkinfo file is as follows.

  Package: foo-pm%type_pkg[perl]
  Type: perl (5.8.8 5.10.0 5.12.3 5.12.4 5.16.2)
  Distribution: <<
   (%type_pkg[perl] = 588) 10.6,
   (%type_pkg[perl] = 5100) 10.6,
   (%type_pkg[perl] = 5123) 10.7, (%type_pkg[perl] = 5123) 10.8, (%type_pkg[perl] = 5123) 10.9,
   (%type_pkg[perl] = 5124) 10.7, (%type_pkg[perl] = 5124) 10.8, (%type_pkg[perl] = 5124) 10.9,
   (%type_pkg[perl] = 5162) 10.7, (%type_pkg[perl] = 5162) 10.8, (%type_pkg[perl] = 5162) 10.9
  <<

Note that we do not include old distributions, such as 10.2 or 10.4-transitional, since the versions of fink which are relevant for them do not recognize this field.

Epoch

Introduced in fink 0.12.0. This optional field can be used to specify the epoch of the package (which defaults to 0 if not specified). For more information refer to the Debian Policy Manual. Because Fink and some of the underlying Debian tools use name-version-revision as the unique identifier of a package, you must not create a package that differs from another solely by its epoch.

When used in a version string, the Epoch appears before the Version value, separated by a colon (1:3.14-2). Note that the Epoch is not part of %v (or (%f). If you add an Epoch field to a package description file, you may have to adjust versioned dependencies on the packages in it. For example, if you add Epoch: 1 and foo-dev declares Depends: foo-shlibs (= %v-%r), you will need to rewrite that as Depends: foo-shlibs (= %e:%v-%r).

Description

A short description of the package (what is it?). This is a one-line description that will be displayed in lists, so it must be short and informative. It should be less than 45 chars and must be less than 60. It is not necessary to repeat the package name in this field - it will always be displayed in proper context. Required field.

Type

This can be set to bundle. Bundle packages are used to group a set of related packages together. They only have dependencies, but no code and no installed files. The fields Source, PatchScript, CompileScript, InstallScript and related ones are ignored for bundle packages.

nosource is a very similar type. It indicates that there is no source tarball, so nothing is fetched and the unpack phase creates just an empty directory. However, the patch, compile and install phases are executed normally. This way you can bring in all the code with a patch, or just create some directories in the InstallScript. Since fink 0.18.0, you can get the same behavior by setting Source: none. This allows you to use "Type" for other purposes (Type: perl, etc.)

Since fink 0.9.5 there is type perl which causes alternate default values for the compile and install scripts to be used. Beginning in fink 0.13.0, there is a new variant of this type, perl $version, where $version is a specific version of perl consisting of three numbers separated by periods, e.g., perl 5.6.0.

Beginning in a CVS version of fink after fink-0.19.2, the language/language-version use has been generalized to allow any Maintainer-defined types and associated subtypes and more than a single type for a given package. The type and subtype are each arbitrary strings of non-whitespace characters (but parentheses, commas, braces, and percent signs should not be used); no percent-expansion is performed, and the type (not subtype) values are converted to all-lowercase. Multiple type values (each with an optional whitespace-separated subtype) are specified in a comma-separated list.

In addition, the concept of "variants" exists, where a single .info file describes a family of related packages with various options enabled. The key to this whole process is the use of a list of subtypes. Instead of a single string, one uses a space-separated list of strings in parentheses. Fink clones the package description file for each subtype in the list and replaces this list with that single subtype. For example:

Type: perl (5.12.3 5.12.4)

yields two package descriptions, one that behaves as if Type: perl 5.12.3 and the other Type: perl 5.12.4. The special subtype list "(boolean)" stands for a list containing the type itself and a period, so the following two forms are identical:

Type: -x11 (boolean)
Type: -x11 (-x11 .)

Subtype list expansion/package cloning is recursive; if there are multiple types with subtype lists, you will get all combinations:

Type: -ssl (boolean), perl (5.12.3 5.12.4)

One can access the specific variant subtype in other fields using the %type_raw[] and %type_pkg[] pseudo-hashes. Here are two example .info fragments:

Info2: <<
Package: foo-pm%type_pkg[perl]
Type: perl (5.12.3 5.12.4)
Depends: perl%type_pkg[perl]-core
 <<
Info2: <<
Package: bar%type_pkg[-x11]
Type: -x11 (boolean)
Depends: (%type_raw[-x11] = -x11) x11
CompileScript:  <<
  #!/bin/bash -ev
  if [ "%type_raw[-x11]" == "-x11" ]; then
    ./configure %c --with-x11
  else
    ./configure %c --without-x11
  fi
  make
<<
<<

Starting in fink 0.26.0, there is a special Type: -64bit which controls a new percent expansion %lib and also changes the default value of LDFLAGS. When combined with the new construction %type_num[], this allows a single .info file to build both a 32-bit version of a library and a 64-bit version. Here's some sample code:

Info2: <<
Package: foo%type_pkg[-64bit]
Type: -64bit (boolean)
Depends: (%type_raw[-64bit] = -64bit) 64bit-cpu
ConfigureParams: --libdir='${prefix}/%lib'
SplitOff: <<
 Package: %N-shlibs
 Files: %lib/libfoo.*.dylib
 Shlibs: <<
    %p/%lib/libfoo.1.dylib 1.0.0 %n (>= 1.0-1) %type_num[-64bit]
  <<
<<
<<

Note that Type: -64bit is generally not appropriate for the x86_64 architecture, since in that case libraries are being built 64-bit by default and stored in %i/lib.

License

This field gives the nature of the license under which the package is distributed. The value must be one of the values described in Package Licenses earlier in this document. Additionally, this field must only be given if the package actually complies to the packaging policy in these respects, i.e. a copy of the license is installed in the doc directory for the package.

Maintainer

The name and e-mail address of the person responsible for the package. This field is required, and there must be exactly one name and address in the following format:

Firstname Lastname <user@host.domain.com>
InfoN

This field allows fink to implement backward-incompatible syntax changes in package description files. A given version of fink is configured with the maximum integer "N" that it can handle. Any package in a higher InfoN field will be ignored, so this mechanism should only be used when necessary, lest people with older versions of fink be needlessly alienated. To use this mechanism, embed the entire package description in the desired InfoN field. See the "File Format" section earlier in this document for a description of the syntax for multiline fields. Here are the features added for each InfoN level, along with the earliest version of fink that supports it:

  • Info2 (fink>=0.20.0): Ability to use percent-expansions in the main Package field of the .info file and the ability to use the %type_* percent-expansions in the Package field of SplitOff (and SplitOffN) packages.
  • Info3 (fink>=0.25.0): Can indent nicely in .info files, no more support for RFC-822 multi-lines, and can put comments in pkglist fields.
  • Info4 (fink>=0.26.2): adds %V expansion, and permits %lib in ConfigureParams field.

Dependencies:

FieldValue
Depends

A list of packages which must be installed before this package can be built. Percent expansion is performed on this field (as well as the other package list fields in this section: BuildDepends, RuntimeDepends, Provides, Conflicts, Replaces, Recommends, Suggests, and Enhances. Usually, this is just a comma-separated list for plain package names, but Fink now supports alternatives and version clauses with the same syntax as dpkg. A fully featured example:

Depends: <<
	daemonic (>= 20010902-1),
	emacs | xemacs
<<

The layout above is the preferred format for the Depends and similar fields. The field uses the multi-line field declarators << and each package is placed in alphabetical order on its own indented line. If the field only has a single entry, the simplified Field: value format may be used.

Note that there is no way to express real optional dependencies. If a package works both with and without another package, you must either make sure that the other package is not used even when it is present or add it to the Depends field. If you want to offer the user both options, make two separate packages, e.g. wget and wget-ssl.

Order of operations: logical "OR" (list of alternatives) has a higher precedence (binds more tightly) than the logical "AND" between each package (or set of alternatives) in the comma-separated list. Unlike the use of parentheses in arithmetic, there is no way to specify alternative groups of packages or otherwise change the order of operations in Depends and related fields.

Starting with a post-0.18.2 CVS version of fink, you can have conditional dependencies. These are specified by placing (string1 op string2) before a package name. Percent expansion is performed as usual and then the two strings (neither of which can be null) are compared according to the op operator: <<, <=, =, !=, >>, >=. The immediately-following package is only considered as a dependency if the comparison is true.

You can use this format to simplify maintaining several similar packages. For example, the packages elinks and elinks-ssl could both list:

Depends: <<
	expat-shlibs,
	(%n = elinks-ssl) openssl097-shlibs
<<

would have the same effect as having elinks list:

Depends: expat-shlibs

and elinks-ssl list:

Depends: expat-shlibs, openssl097-shlibs

As an alternative syntax, you can also specify (string), which is "true" if string is non-null. For example:

Package: nethack%type_pkg[-x11]
Type: -x11 (boolean)
Depends: (%type_pkg[-x11]) x11

would set the package x11 as a dependency for the nethack-x11 variant but not for the nethack variant.

Note that when using Depends/BuildDepends for shared library packages for which more than one major-version is available, you must not do the following:

  Package: foo
  Depends: id3lib3.7-shlibs | id3lib4-shlibs
  BuildDepends: id3lib3.7-dev | id3lib4-dev

even if your package could work with either library. Pick one (preferably the highest version that can be used successfully) and use it consistently in your package.

As explained in the Shared Library Policy, only one of the -dev packages can be installed at a time, and each has links of the same name that could point to different filenames in the associated -shlibs package. When compiling package foo, the actual filename (in the -shlibs package) gets hard-coded into the foo binary. That means the resulting package needs the specific -shlibs package associated with the -dev that was installed at compile-time. As a result, one cannot have a Depends that indicates that either one will suffice.

In the past, non-essential packages implicitly depended on the essential ones; this is no longer true.

BuildDepends

Introduced in fink 0.9.0. A list of dependencies that is applied at build time only. This can be used to list tools (e.g. flex) that must be present to build the package, but which are not used at run time. Supports the same syntax as Depends. If a build is being done with test suites enabled, the dependencies in the TestDepends field will be added to this list.

RuntimeDepends

Introduced in fink 0.32.0. A list of dependencies that is applied at run time only, that is, when the package is being installed. This can be used to list packages that must be present to run the package, but which are not used at build time. Supports the same syntax as Depends.

Provides

A comma-separated list of package names that this package is considered to "provide". If a package named "pine" specifies Provides: mailer, then any dependency on "mailer" is considered satisfied when "pine" is installed. You'll usually also want to name these packages in the "Conflicts" and the "Replaces" field.

Note that there is no versioning data associated with Provides items. They do not inherit from the parent package that contains the Provides list nor is there a syntax for specifying an arbitrary version in the Provides field itself. Further, a dependency that contains a version specification is not satisfied by a package that Provides that needed package name. As a result, having many variants provide a common surrogate package may be harmful, because it precludes the use of versioned dependencies. For example, if foo-gnome and foo-nognome both have "Provides: foo", another package with "Depends: foo (> 1.1)" will not work.

Conflicts

A comma-separated list of package names that must not be installed at the same time as this package. For virtual packages it is allowed to list the names of the provided packages here; they will be handled appropriately. This fields also supports versioned dependencies like the Depends field, but not alternatives (wouldn't make sense). If a package is listed in its own Conflicts, it will be (silently) removed from that list. (Introduced in a post-0.18.2 CVS version of fink.)

Note: Fink itself currently ignores this field. However, it is passed on to dpkg and will be handled accordingly. In summary, it only effects run-time, not build-time.

BuildConflicts

A list of packages that must not be installed while this package is being compiled. This can be used to prevent ./configure or the compiler from seeing undesired library headers or to avoid use of a version of a tool that is known to be broken (for example, a bug in a certain version of sed). If a build is being done with test suites enabled, the packages in the TestConflicts field will be added to this list.

Replaces

This is used together with "Conflicts", when this package not only takes over the function of the conflicting package, but also has some common files. Without this field, dpkg may generate errors when installing the package because files are still owned by the other package. It is also a hint that the two packages involved are genuine alternatives and one can be removed in favor of the other. If a package is listed in its own Replaces, it will be (silently) removed from that list. (Introduced in a post-0.18.2 CVS version of fink.)

Note: Fink itself currently ignores this field. However, it is passed on to dpkg and will be handled accordingly. In summary, it only effects run-time, not build-time.

Recommends, Suggests, Enhances

These fields specify additional package relations in the same style as the other dependency fields. These three relations don't affect actual installation via dpkg or apt-get. However, they are used by dselect and other frontends to help the user make sensible choices.

Pre-Depends

A special variation of the Depends field with more strict semantics. This field must only be used after the case has been discussed on the developer mailing list and a consensus has been reached that it is necessary.

Essential

A boolean value that denotes essential packages. Essential packages are installed as part of the bootstrap process. dpkg will refuse to remove essential packages from the system unless special flags are used to override this. In the past, non-essential packages implicitly depended on the essential ones; this is no longer true.

BuildDependsOnly

Introduced in fink 0.9.9. A boolean value which indicates that no other packages should Depend on this one, they should only BuildDepend. Unlike usual boolean fields, BuildDependsOnly is tri-state: leaving it undefined (not specifying it at all) is different than defining it as logically false. See the Shared Library Policy for more information.

As of fink 0.20.5, the presence or absence of this field, and its value if present, are recorded into the .deb file when the package is built. Therefore, if you change the value of BuildDependsOnly or if you add or remove it, you must increase the revision number of the package.

Unpack Phase:

FieldValue
CustomMirror

A list of mirror sites. Each mirror site appears on a separate line, in the following format: <location>: <url>. location can be a continent code (e.g. nam), a country code (e.g. nam-us), or anything else; mirrors are tried in that order. Example:

CustomMirror: <<
nam-US: ftp://ftp.fooquux.com/pub/bar
asi-JP: ftp://ftp.qiixbar.jp/pub/mirror/bar
eur-DE: ftp://ftp.barfoo.de/bar
Primary: ftp://ftp.barbarorg/pub/
<<

The standard continent and country codes are listed in /sw/lib/fink/mirror/_keys, which is part of the fink or fink-mirrors package.

Source

An URL to the source tarball. It should be a HTTP or FTP URL, but Fink doesn't really care - it just passes the URL to wget. This field supports a special URL scheme for mirrors: mirror:<mirror-name>:<relative-path>. This will look up the mirror setting for mirror-name in Fink's configuration, append the relative-path part and use that as the actual URL. The known mirror-names are listed in /sw/lib/fink/mirror/_list, which is part of the fink or fink-mirrors package. Alternatively, using custom as the mirror-name will cause Fink to use the CustomMirror field. Before the URL is used, percent expansion takes place. Remember that %n includes all %type_ variant data, so you may want to use %{ni} here (perhaps with some specific %type_ expansions).

Since fink 0.18.0, Source: none has the special meaning that there is no source to fetch. See the description of the Type field for more information. The value gnu is a shorthand for mirror:gnu:%n/%n-%v.tar.gz; gnome is a shorthand for mirror:gnome:stable/sources/%n/%n-%v.tar.gz. The default is %n-%v.tar.gz (i.e. a manual download). This implicitly-defined Source form is deprecated (explicitly-stated simple filename/manual download is still okay).

Sources that are only needed in order to run test suites should use TestSource and related fields, inside the InfoTest block.

SourceN

If a package consists of several tarballs, name them with these additional fields, starting with N = 2. So, the first tarball (which should be some kind of "main" tarball) goes into Source, the second tarball in Source2 and so on. The rules are the same as for Source, only that the "gnu" and "gnome" shortcuts are not expanded - that would be useless anyway. Starting with a CVS version of fink after 0.19.2, you may use arbitrary (not necessarily consecutive) integer values of N >= 2. However, you still may not have duplicates.

SourceDirectory

Must be used when the tarball expands to a single directory, but the directory's name is different from the basename of the tarball. Usually, a tarball named "foo-1.0.tar.gz" will produce a directory named "foo-1.0". If it produces a directory with a different name, specify it with this parameter. Percent expansion is performed on this field.

NoSourceDirectory

Set this boolean parameter to a true value if the tarball does not expand to a single directory. Usually, a tarball named "foo-1.0.tar.gz" will produce a directory named "foo-1.0". If it just unpacks the files to the current directory, use this parameter and set it to a boolean true value.

SourceNExtractDir

Normally, an auxiliary tarball will be extracted in the same directory as the main tarball. If you need to extract it in a specific subdirectory instead, use this field to specify it. Source2ExtractDir corresponds to the Source2 tarball, as one would expect. See ghostscript, vim and tetex for examples of usage.

SourceRename

This field can rename a source tarball on the fly. This is useful if for example the version of the source is encoded in the directory name on the server, but the tarball itself has the same name for all versions, e.g. http://www.foobar.org/coolapp/1.2.3/source.tar.gz. To circumvent the problems caused by this, you would then use something like

SourceRename: %n-%v.tar.gz

In the above example this would result in the tarball being stored under /sw/src/coolapp-1.2.3.tar.gz as one would expect.

SourceNRename

This is just the same as the SourceRename field, except that it is used to rename the tarball specified by the corresponding SourceN field. See context or hyperref for examples of usage.

Source-MD5

Introduced in fink 0.10.0. With this field you can specify the MD5 checksum of the source file. This information is then used by Fink to detect incorrect source files, that is, tarballs not matching the one the package creator used. Common causes for this problem include: incompletely downloaded tarballs; upstream maintainers silently replaced a tarball; a trojan or similar attacks; and so on.

A typical usage example looks like this:

Source-MD5: 4499443fa1d604243467afe64522abac

To compute the checksum, the md5sum tool is used. If you want to determine the checksum of the tarball /sw/src/apache_1.3.23.tar.gz, you run the following command (displayed with output here):

fingolfin% md5sum /sw/src/apache_1.3.23.tar.gz 
4499443fa1d604243467afe64522abac  /sw/src/apache_1.3.23.tar.gz

As you can see, the value to the left is exactly the value you need.

SourceN-MD5

Introduced in fink 0.10.0. This is just the same as the Source-MD5 field, except that it is used to specify the MD5 checksum of the tarball specified by the corresponding SourceN field.

TarFilesRename

Introduced in fink 0.10.0. This field only applies to source files that are using the tar format

With this field you can rename files in the given source tarball during the extraction of the tarball. This is very useful to work around the fact that the HFS+ file system is not case sensitive, as files like install and INSTALL will collide on a standard Mac OS X system. With this field you can avoid these issues without having to repackage the tarball (as was done in the past in such cases).

In this field you simply specify a list of files that are to be renamed. You can make use of wildcards. By default any given file will be renamed to its current name with _tmp appended. You can override this default by using the same syntax as in the Files and DocFiles fields, namely by writing the old filename followed by a : and then followed by the new filename. Example:

TarFilesRename: foo bar.* qux:quux
Tar2FilesRename: directory/INSTALL:directory/INSTALL.txt
TarNFilesRename

Introduced in fink 0.10.0. This is just the same as the TarFilesRename field, except that it is used for the tarball specified by the corresponding SourceN field.

Patch Phase:

FieldValue
UpdateConfigGuess

A boolean value. If true, the files config.guess and config.sub in the build directory will be replaced with versions that know about Darwin. This happens in the patch phase and before the PatchScript is run. Only use this when you know it is necessary, i.e. when the configure script fails with a "unknown host" message.

UpdateConfigGuessInDirs

Introduced in a post-0.9.0 CVS version. A list of subdirectories. This does the same as UpdateConfigGuess, but is useful for packages that have outdated config.guess files in several directories throughout the source tree. Previously you had to copy/move the files there manually in the PatchScript. With this new field you can just list the directories. Use . to update files in the build directory itself.

UpdateLibtool

A boolean value. If true, the files ltconfig and ltmain.sh in the build directory will be replaced with versions that know about Darwin. This happens in the patch phase and before the PatchScript is run. Only use this when you know that the package needs it. Some packages can be broken by overwriting the libtool scripts with mismatching versions. See the libtool page for further information.

UpdateLibtoolInDirs

Introduced in a post-0.9.0 CVS version. A list of subdirectories. This does the same as UpdateLibtool, but is useful for packages that have outdated libtool 1.3.x scripts in several directories throughout the source tree. Previously you had to copy/move the files there manually in the PatchScript. With this new field you can just list the directories. Use . to update files in the build directory itself.

UpdatePoMakefile

A boolean value. If true, the file Makefile.in.in in the subdirectory po is replaced with a patched version. This happens in the patch phase and before the PatchScript is run.

The patched version respects DESTDIR and makes sure that message catalogs end up in /sw/share/locale, not /sw/lib/locale. Before using this field, make sure that you won't break the package and that it's really required. You can run diff to find the differences between the package's version and Fink's version (in /sw/lib/fink/update).

Patch

The filename of a patch to be applied with patch -p1 <patch-file. This should be just a filename; the appropriate path (the same directory where the .info file is located) will be prepended automatically. Percent expansion is performed on this field, so a typical value is simply %f.patch or %n.patch. The patch is applied in a separate step before the PatchScript is run (if any).

Remember that %n includes all %type_ variant data, so you may want to use %{ni} here (perhaps with some specific %type_ expansions). It's easier to maintain a single patchfile and then make variant-specific changes in PatchScript than to have a separate patchfile for each variant.

As of fink-0.29.0, this field should not be used. Use PatchFile instead. Support for Patch will be removed in the future.

PatchFile

The same syntax as the Patch field. The full path to this file is available using the %{PatchFile} percent expansion--do not use %a to access this file. Unlike Patch, PatchFile is applied as part of PatchScript. Fink checks that the listed file exists, is readable, and that its checksum matches the PatchFile-MD5 field.

You may not use both Patch and PatchFile in the same package description. Any package that uses PatchFile must declare at least BuildDepends: fink (>= 0.24.12). Giving a higher version requirement is allowed if it is necessary for other reasons.

PatchFileN

If a package has several patch files, name them with these additional fields, starting with N = 2. So, the first patch file goes into PatchFile, the second patch file in PatchFile2 and so on. Any package that uses PatchFileN must declare at least BuildDepends: fink (>= 0.30.0). Giving a higher version requirement is allowed if it is necessary for other reasons.

PatchFile-MD5

The MD5 checksum of the file given in the PatchFile field. This field is required if PatchFile is used. (Introduced in fink-0.24.12)

PatchFileN-MD5

The MD5 checksum of the file given in the PatchFileN field. This field is required if PatchFileN is used. (Introduced in fink-0.30.0)

PatchScript

A list of commands that are run in the patch phase. This is the place to put commands that patch or otherwise modify the package source. See the note on scripts below. Before the commands are executed, percent expansion takes place. If a PatchFile field exists, the default PatchScript is:

patch -p1 < %{PatchFile}

If one or more PatchFileN fields are used, the following is appended as needed to the default script:

patch -p1 < %{PatchFileN}

If there is no PatchFile, the default is blank. If you have an explicit PatchScript, you must apply the PatchFile(s) explicitly.

Compile Phase:

FieldValue
SetENVVAR

Causes certain environment variables to be set in the compile and install phases. This can be used to pass compiler flags etc. to configure scripts and Makefiles. Currently supported variables are: CC, CFLAGS, CPP, CPPFLAGS, CXX, CXXFLAGS, DYLD_LIBRARY_PATH, JAVA_HOME, LD, LDFLAGS, LIBRARY_PATH, LIBS, MACOSX_DEPLOYMENT_TARGET, MAKE, MFLAGS, MAKEFLAGS. The value you specify is subject to the percent expansion described in the last section. A common example:

SetLDFLAGS: -Wl,-strip_dead_dylibs

Some environment variables have default preset values. If you specify a value for one of these, it will be prepended to the default value. The preset variables (and their default values) are:

CPPFLAGS: -I%p/include
LDFLAGS: -L%p/lib

Starting in fink 0.26.0, there is one exception to these defaults: if Type: -64bit is set to -64bit, then the default value of LDFLAGS is -L%p/%lib -L%p/lib instead.

Finally, MACOSX_DEPLOYMENT_TARGET is set to a default value depending on which version of OSX is being run, but setting a value for it for a package will override (rather than prepend to) the default value.

NoSetENVVAR

When set to a true value, deactivates the default values for the preset variables (such as CPPFLAGS, LDFLAGS, CXXFLAGS mentioned above). For example, if you want LDFLAGS to remain unset, specify NoSetLDFLAGS: true .

UseMaxBuildJobs

When set to a true value, appends -jN, where N is the value from the fink.conf field MaxBuildJobs, to the environment variable MAKEFLAGS during CompileScript and TestScript. This value is added to MAKEFLAGS even if the field NoSetMAKEFLAGS: true is used. As of fink > 0.31.2, if the field is not present or blank, the default is True.

BuildAsNobody

In fink >= 0.33.0, when set to a false value, causes fink to build as root rather than as the underprivileged fink-bld user. If this field is not present, its value defaults to true, indicating that the package should be built as fink-bld.

In earlier fink versions, this field does nothing.

ConfigureParams

Additional parameters to pass to the configure script. (See CompileScript for details.) For packages not of Type: Perl, the parameter --prefix=%p is prepended to this value. As of fink > 0.13.7, this field will also work with perl modules Type: Perl; the default perl Makefile.PL string is prepended to the value supplied for ConfigureParams.

If a build is being done with test suites enabled, the value of the TestConfigureParams field will be appended to the normal ConfigureParams value.

Starting in fink-0.22.0, this field supports conditionals. The syntax is the same as that used in the Depends and other package-list fields. The conditional expression only applies to the whitespace-delimited "word" immediately following it. For example

Type: -x11 (boolean)
ConfigureParams: --mandir=%p/share/man (%type_pkg[-x11]) --with-x11 --disable-shared

will always pass the --mandir and --disable-shared flags, but only pass --with-x11 in the -x11 variant.

This field supports placing parameters into multiple lines using multi-line field declarators. The field is handled as a shell command line and uses \ to separate lines:

ConfigureParams: <<
	--mandir=%p/share/man \
	(%type_pkg[-x11]) --with-x11 \
	--disable-shared
<<

Note: do not place conditional parameters as the last line when using the multi-line field format. In instances when the conditional evaluates as false, the parameter immediately following is not evaluated and this breaks the shell.

GCC

This field specifies the GCC-ABI used by C++ code in this package. (It is needed because that ABI has changed twice, and any libraries which you link to containing C++ code must be compiled with the same ABI you are currently using.)

The allowed values are: 2.95.2 (or 2.95), 3.1, 3.3, and 4.0. Our understanding is that the GCC authors intend to stabilize the GCC-ABI at some point; we can hope that it won't change again.

The GCC field does not have a default value, per se, since it is ignored if it is not set. However, for each tree, there is an expected value for GCC corresponding to the default g++ compiler for that tree. The expected values for the various package trees are: 2.95 in the 10.1 tree, 3.1 in the 10.2 tree, 3.3 in the 10.2-gcc3.3, 10.3, and 10.4-transitional trees, and 4.0 in the 10.4 and 10.7 trees.

Note that when the GCC value is different from the expected value, the compiler must be specified within the package (typically by setting the CC or CXX flags), and a dependency on one of the (virtual) gcc packages should be specified.

As of fink 0.13.8, when this flag is present, the version of gcc is tested using gcc_select, and fink exits with an error if the wrong version is present.

This field was added to fink to aid maintainers in tracking the transition between the gcc compilers, which introduced a binary incompatibility between libraries that involve C++ code which is not reflected in the versioning scheme.

CompileScript

A list of commands that are run in the compile phase. This is the place to put commands that configure and compile the package. See the note on scripts below. Before the commands are executed, percent expansion takes place. Normally the default is:

./configure %c
make

This is appropriate for packages that use GNU autoconf. For packages with of type perl (as specified via the Type field) with the perl version not specified, the default instead (as of fink 0.13.4) is:

perl Makefile.PL PREFIX=%p \
 INSTALLPRIVLIB=%p/lib/perl5 \
 INSTALLARCHLIB=%p/lib/perl5/darwin \
 INSTALLSITELIB=%p/lib/perl5 \
 INSTALLSITEARCH=%p/lib/perl5/darwin \
 INSTALLMAN1DIR=%p/share/man/man1 \
 INSTALLMAN3DIR=%p/share/man/man3 \
 INSTALLSITEMAN1DIR=%p/share/man/man1 \
 INSTALLSITEMAN3DIR=%p/share/man/man3 \
 INSTALLBIN=%p/bin \
 INSTALLSITEBIN=%p/bin \
 INSTALLSCRIPT=%p/bin
make
make test

If the type is perl $version with the version specified (e.g., $version might be 5.6.0), then the default becomes:

perl$version Makefile.PL \
 PERL=perl$version PREFIX=%p \
 INSTALLPRIVLIB=%p/lib/perl5/$version \
 INSTALLARCHLIB=%p/lib/perl5/$version/$perlarchdir \
 INSTALLSITELIB=%p/lib/perl5/$version \
 INSTALLSITEARCH=%p/lib/perl5/$version/$perlarchdir \
 INSTALLMAN1DIR=%p/share/man/man1 \
 INSTALLMAN3DIR=%p/share/man/man3 \
 INSTALLSITEMAN1DIR=%p/share/man/man1 \
 INSTALLSITEMAN3DIR=%p/share/man/man3 \
 INSTALLBIN=%p/bin \
 INSTALLSITEBIN=%p/bin \
 INSTALLSCRIPT=%p/bin
make
make test

where $perlarchdir is "darwin" for versions 5.8.0 and earlier, and is "darwin-thread-multi-2level" for versions 5.8.1 and later.

NoPerlTests

Introduced in fink > 0.13.7. A boolean value, specific for perl module packages. If true, the make test portion of the CompileScript will be ignored for that specific perl module package.

Test Suites:

FieldValue
InfoTest

Introduced in fink 0.25. This field encapsulates information that will only be used when performing a build with test suites enabled. It contains other fields. If present, this field must contain a TestScript. All other fields are optional. The following fields are allowed inside InfoTest:

  • TestScript: A script which runs the test suite. This script should exit with status 0 if the suite passes, 1 to indicate warnings, or any other value to indicate failures serious enough to be considered fatal. Because of this tri-state logic, you should explicitly set an exit value in this script. For instance, make check is a bad script, since it will exit with status 1 if the check target doesn't exist. make check || exit 2 would be a better script.
  • TestConfigureParams: A value which will be appended to ConfigureParams.
  • TestDepends and TestConflicts: Lists of packages that will be added to the BuildDepends or BuildConflicts lists.
  • TestSource: Extra sources necessary to run the test suite. All of the affiliated fields are also supported, so you must also specify TestSource-MD5, and you may also have TestSourceN and corresponding TestSourceN-MD5, TestTarFilesRename, etc.
  • TestSuiteSize: Describes approximately how long the test suite takes to run. Valid values are small, medium, and large. This field is currently ignored.
  • Any other standard field. If a field is specified both inside and outside InfoTest, the value inside InfoTest will replace the other value when test suites are active.

Here's an example:

InfoTest: <<
    TestScript: make check || exit 2
    TestConfigureParams: --enable-tests
<<

Install Phase:

FieldValue
UpdatePOD

Introduced in fink 0.9.5. A boolean value, specific for perl module packages. If true, this will add code to the install, postrm and postinst scripts that maintains the .pod files provided by perl packages. This includes adding and removing the .pod date from the central /sw/lib/perl5/darwin/perllocal.pod file. (If the type has been given as perl $version with a specific version of perl such as 5.6.0, then these scripts are adapted to deal with the central .pod file /sw/lib/perl5/$version/perllocal.pod.)

InstallScript

A list of commands that are run in the install phase. This is the place to put commands that copy all the necessary files into the temporary dpkg directory for the package. See the note on scripts below. Before the commands are executed, percent expansion takes place. Normally the default is:

make install prefix=%i

The default is appropriate for packages that use GNU autoconf. For packages with of type perl (as specified via the Type field) with the perl version not specified, the default instead (as of fink 0.13.4) is:

make install INSTALLPRIVLIB=%i/lib/perl5 \
 INSTALLARCHLIB=%i/lib/perl5/darwin \
 INSTALLSITELIB=%i/lib/perl5 \
 INSTALLSITEARCH=%i/lib/perl5/darwin \
 INSTALLMAN1DIR=%i/share/man/man1 \
 INSTALLMAN3DIR=%i/share/man/man3 \
 INSTALLSITEMAN1DIR=%i/share/man/man1 \
 INSTALLSITEMAN3DIR=%i/share/man/man3 \
 INSTALLBIN=%i/bin \
 INSTALLSITEBIN=%i/bin \
 INSTALLSCRIPT=%i/bin

If the type is perl $version with the version specified (e.g., $version might be 5.6.0), then the default becomes:

make install INSTALLPRIVLIB=%i/lib/perl5/$version \
 INSTALLARCHLIB=%i/lib/perl5/$version/$perlarchdir \
 INSTALLSITELIB=%i/lib/perl5/$version \
 INSTALLSITEARCH=%i/lib/perl5/$version/$perlarchdir \
 INSTALLMAN1DIR=%i/share/man/man1 \
 INSTALLMAN3DIR=%i/share/man/man3 \
 INSTALLSITEMAN1DIR=%i/share/man/man1 \
 INSTALLSITEMAN3DIR=%i/share/man/man3 \
 INSTALLBIN=%i/bin \
 INSTALLSITEBIN=%i/bin \
 INSTALLSCRIPT=%i/bin

where $perlarchdir is "darwin" for versions 5.8.0 and earlier, and is "darwin-thread-multi-2level" for versions 5.8.1 and later.

If the package supports it, it is preferably to use make install DESTDIR=%d instead.

AppBundles

Introduced in a post-0.23.1 version. This field installs the specified application bundle(s) into %p/Applications. It will also create a symlink to the /Applications/Fink directory. Example:

AppBundles: build/*.app Foo.app
JarFiles

Introduced in fink 0.10.0. This field is somewhat similar to DocFiles. It installs the specified jar files into %p/share/java/%n. Example:

JarFiles: lib/*.jar foo.jar:fooBar.jar

This will install all the jars that were in the lib directory and will install foo.jar as fooBar.jar.

It also ensures that these jar files (specifically: all files in %p/share/java/%n that end in .jar) are added to the CLASSPATH environment variable. This allows tools like configure or ant to properly detect the installed jar files.

DocFiles

This field provides a convenient way to install README or COPYING files in the doc directory for the package, %p/share/doc/%n. The value is a space-separated list of files. You can copy files from subdirectories of the build directory, but they will end up in the doc directory itself, not in a subdirectory. Shell wildcards are allowed. It is also possible to rename single files on the fly by appending the new name separated by a colon (:), e.g. libgimp/COPYING:COPYING.libgimp. This field works by appending appropriate install commands to the InstallScript.

Shlibs

Introduced in fink 0.11.0. This field declares the shared libraries which are installed in the package. There is one line for each shared library, which contains the -install_name of the library and information about its binary compatibility. Shared libraries that are "public" (i.e., provided for use by other packages) have, separated by whitespace after the filename, the -compatibility_version, versioned package dependency information specifying the Fink package which provides this library at this compatibility version, and the library architecture. (The library architecture may either be "32", "64", or "32-64", and may be absent; if absent, the value defaults to "32" under the powerpc and i386 machine architectures, and to "64" under the x86_64 machine architecture.) The dependency should be stated in the form foo (>= version-revision) where version-revision refers to the first version of a Fink package which made this library (with this compatibility version) available. The Shlibs declaration amounts to a promise from the maintainer that a library with this name and a -compatibility_version of at least this number will always be found in later versions of this Fink package. Shared libraries that are "private" are denoted by an exclamation mark preceeding the filename, and no compatilibity or versioning information is given. See the Shared Library Policy for more information.

RuntimeVars

Introduced in fink 0.10.0. This field provides a convenient way to set environment variables to some static value at runtime (if you need more flexibility, refer to the profile.d scripts section). As long as your package is installed, these variables will be set via the /sw/bin/init.[c]sh scripts.

The value of your variable can contain spaces (trailing ones are trimmed); also, percent expansion takes place. For example:

RuntimeVars: <<
 SomeVar: %p/Value
 AnotherVar: foo bar
<<

will set two environment variables 'SomeVar' and 'AnotherVar' and their values will be respectively '/sw/Value' (or whatever your prefix is) and 'foo bar'.

This field works by appending appropriate commands to the InstallScript. These commands add a setenv/export line for each variable to the package profile.d scripts, so you can provide your own ones, they won't be overwritten. The lines are prepended to the scripts, you can thus use these variables in your scripts.

SplitOff

Introduced in fink 0.9.9. Generate a second package from the same compile/install run. For details about how this works, see the separate splitoff section below.

SplitOffN

Introduced in fink 0.9.9. This is the same as SplitOff, used to generate a third, fourth, etc. package from the same compile/install run. Starting with a CVS version of fink after 0.19.2, you may use arbitrary (not necessarily consecutive) integer values of N >= 2. However, you still may not have duplicates.

Files

Introduced in fink 0.9.9. Used only within a SplitOff or SplitOffN field, this designates which files and directories should be moved from the parent package's installation directory %I to the current installation directory %i. Note that this is executed after the InstallScript and the DocFiles of the parent package, but before the InstallScript and Docfiles of the current package.

Build Phase:

FieldValue
PreInstScript, PostInstScript, PreRmScript, PostRmScript

These fields specify pieces of shell scripts that will be called when the package is installed, upgraded or removed. Fink automatically adds the shell script header #!/bin/sh, and calls set -e so any command that fails will result in instant termination of the script. Fink also adds an exit 0 at the end. To indicate an error, exit from the script with a non-zero exit code. The first parameter ($1) is set to a value indicating what action is being performed. Some possible values are install, upgrade, remove and purge. Note that there are more values, used during error rollback or when removing a package in favor of another one.

The scripts are called at the following times:

  • PreInstScript: When the package is installed for the first time and before upgrading the package to this version.
  • PostInstScript: After unpacking and setting up the package.
  • PreRmScript: Before the package is removed or upgraded to a later version.
  • PostRmScript: After the package was removed or upgraded to a later version.

To make it more clear, an upgrade invokes both the ...Inst scripts of the new version and the ...Rm scripts of the old version. Details can be found in the Debian Policy Manual, Chapter 6.

Percent expansion is performed on the scripts. Commands can generally be called without giving a full path.

ConfFiles

A space-separated list of files that are user-modifiable configuration files. Percent expansion is performed on this field. The files must be specified with an absolute path, e.g. %p/etc/%n.conf. The named files will receive special treatment by dpkg. When a package is upgraded and the file has changed both on disk and in the package, the user is asked which version to use and backups of the file will be made. When a package is "remove"d, the configuration files will remain on disk. Only a "purge" also removes the configuration files.

InfoDocs

Lists the names of Info documents that the package installs in %p/share/info. This will add appropriate code to the postinst and prerm scripts to maintain the Info directory file, dir.

Note: Only use the un-numbered file in the case of split Info documents. E.g. if a package has:

foo.info
foo.info-1
foo.info-2

you should only use:

InfoDocs:  foo.info

This feature is still in flux, more fields for finer control may be added in the future.

DaemonicFile

Gives a service description for daemonic. daemonic is used by Fink to create and remove StartupItems for daemon processes (e.g. web servers). The description will be added to the package as a file named %p/etc/daemons/name.xml, where name is specified by the DaemonicName field and defaults to the package name. Percent expansion is performed on the contents of this field. Note that you must add daemonic to the dependency list if your package uses it.

DaemonicName

A name for the daemonic service description file. See the description of DaemonicFile for details.

Additional Data:

FieldValue
Homepage

The URL of the upstream home page of the package.

DescDetail

A more detailed description than the one in the Description field (what is it, what can I use it for?). Multiple lines allowed. Because this field will be displayed without the benefit of word-wrap, you should manually insert line breaks in order to keep lines less than 79 chars (if possible).

DescUsage

This is for information that is needed to use the package (how do I use it?). As in "run wmaker.inst once before using WindowMaker". Multiple lines allowed. Because this field will be displayed without the benefit of word-wrap, you should manually insert line breaks in order to keep lines less than 79 chars (if possible).

DescPackaging

Notes about the packaging. Stuff like "patches the Makefile to put everything in place" goes here. Multiple lines allowed.

DescPort

Notes that are specific to porting the package to Darwin. Stuff like "config.guess and libtool scripts are updated, -no-cpp-precomp is necessary" goes here. Multiple lines allowed.

6.3 SplitOffs

Beginning with fink 0.9.9, a single .info file can be used to build multiple packages. The install phase begins as usual, with the execution of the InstallScript and DocFiles commands. A SplitOff or SplitOffN field, if present, then triggers the creation of an additional install directory. Within the SplitOff or SplitOffN field, the new install directory is referred to as %i, while the original install directory of the parent package is referred to as %I.

Each SplitOff and SplitOffN field must contain a number of fields of its own. In fact, it resembles a complete package description, but with certain fields missing. Here is what belongs in the sub-description (by category):

Because %n-%v-%r is treated as the unique identifier of a package, you must not have the same Package (at the same Version and Revision) listed as a SplitOff (or SplitOffN) of multiple packages. If you use variants, remember that each variant is considered an independent package, so the following package layout is forbidden:

Package: mime-base64-pm%type_pkg[perl]
Type: perl (5.12.3 5.12.4)
SplitOff: <<
  Package: mime-base64-pm-bin
<<

During the install phase, the InstallScript and DocFiles of the parent package are executed first. Next comes processing of the SplitOff and SplitOffN fields. For each such field in turn, the InstallScript of that field is run, and then the Files command causes the listed files and directories to be moved from the parent's installation directory %I to the current installation directory %i. Then the DocFiles and other Installation Phase fields of the given SplitOff or SplitOffN package are executed.

At this time, the SplitOff is processed first (if present), followed by each SplitOffN in numerical order by N. However, this may change in the future, so, for example, instead of:

SplitOff: <<
  Description: Some header files
  Files: include/foo.h include/bar.h
<<
SplitOff2: <<
  Description: All other header files
  Files: include/*
<<

which only works correctly if SplitOff is processed before SplitOff2 it's safer to list explicitly the files for each (or use more specific filename globs).

During the build phase, the pre/post install/remove scripts for each of the packages is constructed by using the build phase commands which were specified for that package.

Each package being built is required to document the licensing arrangement in %i/share/doc/%n (and of course %n takes a different value for each package). Note that DocFiles copies files rather than moving them, so it is possible to install identical copies of the documentation into each of the packages by using DocFiles several times.

6.4 Scripts

The PatchScript, CompileScript and InstallScript fields allow you to specify shell commands to be executed. The build directory (%b) is the current directory when scripts are executed. You should always use relative pathnames or percent-expansions for files and directories in the fink hierarchy, not complete absolute pathnames. Two forms are supported.

This field can be a simple list of commands. This is sort of like a shell script. However, the commands are executed via system(), one line at a time, so setting variables or changing the directory only affects commands on that same line. Starting in a CVS version of fink after 0.18.2, you can wrap long lines similar to normal shell scripts: a backslash (\) at the end of a line indicates that the next line is a continuation.

Alternately, you can embed a complete script here, using the interpreter of your choice. As with any Unix script, the first line must begin with #! followed by the full pathname of to the interpreter and any needed flags (e.g., #!/bin/csh, #!/bin/bash -ev, etc.). In this situation, the whole *Script field is dumped into a temporary file that is then executed.

6.5 Patches

If your package needs a patch to compile on Darwin (or to work with fink), name the patch with the same name as the package description, using the extension ".patch" instead of ".info" and put it in the same directory as the .info file. Specify the filename of the patchfile with a line such as:

PatchFile: %n.patch

(For packages with variants, it may be better to use %{ni}.patch .) You must also give the MD5 sum of the patchfile in the PatchFile-MD5 field, and specify BuildDepends: fink (>= 0.24.12) (or a later version of fink).

When a PatchFileN field is used, general custom is to name the file %n-purpose-of-patch.patch to make it easy to keep track of. You must also use the field PatchFileN-MD5 and specify BuildDepends: fink (>= 0.30.0) (or a later version of fink).

When a PatchFile declaration is present, there is a default PatchScript equivalent to:

PatchScript: patch -p1 < %{PatchFile}

Using PatchFileN appends the following to the default PatchScript above:

patch -p1 < %{PatchFileN}

This will be overridden if you supply a PatchScript of your own (for example, to perform a substitution on the patch file before applying it).

If you need to have the user's chosen prefix in the patch file it is recommended that you have a variable such as @PREFIX@ instead of /sw in the patch and then use:

PatchScript: sed 's|@PREFIX@|%p|g' < %{PatchFile} | patch -p1

Patches should be in unidiff format and are normally generated by using:

diff -urN <originalsourcedir> <patchedsourcedir>

If you have used emacs to edit files, you can add -x'*~' to the diff command above in order to exclude automatically-generated backup files.

It must also be noted that extremely large patches should not be put in cvs. They should be put on a web/ftp server and specified using the SourceN: field. If you don't have a website, fink project admins can make the file available from fink's own website. If your patch is larger than about 30Kb, you should consider making it a separate download.

6.6 Profile.d scripts

If your package needs some run-time initialization (e.g. to setup environment variables), you can use profile.d scripts. These script fragments are sourced by the /sw/bin/init.[c]sh scripts. Normally, all fink users will load these scripts in their shell startup files (.cshrc and comparable files). Your package must provide each script in two variants: one for sh compatible shells (sh, zsh, bash, ksh, ...) and one for csh compatible shells (csh, tcsh). They have to be installed as /sw/etc/profile.d/%n.[c]sh (where %n as usual stands for the package name). Also, their executable and read bits have to be set (i.e. install them with -m 755), otherwise they will not be loaded correctly.

If you just need to set some environment variables (for example, QTDIR to '/sw'), you can use the RuntimeVars field which is provided as a convenient way to achieve exactly this.


Copyright Notice

Copyright (c) 2001 Christoph Pfisterer, Copyright (c) 2001-2013 The Fink Project. You may distribute this document in print for private purposes, provided the document and this copyright notice remain complete and unmodified. Any commercial reproduction and any online publication requires the explicit consent of the author.


Generated from $Fink: packaging.en.xml,v 1.128 2014/02/14 18:22:26 nieder Exp $