Getting Started with the DKML Install API
The DKML Install API lets you take the tools you know (OCaml and Opam) and well-known¹ installer generators, to generate a installer for your OCaml project.
¹ Well-known is an aspiration. Currently only a simple CLI installer generator is available, but other well-known installer generators like 0install or cpack could be added in the future.
Specifically the DKML Install API lets you take a) pre-designed packages from Opam and b) installation instructions written in OCaml source code, and assembles binary artifacts that act as the primary materials to installer generators.
Why use it?
Often you start with the most basic installation logic: copy a directory of prebuilt binaries and other files into the installation directory. Later you realize you need to customize a configuration file, populate a database or compile assets at installation time. Now you have several options:
You generate the configuration/database/assets when your program is first run. You made a trade-off: instead of notifying your user of problems early, they don’t find out until the program is run for the first time. Sometimes that is a perfectly acceptable trade-off.
You follow your target platform’s recommendation; for example the Fedora Linux Packaging Guidelines suggest using the Lua interpreter embedded in the Fedora/RedHat
rpmpackage manager for any scripting needs. For other target platforms like Windows and non-RedHat based package managers, you modify your installer to first install the Lua interpreter. You made a trade-off: you need to write some of your core logic in a language like Lua which is likely unfamiliar to you or your OCaml application developers, and you may need to rewrite or duplicate some of your existing OCaml logic in Lua or whatever the target platform recommends.
You follow the widespread practice of using portable scripts. On Unix systems you write POSIX shell scripts that run with the Bourne shell available on almost all Unix machines. On Windows system you write PowerShell scripts which have been the basis of Windows package managers like Chocolatey.
By now you should see that you can rapidly accumulate technical debt when your installation logic gets complex quick. The original author of the DKML Install API followed option #3 when developing a Windows-friendly installer for OCaml. The installer worked well but other developers would have difficulty contributing to its Unix and Windows portable scripts.
As OCaml application developers, you already know how to embed complex logic in OCaml. With the DKML Install API you:
inform your users of setup problems early during installation rather than at runtime. That avoids the tradeoff for option #1
gain the ability to write your installation logic in a language you are already familiar with. That avoids the tradeoff for option #2 and #3
gain the ability to test units of your installation logic with your normal OCaml test infrastructure (Alcotest, ppx_expect, etc.)
but you will need to accept a learning curve for:
how to use this DKML Install API
how to write Opam packages that install artifacts to non-standard locations
- Getting Started with the DKML Install API
- Console Packager
- Component Authors
- Indices and tables