site-lib(5)

💖 site-lib(5) — File Formats Manual 💖

okay bestie, gather round, because this one is literally the blueprint for where all ur OCaml packages live. it's giving real estate agent for your filesystem. let's go ✨

---

🌸 NAME 🌸

site-lib — [Location of package directories] 🏠

---

🌈 STANDARD LAYOUT 🌈

the classic. the OG. the main character layout 🫶

...somewhere in the filesystem hierarchy...
   |
   \
     site-lib
     |
     +- (optional) stublibs
     +- (optional) postinstall
     +- (optional) postremove
     |
     +- package1
     |  |
     |  +- META
     |  +- archive files
     |  +- interface definitions
     |
     +- package2
     +
     :
     :
     \
        packageN

---

✨ DESCRIPTION ✨

so every single installation of "findlib" has a default location for package directories, and that location is normally a directory called site-lib. iconic name, no notes. 💅

where does it actually live? that's set by two configuration variables, bestie:

• path — used to look up packages 🔍
• destdir — used to install new packages 📦

see findlib.conf for the deets. iykyk.

---

🎀 package names 🎀

the name of a package is the name of the package directory. periodt. so like, if destdir=/usr/local/lib/ocaml/site-lib, then the package p gets installed into the subdirectory /usr/local/lib/ocaml/site-lib/p. that subdirectory has to contain the META file and all the other files that belong to the package. no strays, no crumbs. 🍓

⚠️ huge one: package names must not contain the . character. not even a little one. don't do it.

---

🦋 destdir (aka where the new stuff goes) 🦋

the variable destdir specifies the directory for new packages. u can only have one such directory at a time — one at a time, bestie, we're monogamous here 😭 — but ofc u can change this directory in findlib.conf. the command ocamlfind install puts new packages into this directory, and honestly it's recommended that u use this command for installation, because it ensures the directory layout is right. let the tool cook. 👑

---

🔍 path (aka where we go looking) 🔍

for searching packages, findlib uses (only) the variable path, which may name several locations to look at. that's it. that's the whole search party. 🕵️‍♀️

---

💀 stublibs (the DLL girlies) 💀

for systems with DLL support, another directory may exist: stublibs. if it's present, findlib will install DLLs into this directory, which is shared by all packages at the same site-lib location. communal DLL living, we love to see it 🫶

how does findlib know who owns what? special files with the suffix .owner. for example, for the DLL dllpcre.so there's another file dllpcre.so.owner containing the string pcre, so findlib knows that the package pcre owns this DLL. cute lil name tag 🏷️

⚠️ it is not possible that a DLL is owned by several packages. no shared custody. none.

and if the stublibs directory does not exist? then DLLs are installed regularly in the package directories like any other file. back to basics. 🌱

---

🧚 postinstall & postremove 🧚

for special needs, a postinstall and/or a postremove script may be installed in the site-lib directory. these scripts are invoked after installation or removal of a package, respectively. like a little goodbye/good-luck ritual 🕯️

---

🌟 ALTERNATE LAYOUT 🌟

yes there's a second layout. plot twist. 😲

...somewhere in the filesystem hierarchy...
   |
   \
     site-lib
     |
     +- (optional) stublibs
     +- (optional) postinstall
     +- (optional) postremove
     |
     +- package1
     |  |
     |  +- archive files
     |  +- interface definitions
     |
     +- package2
     +
     :
     :
     \
  :     packageN
  |
  \
    metaregistry
    |
    +- META.package1
    +- META.package2
    +
    :
    \
       META.packageN

so this is an alternate directory layout that collects all the META files in one directory. all of them. one big META party 🎉 it's giving centralised metadata, very organised of u.

u can configure this layout by setting path to the absolute location of metaregistry. findlib recognizes that there are META files in this directory and uses them — it is not necessary to include site-lib into the path. one less thing, slay. ✨

for it to actually work, the META files must contain a directory directive pointing to the corresponding package directory that resides below site-lib. don't forget it or it's giving lost in the filesystem 😭

---

👑 ocamlfind install & the alternate layout 👑

good news bestie: the command ocamlfind install copes with this layout too. 💪

here's the tea:

• the variable destdir must contain the absolute location of site-lib
• the variable metadir must contain the absolute location of metaregistry

and ngl the best part: ocamlfind install automatically adds a directory directive to the META file, so u need not do it manually. not me doing zero work and still winning 🥳

---

🌈 reminder: no matter which layout u pick, package names still can't have a . in them. that rule is forever. periodt.

---

mwah 💋 that's the whole page. now go forth and organise ur site-lib like the icon u are. 🎀✨

— from the User Manual of The findlib package manager for OCaml, this lil entry is site-lib(5). stay slay, bestie 💜🦋