fink.conf.5.in

.\" -*- nroff -*-
.Dd July 2014
.Dt FINK.CONF 5
.Sh NAME
.Nm fink.conf
.Nd configuration file for
.Xr fink 8
.Sh SYNOPSIS
@PREFIX@/etc/fink.conf
.\"
.\"
.\" DESCRIPTION
.\"
.\"
.Sh DESCRIPTION
When
.Xr fink 8
is initially installed it prompts you for the answers to some questions to set
up your configuration file, such as which mirrors you want to use for
downloading files and how to acquire super-user rights. You can re-run this
process by calling the
.Cm fink configure
command. In order to set some options, you may need to edit your
.Nm
by hand. In general, these options are meant for advanced users only.
.Pp
Your
.Nm
consists of multiple lines, in the format
.Bl -tag -width flag -offset indent -compact
.It OptionName: Value
.El
.Pp
Options are one per line, and the option name is separated from its value by a :
and a single space. The contents of value depends on the option, but it is
normally either a boolean ("True" or "False"), a string, or a list of strings
delimited by a space.
For example:
.Bl -tag -width flag -offset indent -compact
.It BooleanOption: True
.It StringOption: Something
.It ListOption: Option1 Option2 Option3
.El
.\"
.\"
.\" REQUIRED SETTINGS
.\"
.\"
.Sh REQUIRED SETTINGS
Some of the settings in
.Nm
are mandatory. Without them
.Nm fink
cannot
function properly. The following settings belong to this category.
.Bl -tag -width flag
.It Cm Basepath: Ar path
Tells
.Nm fink
where it was installed. You should not change this value after installation,
it will confuse
.Nm fink.
.El
.\"
.\"
.\" OPTIONAL USER SETTINGS
.\"
.\"
.Sh OPTIONAL USER SETTINGS
There are various optional settings which users can customize to change the
behaviour of
.Nm fink.
.Bl -tag -width flag
.It Cm RootMethod: Ar su or sudo or none
For some operations,
.Nm fink
needs super user rights. Recognized values are
.Nm sudo
or
.Nm su.
You can also set this to
.Nm none,
in which case you must run
.Nm fink
as root yourself. The default value is
.Nm sudo
and in most cases it should not be changed.
.It Cm Trees: Ar list of trees
Available trees are:
.Bl -tag -width flag -offset indent -compact
.It local/main      - any local packages you want to install
.It local/bootstrap - packages used in the installation of fink
.It stable/main     - stable packages from fink
.It unstable/main   - unstable packages from fink
.El
You may also add your own trees in the
.Pa @PREFIX@/fink/dists
directory for your own purposes,
but this is not necessary in most circumstances. The default trees are
"local/main local/bootstrap stable/main". This list should be kept in sync with
.Pa @PREFIX@/etc/apt/sources.list.
.Pp
The order of trees is meaningful, as packages from later trees may override
packages from earlier ones.
.It Cm Distribution: Ar 10.7, 10.8, 10.9, or 10.10.
.Nm fink
needs to know which version of Mac OS X you are running. Mac OS X versions up to 10.6 are no longer supported by this version of
.Nm fink.
This field is set by running the
.Cm @PREFIX@/lib/fink/postinstall.pl
script. You should not need to alter this value manually.
.It Cm FetchAltDir: Ar path
Usually
.Nm fink
will store the sources it fetches in
.Pa @PREFIX@/src.
Using this option, you can specify an (absolute) alternate directory in which
.Nm fink
should look for downloaded source code. For example:
.Bl -tag -width flag -offset indent -compact
.It FetchAltDir: /usr/src
.El
.It Cm Verbose: Ar a number from 0 to 3
This option sets how much information
.Nm fink
tells you about what it is doing. The
values are:
.Bl -tag -width flag -offset indent -compact
.It 0 - Quiet (don't show download stats)
.It 1 - Low (don't show tarballs being expanded)
.It 2 - Medium (show almost everything)
.It 3 - High (show everything)
.El
The default value is 1.
.It Cm SkipPrompts: Ar a comma-delimited list
This option instructs
.Nm fink
to refrain from asking for input when the user does
not want to be prompted. Each prompt belongs to a category. If a prompt's
category is in the SkipPrompts list then the default option will be chosen
within a very short period of time.
.Pp
Currently, the following categories of prompts exist:
.Bl -tag -width flag -offset indent -compact
.It fetch - Downloads and mirrors
.It virtualdep - Choosing between alternative packages
.El
By default, no prompts are skipped.
.It Cm OldIndexes: Ar ignore, update or warn
When installing packages,
.Nm fink
will check if your package index is over 2 weeks
old.  If it is, you can have
.Nm fink
automatically warn you, or even download
updates for you.
The default value is "warn".
.It Cm NoAutoIndex: Ar boolean
.Nm fink
caches its package descripition files to save it having to read
and parse them all every time it runs.
.Nm fink
checks whether or not the package
index needs to be updated unless this option is set to "True". It defaults to
"False" and it is not recommended that you change it.
If you do, you may need to manually run the
.Nm fink index
command to update the index.
.It Cm SelfUpdateNoCVS: Ar boolean
The command
.Cm fink selfupdate
upgrades the
.Nm fink
package manager to the latest release.
This option makes sure that the Concurrent Version System (CVS) is not used to
achieve this when set to True. It is set automatically by the
.Cm fink selfupdate-cvs
command, so you should not need to change it manually.
.It Cm Buildpath: Ar path
.Nm fink
needs to create several temporary directories for each package it compiles from source. They are placed in
.Pa @PREFIX@/src/fink.build
by default. If you want them to be somewhere else, specify the (absolute) path here.
See the descriptions of the
.Cm KeepRootDir
and
.Cm KeepBuildDir
fields later in this document for more information about these temporary directories.
.Pp
It is recommended that the Buildpath end with .noindex or .build.
Otherwise, Spotlight will attempt to index the temporary files in the
Buildpath, slowing down builds.
.It Cm Bzip2Path: Ar the path to your bzip2 (or compatible) binary
The Bzip2Path option lets you override the default path for the bzip2 command-line
tool.  This allows you to specify an alternate location to your bzip2 executable,
pass optional command-line options, or use a drop-in replacement like pbzip2 for
decompressing .bz2 archives.
.It Cm MaxBuildJobs: Ar positive integer
This option specifies how many concurrent build jobs should be spawned when
building a package that has parallel build jobs enabled. Building in parallel
speeds up the build process on multi-CPU or multi-core systems. Technically
speaking,
.Nm fink
uses the value of this option in MAKEFLAGS=-j. Running
.Cm fink configure
will tell you how many active CPUs/cores are available on your system.
.It Cm AutoUid: Ar boolean
This option specifies whether fink should dynamically allocate the UID and GID
of its unprivileged fink-bld user if that user is absent.
.It Cm FinkBldUid: Ar positive integer
This item specifies the current UID for the fink-bld user. The new setting will 
take effect when you run a fink operation that can
build a package, such as 
.Cm selfupdate,
.Cm build,
.Cm rebuild,
or
.Cm install.
.It Cm AutoUidMin: Ar positive integer
Minimum value for the pool of values from which fink will attempt to find an
unused UID or GID automatically if
.Cm AutoUid: true 
is set.
.It Cm AutoUidMax: Ar positive integer
Maximum value for the pool of values from from which fink will attempt to find an
unused UID or GID automatically if
.Cm AutoUid: true 
is set.
.El
.\"
.\"
.\" DOWNLOAD SETTINGS
.\"
.\"
.Sh DOWNLOAD SETTINGS
There are various settings which influence the way
.Nm fink
downloads package data.
.Bl -tag -width flag
.It Cm ProxyPassiveFTP: Ar boolean
This option makes
.Nm fink
use "passive" mode for FTP downloads. Some FTP server or
network configurations require this option to be set to True. It is recommended
that you leave this option on at all times since active FTP is deprecated.
.It Cm ProxyFTP: Ar url
If you use a FTP proxy then you should enter its address here, for example:
.Bl -tag -width flag -offset indent -compact
.It ProxyFTP: ftp://yourhost.com:2121/
.El
Leave if blank if you do not use a FTP proxy.
.It Cm ProxyHTTP: Ar url
If you use a HTTP proxy then you should enter its address here, for example:
.Bl -tag -width flag -offset indent -compact
.It ProxyHTTP: http://yourhost.com:3128/
.El
Leave if blank if you do not use a HTTP proxy.
.It Cm DownloadMethod: Ar wget or curl or axel or axelautomirror or aria2
.Nm fink
can use four different applications to download files from the Internet -
.Nm wget,
.Nm curl,
.Nm axel,
or
.Nm aria2.
The value
.Nm axelautomirror
uses an experimental mode of the
.Xr axel 1
application which tries to determine the closest server that has a certain file.
The use of axelautomirror is not recommended at this time. The default value is
.Nm curl.
The application you chose as DownloadMethod MUST be installed!
.It Cm SelfUpdateMethod: Ar point, rsync or cvs
.Xr fink 8
can use some different methods to update the package info files.
.Nm rsync
is the recommended setting, it uses
.Xr rsync 1
to download only modified files in the trees that you have enabled. Note that if you have changed or added to files in the stable or unstable trees, using rsync will delete them. Make a backup first.
.Nm cvs
will download using anonymous or :ext:
.Xr cvs 1
access from the Fink repository. This has the disadvantage that cvs can not switch mirrors, if the server is unavailable you will not be able to update.
.Nm point
will download only the latest released version of the packages. It is not recommended as your packages may be quite out of date.
.It Cm SelfUpdateTrees: Ar space separated list of trees
By default, the selfupdate methods will update only the current
distribution's tree.  This option overrides the list of distribution
versions that will be updated during a selfupdate.
.Pp
Please note that you will need a recent "cvs" binary installed if you
wish to include directories that do not have CVS/ directories in their
entire path (e.g.,
.Nm dists/local/main
or similar).
.It Cm UseBinaryDist: Ar boolean
Causes
.Nm fink
to try to download pre-compiled binary packages from the binary
distribution if available and if deb is not already on the system.
Passing
.Nm fink
the
.Cm -b
flag has the same effect, but only operates on that single
.Nm fink
invocation.  Passing
.Nm fink
the
.Cm --no-use-binary-dist
flag overrides this, and compiles from source for that single
.Nm fink
invocation.
.Pp
Note that this mode instructs
.Nm fink
to download the version it wants if
that version is available for download; it does not cause
.Nm fink
to
choose a version based on its binary availability.
.El
.\"
.\"
.\" MIRROR SETTINGS
.\"
.\"
.Sh MIRROR SETTINGS
Getting software from the Internet can be a tedious thing and often
downloads are
not as fast as we would like them to be. Mirror servers host copies of files
available on other servers, but may have a faster connection to the Internet or
be geographically closer to you, thus enabling you to download files faster.
They also help reduce load on busy primary servers, for example ftp.gnu.org, and
they provide an alternative should one
server not be reachable.
.Pp
In order for
.Nm fink
to pick the best mirror for you, you must tell it which
continent and which country you reside in. If downloads from one server fail, it
will prompt you if you want to retry from the same mirror, a different mirror in
the same country or continent, or a different mirror anywhere in the world.
.Pp
.Nm
holds settings about which mirrors you would like to use.
.Bl -tag -width flag
.It Cm MirrorContinent: Ar three letter code
You should change this value using the
.Cm fink configure
command. The three letter code is one found in
.Pa @PREFIX@/lib/fink/mirror/_keys.
For example, if you live in europe:
.Bl -tag -width flag -offset indent -compact
.It MirrorContinent: eur
.El
.It Cm MirrorCountry: Ar six letter code
You should change this value using the
.Cm fink configure
command. The three letter code is one found in
.Pa @PREFIX@/lib/fink/mirror/_keys.
For example, if you live in Austria:
.Bl -tag -width flag -offset indent -compact
.It MirrorCountry: eur-AT
.El
.It Cm MirrorOrder: Ar MasterFirst or MasterLast or MasterNever or ClosestFirst
.Nm fink
supports 'Master' mirrors, which are mirrored repositories of the source
tarballs for all Fink packages. The advantage of using the Master mirror set is that
the source download URLs will never break. Users can choose to use
these mirrors which are maintained by the Fink team, or to use only the original
source URLs and external mirror sites such as the gnome, KDE, and debian mirror sites.
Additionally users can choose to combine the two sets, which are then searched in proximity order, as
documented above. When using the MasterFirst or MasterLast options, the user can 'skip ahead'
to the Master (or non Master) set if a download fails. The options are:
.Bl -tag -width flag -offset indent -compact
.It MasterFirst - Search "Master" source mirrors first.
.It MasterLast - Search "Master" source mirrors last.
.It MasterNever - Never use "Master" source mirrors.
.It ClosestFirst - Search closest source mirrors first (combine all mirrors into one set).
.El
.It Cm Mirror-rsync:
When doing 'selfupdate' with the SelfupdateMethod set to rsync, this is the rsync url to sync from.
This should be an anonymous rsync url, pointing to a directory which contains all the Fink distributions and trees.
.El
.\"
.\"
.\" DEVELOPER SETTINGS
.\"
.\"
.Sh DEVELOPER SETTINGS
Some options in
.Nm
are only useful to developers. We do not recommend that conventional Fink users modify them. The following options
fall into this category.
.Bl -tag -width flag
.It Cm KeepRootDir: Ar boolean
Causes
.Nm fink
not to delete the temporary installation directory
.Pa root-[name]-[version]-[revision]
in the
.Cm Buildpath
after building a package. Defaults to false.
Be careful, this option can fill your hard-disk quickly!
Passing
.Nm fink
the
.Cm -K
flag has the same effect, but only operates on that single
.Nm fink
invocation.
.It Cm KeepBuildDir: Ar boolean
Causes
.Nm fink
not to delete the package compile directory
.Pa [name]-[version]-[revision]
in the
.Cm Buildpath
after building a package. Defaults to false.
Be careful, this option can fill your hard-disk quickly!
Passing
.Nm fink
the
.Cm -k
flag has the same effect, but only operates on that single
.Nm fink
invocation.
.El
.\"
.\"
.\" ADVANCED SETTINGS
.\"
.\"
.Sh ADVANCED SETTINGS
There are some other options which may be useful, but require some knowledge to get right.
.Bl -tag -width flag
.It Cm MatchPackageRegEx: Ar regex
Causes
.Nm fink
not to ask which package to install if one (and only one) of the choices matches
the perl Regular Expression given here.
Example:
.Bl -tag -width flag -offset indent -compact
.It MatchPackageRegEx: (.*-ssl$|^xfree86$|^xfree86-shlibs$)
.El
will match packages ending in '-ssl', and will match 'xfree86' and 'xfree86-shlibs' exactly.
.It Cm CCacheDir: Ar path
If the Fink package ccache-default is installed, the cache files it makes
while building Fink packages will be placed here. Defaults to
.Pa @PREFIX@/var/ccache.
If set to
.Nm none,
.Nm fink
will not set the
.Ev CCACHE_DIR
environment variable and ccache will use
.Pa $HOME/.ccache,
potentially putting root-owned files into your home directory.
.It Cm NotifyPlugin: Ar plugin
Specify a space-separated list of notification plugins, to tell you when packages have been installed/uninstalled.
Defaults to
.Pa Growl
(requires Mac::Growl to operate).  The available plugins are listed in the output of
"fink plugins".
.nf
See the wiki at https://github.com/fink/fink/wiki/Notification-plugins
for more information.
.fi
.It Cm AutoScanpackages: Ar boolean
When
.Nm fink
builds new packages,
.Xr apt-get 8
does not yet know about them.
Historically, the command
.Cm fink scanpackages
had to be run for apt-get to notice the new packages, but now this happens
automatically. If this option is present and false, then
.Cm fink scanpackages
will no longer be run automatically after packages are built.
.It Cm ScanRestrictivePackages: Ar boolean
When scanning the packages for
.Xr apt-get 8 ,
.Nm fink
normally scans all packages in the current trees. However, if the resuting
apt repository will be made publically available, the administrator may be
legally obligated not to include packages with
.Nm Restrictive
or
.Nm Commercial
licenses. If this option is present and false, then
.Nm fink
will omit those
packages when scanning.
.It Cm GitPath: Ar the path to your git binary
The GitPath option lets you override the default path for the git command-line
tool used by the selfupdate-git command. It is set automatically when
you first use the selfupdate-git but can be overridden if you wish to specify
an alternate location to your git executable.
.It Cm SvnPath: Ar the path to your svn binary
The SvnPath option lets you override the default path for the svn command-line
tool used by the selfupdate-svn command. It is set automatically when
you first use the selfupdate-svn but can be overridden if you wish to specify
an alternate location to your svn executable.
.El
.\"
.\"
.\" AUTHOR
.\"
.\"
.Sh AUTHOR
This manpage is maintained by the Fink Core Group <fink-core@lists.sourceforge.net>.
.\"
.\"
.\" ACKNOWLEDGEMENTS
.\"
.\"
.Sh ACKNOWLEDGEMENTS
.Nm fink
is developed and maintained by The Fink Project (http://www.finkproject.org).
.\"
.\"
.\" SEE ALSO
.\"
.\"
.Sh "SEE ALSO"
.Xr apt-get 8 ,
.Xr fink 8