findlib.conf(5)

💖 findlib.conf(5) 💖

okay bestie, welcome to the findlib.conf page — it lives in the File Formats Manual section of the manual, and it's literally the glow-up guide for how findlib/ocamlfind gets configured. pull up a chair, grab a boba, we're doing this 🧋✨

---

🎀 NAME 🎀

findlib.conf — [Configuration of findlib/ocamlfind]

---

🌈 GENERAL 🌈

so there are three whole ways to configure the findlib library, and honestly? pick your fighter:

🛠️ Build time

before findlib is even compiled, a configure script gets invoked to figure out the settings that are most likely to work on your system. most settings just get written into text files and you can change them after installation, no biggie. BUT — and this is the part where you lock in 🔒 — the following properties cannot be changed later, because they're compiled straight into the resulting binaries:

• the default location of the configuration file findlib.conf. however, you can set a different location by the environment variable OCAMLFIND_CONF.
• whether the installed OCaml version supports autolinking or not.

📄 Configuration file findlib.conf

an initial version of this file is generated by the configure script, but you are absolutely free to modify it later. most important, this file contains the system-wide search path used to look up packages, and the default location where to install new packages.

also! all files with the suffix .conf found in the directory findlib.conf.d are also scanned for parameters. sneaky little bonus config, we love her 🦋

🌱 Environment variables

the settings of findlib.conf can be overridden by environment variables. yes, they really can just do that.

last but not least, several settings can also be passed as command-line options, or by invoking the function Findlib.init. so many doors, so many keys 🔑

---

✨ findlib.conf ✨

the directory containing findlib.conf is determined at build time (by running the configure script), and the fallback default is /usr/local/etc. you can set a different location by changing the environment variable OCAMLFIND_CONF, which must contain the absolute path of findlib.conf.

the file has the same syntax as META, i.e. it consists of a number of lines with the format

variable = "value"

here is the list of allowed variables — yes, all of them, we're not skipping a single one 💅

🌸 path

the search path for META files/package directories. this variable enumerates directories which are separated by colons (Windows: semicolons), and these directories are tried in turn to find a certain package.

more exactly, if d is such a directory and p the searched package, the search algorithm will first check whether d/p/META exists. in this case, this META file is taken, and d/p is the package directory. second, the algorithm tries d/META.p, but the package directory must be specified in this META.p file by a directory directive.

note that the first found META file is taken, so the order of the directories in the search path counts. order matters, bestie, it's giving ranked choice voting 🗳️

this variable is required.

example:

path = "/usr/local/lib/ocaml/site-lib:/usr/lib/ocaml/site-lib"

🌸 destdir

this variable determines the location where ocamlfind install puts the packages by default: if d is this directory, and p the package to install, a new subdirectory d/p will be created containing all the files of the package.

example:

destdir = "/usr/local/lib/ocaml/site-lib"

this variable is required.

🌸 metadir

if set, the command ocamlfind install will put the META files of packages into this directory (files are named META.p where p=package name); otherwise the META files are put into the package directories like any other file.

example:

metadir = "/var/lib/findlib/metaregistry"

this variable is optional. it is not used by default.

🌸 ocamlc, ocamlopt, ocamlcp, ocamlmktop, ocamldoc, ocamldep, ocamlbrowser

if you want to call other executables than "ocamlc", "ocamlopt", "ocamlcp", "ocamlmktop", "ocamldoc", "ocamldep", and "ocamlbrowser", you can set the names of the executables here. the command ocamlfind looks into these four variables to determine the names of the compilers to call.

example:

ocamlc     = "ocamlc.opt"
ocamlopt   = "ocamlopt.opt"
ocamlcp    = "ocamlcp.opt"
ocamlmktop = "ocamlmktop.opt"

this variable is optional. it is not used by default.

🌸 stdlib

this variable determines the location of the standard library. this must be the same directory for which the OCaml compilers are configured.

this variable is optional. it is not recommend to set this variable unless you know what you are doing!

🚨 bestie listen — if you don't know what you're doing, don't touch it. i'm serious. put the variable down. 🙈

🌸 ldconf

this variable determines the location of the ld.conf file. this must be the same file the OCaml compilers read in; it is updated by ocamlfind when installing and removing packages. you can set this variable to the special value "ignore" to disable the automatic modification of the ld.conf file.

if not set, the ld.conf file is assumed to reside in the OCaml standard library directory.

this variable is optional. it is not recommended to set this variable unless you know what you are doing!

⚠️ same energy as above, fr fr. only if you know what you're doing.

🧚 Toolchains

it is possible to have variants of the original configuration. these variants are called "toolchains" because they are intended to select different compilers, e.g. patched compilers. in order to set a variable for a certain toolchain, use the syntax

variable(toolchain) = "value"

for example:

ocamlc(mypatch) = "ocamlc-mypatch"

when the toolchain "mypatch" is selected, this compiler will be used instead of the standard one. cute, right? 🎀

in order to switch to a certain toolchain, use the -toolchain option of ocamlfind.

---

🦋 Environment 🦋

a number of environment variables modifies the behaviour of findlib/ocamlfind:

💜 OCAMLFIND_CONF

this variable overrides the location of the configuration file findlib.conf. it must contain the absolute path name of this file.

💜 OCAMLFIND_TOOLCHAIN

this variable sets the currently selected toolchain when a -toolchain option is not passed on the command line.

💜 OCAMLPATH

this variable may contain an additional search path for package directories. it is treated as if the directories were prepended to the configuration variable path.

💜 OCAMLFIND_DESTDIR

this variable overrides the configuration variable destdir.

💜 OCAMLFIND_METADIR

this variable overrides the configuration variable metadir.

💜 OCAMLFIND_COMMANDS

this variable overrides the configuration variables ocamlc, ocamlopt, ocamlcp, ocamlmktop, ocamldoc, ocamldep, and/or ocamlbrowser. its value must conform to the syntax

ocamlc=name ocamlopt=name ocamlcp=name ocamlmktop=name ocamldoc=name ocamldep=name ocamlbrowser=name

example:

ocamlc=ocamlc-3.00 ocamlopt=ocamlopt-3.00 ocamlcp=ocamlcp-3.00 ocamlmktop=ocamlmktop-3.00

💜 CAMLLIB or OCAMLLIB

this variable overrides the configuration variable stdlib.

💜 OCAMLFIND_LDCONF

this variable overrides the configuration variable ldconf.

💜 OCAMLFIND_IGNORE_DUPS_IN

this variable instructs findlib not to emit warnings that packages or module occur several times. the variable must be set to the directory where the packages reside that are to be ignored for this warning.

---

and that's the whole page, bestie!! you ate that 🍽️✨

💖 this was the User Manual version of the findlib package manager for OCaml docs — that's findlib.conf(5), slay — and yeah, that's the whole vibe check. go forth and configure, main character 💅👑🌸