1OPAM-LOCK(1)                      Opam Manual                     OPAM-LOCK(1)
2
3
4

NAME

6       opam-lock - Create locked opam files to share build environments across
7       hosts.
8

SYNOPSIS

10       opam lock [OPTION]... [PACKAGES]...
11

DESCRIPTION

13       Generates a lock file of a package: checks the current state of their
14       installed dependencies, and outputs modified versions of the opam file
15       with a .locked suffix, where all the (transitive) dependencies and
16       pinnings have been bound strictly to the currently installed version.
17
18       By using these locked opam files, it is then possible to recover the
19       precise build environment that was setup when they were generated.
20
21       If paths (filename or directory) are given, those opam files are
22       locked. If package is given, installed one is locked, otherwise its
23       latest version. If a locally pinned package is given, its current local
24       opam file is locked, even if not versioned or uncommitted changes
25
26       Fails if all mandatory dependencies are not installed in the switch.
27

LOCK FILE CHANGED FIELDS

29       - depends are fixed to their specific versions, with all filters
30       removed (except for the exceptions below
31
32       - depopts that are installed in the current switch are turned into
33       depends, with their version set. Others are set in the conflict field
34
35       - `{dev}`, `{with-test}, and `{with-doc}` filters are kept if all
36       packages of a specific filters are installed in the switch. Versions
37       are fixed and the same filter is on all dependencies that are added
38       from them
39
40       - pin-depends are kept and new ones are added if in the dependencies
41       some packages are pinned
42
43       - pins are resolved: if a package is locally pinned, opam tries to get
44       its remote url and branch, and sets this as the target URL
45

ARGUMENTS

47       PACKAGES
48           List of package names, with an optional version or constraint, e.g
49           `pkg', `pkg.1.0' or `pkg>=0.5' ; or files or directory names
50           containing package description, with explicit directory (e.g.
51           `./foo.opam' or `.')
52

OPTIONS

54       -d, --direct-only
55           Only lock direct dependencies, rather than the whole dependency
56           tree.
57
58       --lock-suffix=SUFFIX (absent=locked)
59           Set locked files suffix to SUFFIX.
60
61       --no
62           Answer no to all opam yes/no questions without prompting. See also
63           --confirm-level. This is equivalent to setting $OPAMNO to "true".
64
65       -y, --yes
66           Answer yes to all opam yes/no questions without prompting. See also
67           --confirm-level. This is equivalent to setting $OPAMYES to "true".
68

COMMON OPTIONS

70       These options are common to all commands.
71
72       --best-effort
73           Don't fail if all requested packages can't be installed: try to
74           install as many as possible. Note that not all external solvers may
75           support this option (recent versions of aspcud or mccs should).
76           This is equivalent to setting $OPAMBESTEFFORT environment variable.
77
78       --cli=MAJOR.MINOR (absent=2.1)
79           Use the command-line interface syntax and semantics of MAJOR.MINOR.
80           Intended for any persistent use of opam (scripts, blog posts,
81           etc.), any version of opam in the same MAJOR series will behave as
82           for the specified MINOR release. The flag was not available in opam
83           2.0, so to select the 2.0 CLI, set the OPAMCLI environment variable
84           to 2.0 instead of using this parameter.
85
86       --color=WHEN
87           Colorize the output. WHEN must be one of `always', `never' or
88           `auto'.
89
90       --confirm-level=LEVEL
91           Confirmation level, LEVEL must be one of `ask', `no', `yes' or
92           `unsafe-yes'. Can be specified more than once. If --yes or --no are
93           also given, the value of the last --confirm-level is taken into
94           account. This is equivalent to setting  $OPAMCONFIRMLEVEL`.
95
96       --criteria=CRITERIA
97           Specify user preferences for dependency solving for this run.
98           Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
99           on the supported language, and the external solvers available, see
100           http://opam.ocaml.org/doc/External_solvers.html. A general guide to
101           using solver preferences can be found at
102           http://www.dicosmo.org/Articles/usercriteria.pdf.
103
104       --cudf=FILENAME
105           Debug option: Save the CUDF requests sent to the solver to
106           FILENAME-<n>.cudf.
107
108       --debug
109           Print debug message to stderr. This is equivalent to setting
110           $OPAMDEBUG to "true".
111
112       --debug-level=LEVEL
113           Like --debug, but allows specifying the debug level (--debug sets
114           it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
115
116       --git-version
117           Print the git version of opam, if set (i.e. you are using a
118           development version), and exit.
119
120       --help[=FMT] (default=auto)
121           Show this help in format FMT. The value FMT must be one of `auto',
122           `pager', `groff' or `plain'. With `auto', the format is `pager` or
123           `plain' whenever the TERM env var is `dumb' or undefined.
124
125       --ignore-pin-depends
126           Ignore extra pins required by packages that get pinned, either
127           manually through opam pin or through opam install DIR. This is
128           equivalent to setting IGNOREPINDEPENDS=true.
129
130       --json=FILENAME
131           Save the results of the opam run in a computer-readable file. If
132           the filename contains the character `%', it will be replaced by an
133           index that doesn't overwrite an existing file. Similar to setting
134           the $OPAMJSON variable.
135
136       --no-aspcud
137           Removed in 2.1.
138
139       --no-auto-upgrade
140           When configuring or updating a repository that is written for an
141           earlier opam version (1.2), opam internally converts it to the
142           current format. This disables this behaviour. Note that
143           repositories should define their format version in a 'repo' file at
144           their root, or they will be assumed to be in the older format. It
145           is, in any case, preferable to upgrade the repositories manually
146           using opam admin upgrade [--mirror URL] when possible.
147
148       --no-self-upgrade
149           Opam will replace itself with a newer binary found at OPAMROOT/opam
150           if present. This disables this behaviour.
151
152       -q, --quiet
153           Disables --verbose.
154
155       --root=ROOT
156           Use ROOT as the current root path. This is equivalent to setting
157           $OPAMROOT to ROOT.
158
159       --safe, --readonly
160           Make sure nothing will be automatically updated or rewritten.
161           Useful for calling from completion scripts, for example. Will fail
162           whenever such an operation is needed ; also avoids waiting for
163           locks, skips interactive questions and overrides the $OPAMDEBUG
164           variable. This is equivalent to set environment variable $OPAMSAFE.
165
166       --solver=CMD
167           Specify the CUDF solver to use for resolving package installation
168           problems. This is either a predefined solver (this version of opam
169           supports builtin-mccs+lp(), builtin-mccs+glpk,
170           builtin-dummy-z3-solver, builtin-dummy-0install-solver, aspcud,
171           mccs, aspcud-old, packup), or a custom command that should contain
172           the variables %{input}%, %{output}%, %{criteria}%, and optionally
173           %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
174
175       --strict
176           Fail whenever an error is found in a package definition or a
177           configuration file. The default is to continue silently if
178           possible.
179
180       --switch=SWITCH
181           Use SWITCH as the current compiler switch. This is equivalent to
182           setting $OPAMSWITCH to SWITCH.
183
184       --use-internal-solver
185           Disable any external solver, and use the built-in one (this
186           requires that opam has been compiled with a built-in solver). This
187           is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
188
189       -v, --verbose
190           Be more verbose. One -v shows all package commands, repeat to also
191           display commands called internally (e.g. tar, curl, patch etc.)
192           Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
193
194       --version
195           Show version information.
196
197       -w, --working-dir
198           Whenever updating packages that are bound to a local,
199           version-controlled directory, update to the current working state
200           of their source instead of the last committed state, or the ref
201           they are pointing to. As source directory is copied as it is, if it
202           isn't clean it may result on a opam build failure.This only affects
203           packages explicitly listed on the command-line.It can also be set
204           with $OPAMWORKINGDIR.
205

ENVIRONMENT

207       Opam makes use of the environment variables listed here. Boolean
208       variables should be set to "0", "no", "false" or the empty string to
209       disable, "1", "yes" or "true" to enable.
210
211       OPAMALLPARENS surround all filters with parenthesis.
212
213       OPAMASSUMEDEPEXTS see option `--assume-depexts'.
214
215       OPAMAUTOREMOVE see remove option `--auto-remove'.
216
217       OPAMBESTEFFORT see option `--best-effort'.
218
219       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
220       the criteria when the `--best-effort' option is set, and is expected to
221       maximise the `opam-query' property in the solution.
222
223       OPAMBUILDDOC Removed in 2.1.
224
225       OPAMBUILDTEST Removed in 2.1.
226
227       OPAMCLI see option `--cli'.
228
229       OPAMCOLOR when set to always or never, sets a default value for the
230       `--color' option.
231
232       OPAMCONFIRMLEVEL see option `--confirm-level`. OPAMCONFIRMLEVEL has
233       priority over OPAMYES and OPAMNO.
234
235       OPAMCRITERIA specifies user preferences for dependency solving. The
236       default value depends on the solver version, use `config report' to
237       know the current setting. See also option --criteria.
238
239       OPAMCUDFFILE save the cudf graph to file-actions-explicit.dot.
240
241       OPAMCUDFTRIM controls the filtering of unrelated packages during CUDF
242       preprocessing.
243
244       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
245       for more options.
246
247       OPAMDEBUG see options `--debug' and `--debug-level'.
248
249       OPAMDEBUGSECTIONS if set, limits debug messages to the space-separated
250       list of sections. Sections can optionally have a specific debug level
251       (for example, CLIENT:2 or CLIENT CUDF:2), but otherwise use
252       `--debug-level'.
253
254       OPAMDIGDEPTH defines how aggressive the lookup for conflicts during
255       CUDF preprocessing is.
256
257       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
258
259       OPAMDROPWORKINGDIR overrides packages previously updated with
260       --working-dir on update. Without this variable set, opam would keep
261       them unchanged unless explicitly named on the command-line.
262
263       OPAMDRYRUN see option `--dry-run'.
264
265       OPAMEDITOR sets the editor to use for opam file editing, overrides
266       $EDITOR and $VISUAL.
267
268       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
269       fails. 0 to print all.
270
271       OPAMEXTERNALSOLVER see option `--solver'.
272
273       OPAMFAKE see option `--fake'.
274
275       OPAMFETCH specifies how to download files: either `wget', `curl' or a
276       custom command where variables %{url}%, %{out}%, %{retry}%,
277       %{compress}% and %{checksum}% will be replaced. Overrides the
278       'download-command' value from the main config file.
279
280       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup.
281
282       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on'.
283
284       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends'.
285
286       OPAMINPLACEBUILD see option `--inplace-build'.
287
288       OPAMJOBS sets the maximum number of parallel workers to run.
289
290       OPAMJSON log json output to the given file (use character `%' to index
291       the files).
292
293       OPAMKEEPBUILDDIR see install option `--keep-build-dir'.
294
295       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
296       some backups. This skips some finalisers and may also help to get more
297       reliable backtraces.
298
299       OPAMLOCKED combination of `--locked' and `--lock-suffix' options.
300
301       OPAMLOGS logdir sets log directory, default is a temporary directory in
302       /tmp
303
304       OPAMMAKECMD set the system make command to use.
305
306       OPAMMERGEOUT merge process outputs, stderr on stdout.
307
308       OPAMNO answer no to any question asked, see options `--no` and
309       `--confirm-level`. OPAMNO is ignored if either OPAMCONFIRMLEVEL or
310       OPAMYES is set.
311
312       OPAMNOAGGREGATE with `opam admin check', don't aggregate packages.
313
314       OPAMNOASPCUD Deprecated.
315
316       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
317       in an earlier format to the current one, on 'update' or 'init'.
318
319       OPAMNOCHECKSUMS enables option --no-checksums when available.
320
321       OPAMNODEPEXTS disables system dependencies handling, see option
322       `--no-depexts'.
323
324       OPAMNOENVNOTICE Internal.
325
326       OPAMNOSELFUPGRADE see option `--no-self-upgrade'
327
328       OPAMPINKINDAUTO sets whether version control systems should be detected
329       when pinning to a local path. Enabled by default since 1.3.0.
330
331       OPAMPRECISETRACKING fine grain tracking of directories.
332
333       OPAMPREPRO set this to false to disable CUDF preprocessing. Less
334       efficient, but might help debugging solver issue.
335
336       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
337       available (e.g. for `opam install').
338
339       OPAMRETRIES sets the number of tries before failing downloads.
340
341       OPAMREUSEBUILDDIR see option `--reuse-build-dir'.
342
343       OPAMROOT see option `--root'. This is automatically set by `opam env
344       --root=DIR --set-root'.
345
346       OPAMROOTISOK don't complain when running as root.
347
348       OPAMSAFE see option `--safe'.
349
350       OPAMSHOW see option `--show'.
351
352       OPAMSKIPUPDATE see option `--skip-updates'.
353
354       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
355       compatibility testing only.
356
357       OPAMSOLVERALLOWSUBOPTIMAL (default `true') allows some solvers to still
358       return a solution when they reach timeout; while the solution remains
359       assured to be consistent, there is no guarantee in this case that it
360       fits the expected optimisation criteria. If `true', opam willcontinue
361       with a warning, if `false' a timeout is an error. Currently only the
362       builtin-z3 backend handles this degraded case.
363
364       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
365       60.0, set to 0 for unlimited. Note that all solvers may not support
366       this option.
367
368       OPAMSTATS display stats at the end of command.
369
370       OPAMSTATUSLINE display a dynamic status line showing what's currently
371       going on on the terminal. (one of one of `always', `never' or `auto')
372
373       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.).
374
375       OPAMSWITCH see option `--switch'. Automatically set by `opam env
376       --switch=SWITCH --set-switch'.
377
378       OPAMUNLOCKBASE see install option `--unlock-base'.
379
380       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
381       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
382       are set. See also option --criteria.
383
384       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
385
386       OPAMUSEOPENSSL force openssl use for hash computing.
387
388       OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
389       or `auto'). By default `auto', which is determined from the locale).
390
391       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
392       Implies OPAMUTF8. This is set by default on OSX only.
393
394       OPAMVALIDATIONHOOK if set, uses the `%{hook%}' command to validate an
395       opam repository update.
396
397       OPAMVERBOSE see option `--verbose'.
398
399       OPAMVERSIONLAGPOWER do not use.
400
401       OPAMWITHDOC see install option `--with-doc'.
402
403       OPAMWITHTEST see install option `--with-test.
404
405       OPAMWORKINGDIR see option `--working-dir'.
406
407       OPAMYES see options `--yes' and `--confirm-level`. OPAMYES has has
408       priority over OPAMNO and is ignored if OPAMCONFIRMLEVEL is set.
409
410       OPAMVAR_var overrides the contents of the variable var when
411       substituting `%{var}%` strings in `opam` files.
412
413       OPAMVAR_package_var overrides the contents of the variable package:var
414       when substituting `%{package:var}%` strings in `opam` files.
415

CLI VERSION

417       All scripts and programmatic invocations of opam should use `--cli' in
418       order to ensure that they work seamlessly with future versions of the
419       opam client. Additionally, blog posts or other documentation can
420       benefit, as it prevents information from becoming stale.
421
422       Although opam only supports roots (~/.opam/) for the current version,
423       it does provide backwards compatibility for its command-line interface.
424
425       Since CLI version support was only added in opam 2.1, use OPAMCLI to
426       select 2.0 support (as opam 2.0 will just ignore it), and `--cli=2.1'
427       for 2.1 (or later) versions, since an environment variable controlling
428       the parsing of syntax is brittle. To this end, opam displays a warning
429       if OPAMCLI specifies a valid version other than 2.0, and also if
430       `--cli=2.0' is specified.
431
432       The command-line version is selected by using the `--cli' option or the
433       OPAMCLI environment variable. `--cli' may be specified morethan once,
434       where the last instance takes precedence. OPAMCLI is only inspected if
435       `--cli' is not given.
436

EXIT STATUS

438       As an exception to the following, the `exec' command returns 127 if the
439       command was not found or couldn't be executed, and the command's exit
440       value otherwise.
441
442       0   Success, or true for boolean queries.
443
444       1   False. Returned when a boolean return value is expected, e.g. when
445           running with --check, or for queries like opam lint.
446
447       2   Bad command-line arguments, or command-line arguments pointing to
448           an invalid context (e.g. file not following the expected format).
449
450       5   Not found. You requested something (package, version, repository,
451           etc.) that couldn't be found.
452
453       10  Aborted. The operation required confirmation, which wasn't given.
454
455       15  Could not acquire the locks required for the operation.
456
457       20  There is no solution to the user request. This can be caused by
458           asking to install two incompatible packages, for example.
459
460       30  Error in package definition, or other metadata files. Using
461           --strict raises this error more often.
462
463       31  Package script error. Some package operations were unsuccessful.
464           This may be an error in the packages or an incompatibility with
465           your system. This can be a partial error.
466
467       40  Sync error. Could not fetch some remotes from the network. This can
468           be a partial error.
469
470       50  Configuration error. Opam or system configuration doesn't allow
471           operation, and needs fixing.
472
473       60  Solver failure. The solver failed to return a sound answer. It can
474           be due to a broken external solver, or an error in solver
475           configuration.
476
477       99  Internal error. Something went wrong, likely due to a bug in opam
478           itself.
479
480       130 User interrupt. SIGINT was received, generally due to the user
481           pressing Ctrl-C.
482

FURTHER DOCUMENTATION

484       See https://opam.ocaml.org/doc.
485

AUTHORS

487       Vincent Bernardoff <vb@luminar.eu.org>
488       Raja Boujbel <raja.boujbel@ocamlpro.com>
489       Roberto Di Cosmo <roberto@dicosmo.org>
490       Thomas Gazagnaire <thomas@gazagnaire.org>
491       Louis Gesbert <louis.gesbert@ocamlpro.com>
492       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
493       Anil Madhavapeddy <anil@recoil.org>
494       Guillem Rieu <guillem.rieu@ocamlpro.com>
495       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
496       Frederic Tuong <tuong@users.gforge.inria.fr>
497

BUGS

499       Check bug reports at https://github.com/ocaml/opam/issues.
500
501
502
503Opam 2.1.2                                                        OPAM-LOCK(1)
Impressum