anil.recoil.org
The unpac monorepo manager self-hosting as a monorepo using unpac
Add alternative dune instructions
Close #250
authored by
Brian Ward
and committed by
Daniel Bünzli
2874f99c
f6345273
+4
CHANGES.md
+4
CHANGES.md
···
16
users don't have the cmdliner library installed (#243).
17
Thanks to Brian Ward for suggesting.
18
19
+
- Add alternative instructions to the cookbook for installing tool support
20
+
files with `dune` (#250).
21
+
Thanks to Brian Ward for the patch and research.
22
+
23
- Help output, improve graceful degration on groff or pager errors (#140).
24
Thanks to Sergey Fedorov for the report.
25
+56
-8
doc/cookbook.mld
+56
-8
doc/cookbook.mld
···
96
you have conventions that clash with [Cmdliner]'s ones but you need to
97
preserve backward compatibility, one way of proceeding is to
98
pre-process {!Sys.argv} into a new array of the right shape before
99
-
giving it to command {{!Cmdliner.Cmd.section-eval}evaluation
100
-
functions} via the [?argv] optional argument.
101
102
These are two common cases:
103
···
213
opam filter [{cmdliner:installed}] after the closing bracket of the command
214
invocation.
215
216
{3:tip_tool_support_with_opam_dune With [opam] and [dune]}
217
218
First make sure your understand the
219
{{!tip_tool_support_with_opam}above basic instructions} for [opam].
220
You then
221
-
{{:https://dune.readthedocs.io/en/stable/reference/packages.html#generating-opam-files}need to figure out} how to add the [cmdliner install] instruction to the [build:]
222
-
field of the opam file after your [dune] build instructions. For a tool named
223
-
[tool] the result should eventually look this:
224
225
{@sh[
226
build: [
227
-
[ … ] # Your regular dune build instructions
228
["cmdliner" "install" "tool-support"
229
"--update-opam-install=%{_:name}%.install"
230
-
"_build/install/default/bin/tool" {os-family != "windows"}
231
-
"_build/install/default/bin/tool.exe" {os-family = "windows"}
232
"_build/cmdliner-install"]]
233
]}
234
···
96
you have conventions that clash with [Cmdliner]'s ones but you need to
97
preserve backward compatibility, one way of proceeding is to
98
pre-process {!Sys.argv} into a new array of the right shape before
99
+
giving it to command {{!Cmdliner.Cmd.section-eval}evaluation functions}
100
+
via the [?argv] optional argument.
101
102
These are two common cases:
103
···
213
opam filter [{cmdliner:installed}] after the closing bracket of the command
214
invocation.
215
216
+
{3:top_tool_support_with_dune_install With [dune] [@install]}
217
+
218
+
Users of [dune] 3.5 or later can use the [cmdliner install
219
+
tool-support] command described above, along with the
220
+
{{:https://dune.readthedocs.io/en/stable/reference/dune/rule.html#directory-targets}
221
+
[directory-targets]}
222
+
feature and
223
+
{{:https://dune.readthedocs.io/en/latest/reference/dune/install.html}
224
+
[install]} stanza, to hook into the existing [dune build @install] command.
225
+
226
+
For an executable named [mytool] defined in a [dune] file, you can add
227
+
the following to the same [dune] file to populate the completion
228
+
scripts and manpages when running [dune build @install] (which is what
229
+
is used by [opam install]):
230
+
231
+
{@dune[
232
+
(rule
233
+
(target (dir cmdliner-support))
234
+
(deps mytool.exe)
235
+
(action
236
+
(ignore-stdout
237
+
(run cmdliner install tool-support ./mytool.exe:mytool cmdliner-support))))
238
+
239
+
(install
240
+
(section share_root)
241
+
(dirs (cmdliner-support/share as .)))
242
+
]}
243
+
244
+
If these features of dune are not available to your project, you may
245
+
instead need to update the [opam] file, see {{!tip_tool_support_with_opam_dune}
246
+
these instructions}.
247
+
248
{3:tip_tool_support_with_opam_dune With [opam] and [dune]}
249
250
First make sure your understand the
251
{{!tip_tool_support_with_opam}above basic instructions} for [opam].
252
You then
253
+
{{:https://dune.readthedocs.io/en/stable/reference/packages.html#generating-opam-files}
254
+
need to add a [.opam.template]} file which inserts the [cmdliner
255
+
install] instruction to the [build:] field of the opam file after your
256
+
[dune] build instructions. For a tool named [mytool] the
257
+
[mytool.opam.template] file should contain:
258
259
{@sh[
260
build: [
261
+
# These first two commands are what dune generates if you don't have
262
+
# a template
263
+
["dune" "subst"] {dev}
264
+
[
265
+
"dune"
266
+
"build"
267
+
"-p"
268
+
name
269
+
"-j"
270
+
jobs
271
+
"@install"
272
+
"@runtest" {with-test}
273
+
"@doc" {with-doc}
274
+
]
275
+
# This is the important command for cmdliner's files
276
["cmdliner" "install" "tool-support"
277
"--update-opam-install=%{_:name}%.install"
278
+
"_build/install/default/bin/mytool" {os-family != "windows"}
279
+
"_build/install/default/bin/mytool.exe" {os-family = "windows"}
280
"_build/cmdliner-install"]]
281
]}
282