Instructions to augment the `install:` field of the `opam` file of a `dune` project

Learning
,
1

Hello,

Could a charitable dune user help me in providing off-the-shelf instructions for installing the completion scripts and manpages of a cmdliner 2.0.0 based tool that uses dune for building.

Here is what the instructions look like if you were to write this directly in an opam file (example for an ocamlbuild-based build).

I want to provide a cookbook entry that has direct instructions for dune users.

Thanks.

2

Note, I’m also open to have that as direct build rules, if that remains short – despite what the advertisement says, dune is not a very composable build system :–)

3

OPAM files generated by Dune do not contain an install: field by default as .install files are used instead. However, you can inject arbitrary fields into the generated OPAM file by putting them in a file called $PKGNAME.opam.template at the root of the Dune project. So something like

# dune-project
(lang dune 3.18)
(package (name mypkg))
(generate_opam_files)

# mypkg.opam.template
install: [
  "cmdliner" "install" "tool-support"
  "--sharedir=%{share}%" "--mandir=%{man}%"
  "_build/install/default/bin/thetool" "%{prefix}%"
]

could be a starting point (here mypkg is the name of the package). Note that you need to write the path to the built tool by hand (here, _build/install/default/thetool). (Also, you may have some issues on Windows if cmdliner install tool-support does not handle the .exe extension automatically.)

I’m assuming here that OPAM is able to work with packages that have both an .install file and an install: field in their OPAM file.

Sorry I can’t give more precise instructions, but am not really an OPAM user. cc @Alizter or @maiste who may be able to give you more details.

Cheers,
Nicolas

1 Like
4

Wouldn’t that be _build/install/default/thetool.exe ?
Doesn’t dune always add an .exe extension ? That’s what the page here proudly says.

.exe extensions are taken into account.

5

Given that the tool itself is built with dune, it would be worth looking into dune-site and the builtin install capability. You’d need to turn your generating instructions from the opam file into a dune rule to let dune know how to generate the artifacts you want install. I think this would feel more “dune-like” to a dune user (opinions?).

If you have an example repo with a dune built app candidate, I’m happy to contribute to trying to find the right dune rule magic (re: off-the-shelf). Maybe using one actual useful app that uses dune & cmdliner as an example - like we can look into creating such PR for dune-release?

Caveat: I don’t know what the share or man and bin sections of the dune-sites mean when not using opam (e.g. dune-pkg). I haven’t tried this yet (maybe they’re just global instead of being tied to particular opam switch?)

I’m excited about the command completion feature. Thanks a lot for your work on this!

6

Dune uses an .exe extension uniformly when building executables in its build directory (eg _build/default). This simplifies writing rules that work uniformly on Windows and Linux.

However, when installing executables, Dune actually removes the .exe extension on Unix, to follow system conventions. In other words, you can work within the build system as if all the executables had .exe extensions, but when dealing with installation artifacts, .exe is only used on Windows.

To give a bit more detail: _build/default/thetool.exe refers to the artifact in the build directory, which is always suffixed with .exe. However, _build/install/default/bin/thetool (yes, there was a missing bin/ in my previous message), refers to the installation artifact (which is actually copied by OPAM), and so it does not have an .exe extension on Unix.

Hope that clarifies things.

Cheers,
Nicolas

1 Like
7

@mbarbin if you are able to find the magic I’m all for it. You can pin cmdliner to try things. However note that the cmdliner tool does not generate opam instructions in any way and it wouldn’t generate dune files either. If that is needed then I think it should be done in another project (but I’m willing to add more build-system agnostic modes in the cmdliner tool if that’s needed).

Meanwhile what @nojb proposes seems more tractable (to me). So if I understand well I can choose between peeking into the install directory or the build directory of dune.

I checked on a build of odoc that would be in the build dir (you then need to use the :NAME renaming syntax)

install: [
  "cmdliner" "install" "tool-support"
  "--sharedir=%{share}%" 
  "--mandir=%{man}%"
  "_build/default/src/odoc/bin/main.exe:odoc" 
  "%{prefix}%" ]

But I’m a bit nervous in suggesting that. Couldn’t dune decide to reshuffle its build directory structure from one version to another ?

While in the install directory it would rather be:

install: [
  "cmdliner" "install" "tool-support"
  "--sharedir=%{share}%" 
  "--mandir=%{man}%"
  "_build/default/install/bin/odoc"  "{os != "win32"}"
  "_build/default/install/bin/odoc.exe"  "{os = "win32"}"
  "%{prefix}%" ]

A bit more verbose but more stable ?

8

Yes, I would recommend going via the install directory, which is what OPAM does as well.

Cheers,
Nicolas

1 Like
9

Just FTR, I moved to do that in the build: section by writing the files in the build directory and updating (or creating) the pkg.install file.

This avoids to use the install: section which I’m being told may slow down builds on Windows as with these packages the install prefix needs to be diffed to see what gets installed (and in turn seems a bit buggy for running byte code at the moment).

The trade off is a hopefully not too brittle patching of the pkg.install file that your build system produces. AFAIU this also means that you will have to manually write your dune invocation in the build: field.

I settled down on these instructions. I’m a bit averse to add too much details that may change in the future. If there’s a better link on the dune docs than the one I provided, tell me.