OwenPriceSkelly
commented
2 years ago (leaving notes here in case we ever need to do this again in the future)
Whenever it automatically generates a .opam file, dune apparently will check for a .opam.template file whose contents it will just blindly copy over for us.
So by putting whatever we want to pin (and nothing else) in the template file, our prelude dependency / url gets propagated correctly through the dune-generated .opam file, and from there to the opam lock-generated .opam.locked file.
tldr: anything you wish was in attachment-converter.opam you should stick in attachment-converter.opam.template instead
Stateless Build Config, Part 1: Sandboxed Opam Switches
Once we're getting closer to releasing Attachment Converter, we'll want to offer some options to help developers build it on their system. One traditional approach to this is to write up a detailed document explaining how to install all the relevant developer tools, os dependencies, and library dependencies, then say a bunch of hail marys and hope to heck it'll work, which it certainly won't. The reason this never works is that when you get something to work on your system, it probably only happened because of a bunch of different system environment settings that you either forgot or didn't know you had turned on. On another random person's machine, most of those assumptions won't hold anymore, and if you didn't realize your installation instructions were making them, they are pretty much guaranteed not to work.
In ride stateless build environments. The goal of a stateless build environment is to write down, explicitly, every last little thing that is required to compile some code, from OS-level dependencies to programming language libraries; the whole nine yards. Because the stateless build environment isn't drawing on any information that isn't available in the local config, you have a guarantee that if it builds on your machine, it will also build on the machine of any other developer who has the same stateless build tool installed.
Opam-Lock
In 2022, there are a number of options for getting The Stateless Build Config Of Your Dreams off the ground. In future issues we'll look at Nix and possibly also Esy--but for this issue, we'll start with what ought to be the easiest one to get working: sandboxed
opamswitches.The basic idea is as follows. You create a special
opamswitch that is just for your project. (As opposed to a global switch; a global switch will typically have an exact OCaml compiler version for a name and contain pretty much everyopampackage you're planning to work with on your system.) You then set your build environment up the normal way, installing all packages you need until your project builds. Then you use a utility calledopam-lock—somewhat similar in concept topip freeze—to record information about whichopampackages are installed in that switch.Once you've created the opam lock file, another user can in the possession of it who has
opaminstalled canopamto create a brand new switch in the image of the lock file. Assuming there are no errors installing dependencies for your project, that other user should then be able to compile your project on their system, because they will have everything they need to do so in their new switch.Here is a guide that can hopefully get you started: https://khady.info/opam-sandbox.html
Attachment Converter
The goal for this issue is to perform the above steps for our project, create an opam lock file, and add it to our GitHub repository. You should be able to test it on your system, but for a more ambitious test you can choose another computer; maybe even the computer of someone who doesn't use OCaml!
The steps are, roughly:
duneto tell you what Attachment Converter'sopamdependencies areopam-lockutility to generate the lock file from your sandboxed switch