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

NAME

6       opam-lint - Checks and validate package description ('opam') files.
7

SYNOPSIS

9       opam lint [OPTION]… [FILES]…
10

DESCRIPTION

12       Given an opam file, performs several quality checks on it and outputs
13       recommendations, warnings or errors on stderr.
14

ARGUMENTS

16       FILES
17           Name of the opam files to check, or directory containing them.
18           Current directory if unspecified
19

OPTIONS

21       --check-upstream
22           Check upstream, archive availability and checksum(s)
23
24       --no
25           Answer no to all opam yes/no questions without prompting. See also
26           --confirm-level. This is equivalent to setting $OPAMNO to "true".
27
28       --normalise
29           Output a normalised version of the opam file to stdout
30
31       --package=PKG
32           Lint the current definition of the given package instead of
33           specifying an opam file directly.
34
35       -s, --short
36           Only print the warning/error numbers, space-separated, if any
37
38       -W WARNS, --warnings=WARNS
39           Select the warnings to show or hide. WARNS should be a
40           concatenation of +N, -N, +N..M, -N..M to respectively enable or
41           disable warning or error number N or all warnings with numbers
42           between N and M inclusive. All warnings are enabled by default,
43           unless WARNS starts with +, which disables all but the selected
44           ones.
45
46       -y, --yes
47           Answer yes to all opam yes/no questions without prompting. See also
48           --confirm-level. This is equivalent to setting $OPAMYES to "true".
49

LINT CODES

51       W20: Field 'opam-version' refers to the patch version of opam, it
52       should be of the form MAJOR.MINOR
53
54       E21: Field 'opam-version' doesn't match the current version, validation
55       may not be accurate
56
57       E22: Some fields are present but empty; remove or fill them
58
59       E23: Missing field 'maintainer'
60
61       E24: Field 'maintainer' has the old default value
62
63       W25: Missing field 'authors'
64
65       W26: No field 'install', but a field 'remove': install instructions
66       probably part of 'build'. Use the 'install' field or a .install file
67
68       E28: Unknown package flags found
69
70       E29: Package dependencies mention package variables
71
72       E31: Fields 'depends' and 'depopts' refer to the same package names
73
74       E32: Field 'ocaml-version:' and variable 'ocaml-version' are
75       deprecated, use a dependency towards the 'ocaml' package instead for
76       availability, and the 'ocaml:version' package variable for scripts
77
78       E33: Field 'os' is deprecated, use 'available' and the 'os' variable
79       instead
80
81       E34: Field 'available:' contains references to package-local variables.
82       It should only be determined from global configuration variables
83
84       W35: Missing field 'homepage'
85
86       W36: Missing field 'bug-reports'
87
88       W37: Missing field 'dev-repo'
89
90       E39: Command 'make' called directly, use the built-in variable instead
91
92       W41: Some packages are mentioned in package scripts or features, but
93       there is no dependency or depopt toward them
94
95       E42: The 'dev-repo:' field doesn't use version control. You should use
96       URLs of the form "git://", "git+https://", "hg+https://"...
97
98       E43: Conjunction used in 'conflicts:' field. Only '|' is allowed
99
100       W44: The 'plugin' package flag is set but the package name doesn't
101       begin with 'opam-'
102
103       E45: Unclosed variable interpolations in strings
104
105       E46: Package is flagged "conf" but has source, install or remove
106       instructions
107
108       W47: Synopsis (or description first line) should start with a capital
109       and not end with a dot
110
111       W48: The fields 'build-test:' and 'build-doc:' are deprecated, and
112       should be replaced by uses of the 'with-test' and 'with-doc' filter
113       variables in the 'build:' and 'install:' fields, and by the newer
114       'run-test:' field
115
116       W49: The following URLs don't use version control but look like version
117       control URLs
118
119       W50: The 'post' flag doesn't make sense with build or optional
120       dependencies
121
122       E51: The behaviour for negated dependency flags 'build' or 'post' is
123       unspecified
124
125       E52: Package is needlessly flagged "light-uninstall", since it has no
126       remove instructions
127
128       E53: Mismatching 'extra-files:' field
129
130       W54: External dependencies should not contain spaces nor empty string
131
132       E55: Non-normalised OS or arch string being tested
133
134       W56: It is discouraged for non-compiler packages to use 'setenv:'
135
136       E57: Synopsis and description must not be both empty
137
138       W58: Found variable, predefined one
139
140       W59: url doesn't contain a checksum
141
142       E60: Upstream check failed
143
144       W61: `with-test` variable in `run-test` is out of scope, it will be
145       ignored
146
147       W62: License doesn't adhere to the SPDX standard, see
148       https://spdx.org/licenses/
149
150       E65: URLs must be absolute
151
152       W66: String that can't be resolved to bool in filtered package formula
153
154       E67: Checksum specified with a non archive url
155

COMMON OPTIONS

157       These options are common to all commands.
158
159       --best-effort
160           Don't fail if all requested packages can't be installed: try to
161           install as many as possible. Note that not all external solvers may
162           support this option (recent versions of aspcud or mccs should).
163           This is equivalent to setting $OPAMBESTEFFORT environment variable.
164
165       --cli=MAJOR.MINOR (absent=2.1)
166           Use the command-line interface syntax and semantics of MAJOR.MINOR.
167           Intended for any persistent use of opam (scripts, blog posts,
168           etc.), any version of opam in the same MAJOR series will behave as
169           for the specified MINOR release. The flag was not available in opam
170           2.0, so to select the 2.0 CLI, set the OPAMCLI environment variable
171           to 2.0 instead of using this parameter.
172
173       --color=WHEN
174           Colorize the output. WHEN must be one of always, never or auto.
175
176       --confirm-level=LEVEL
177           Confirmation level, LEVEL must be one of ask, no, yes or
178           unsafe-yes. Can be specified more than once. If --yes or --no are
179           also given, the value of the last --confirm-level is taken into
180           account. This is equivalent to setting  $OPAMCONFIRMLEVEL`.
181
182       --criteria=CRITERIA
183           Specify user preferences for dependency solving for this run.
184           Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
185           on the supported language, and the external solvers available, see
186           http://opam.ocaml.org/doc/External_solvers.html. A general guide to
187           using solver preferences can be found at
188           http://www.dicosmo.org/Articles/usercriteria.pdf.
189
190       --cudf=FILENAME
191           Debug option: Save the CUDF requests sent to the solver to
192           FILENAME-<n>.cudf.
193
194       --debug
195           Print debug message to stderr. This is equivalent to setting
196           $OPAMDEBUG to "true".
197
198       --debug-level=LEVEL
199           Like --debug, but allows specifying the debug level (--debug sets
200           it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
201
202       --git-version
203           Print the git version of opam, if set (i.e. you are using a
204           development version), and exit.
205
206       --help[=FMT] (default=auto)
207           Show this help in format FMT. The value FMT must be one of auto,
208           pager, groff or plain. With auto, the format is pager or plain
209           whenever the TERM env var is dumb or undefined.
210
211       --ignore-pin-depends
212           Ignore extra pins required by packages that get pinned, either
213           manually through opam pin or through opam install DIR. This is
214           equivalent to setting IGNOREPINDEPENDS=true.
215
216       --json=FILENAME
217           Save the results of the opam run in a computer-readable file. If
218           the filename contains the character `%', it will be replaced by an
219           index that doesn't overwrite an existing file. Similar to setting
220           the $OPAMJSON variable.
221
222       --no-aspcud
223           Removed in 2.1.
224
225       --no-auto-upgrade
226           When configuring or updating a repository that is written for an
227           earlier opam version (1.2), opam internally converts it to the
228           current format. This disables this behaviour. Note that
229           repositories should define their format version in a 'repo' file at
230           their root, or they will be assumed to be in the older format. It
231           is, in any case, preferable to upgrade the repositories manually
232           using opam admin upgrade [--mirror URL] when possible.
233
234       --no-self-upgrade
235           Opam will replace itself with a newer binary found at OPAMROOT/opam
236           if present. This disables this behaviour.
237
238       -q, --quiet
239           Disables --verbose.
240
241       --root=ROOT
242           Use ROOT as the current root path. This is equivalent to setting
243           $OPAMROOT to ROOT.
244
245       --safe, --readonly
246           Make sure nothing will be automatically updated or rewritten.
247           Useful for calling from completion scripts, for example. Will fail
248           whenever such an operation is needed ; also avoids waiting for
249           locks, skips interactive questions and overrides the $OPAMDEBUG
250           variable. This is equivalent to set environment variable $OPAMSAFE.
251
252       --solver=CMD
253           Specify the CUDF solver to use for resolving package installation
254           problems. This is either a predefined solver (this version of opam
255           supports builtin-mccs+lp(), builtin-mccs+glpk,
256           builtin-dummy-z3-solver, builtin-dummy-0install-solver, aspcud,
257           mccs, aspcud-old, packup), or a custom command that should contain
258           the variables %{input}%, %{output}%, %{criteria}%, and optionally
259           %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
260
261       --strict
262           Fail whenever an error is found in a package definition or a
263           configuration file. The default is to continue silently if
264           possible.
265
266       --switch=SWITCH
267           Use SWITCH as the current compiler switch. This is equivalent to
268           setting $OPAMSWITCH to SWITCH.
269
270       --use-internal-solver
271           Disable any external solver, and use the built-in one (this
272           requires that opam has been compiled with a built-in solver). This
273           is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
274
275       -v, --verbose
276           Be more verbose. One -v shows all package commands, repeat to also
277           display commands called internally (e.g. tar, curl, patch etc.)
278           Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
279
280       --version
281           Show version information.
282
283       -w, --working-dir
284           Whenever updating packages that are bound to a local,
285           version-controlled directory, update to the current working state
286           of their source instead of the last committed state, or the ref
287           they are pointing to. As source directory is copied as it is, if it
288           isn't clean it may result on a opam build failure.This only affects
289           packages explicitly listed on the command-line.It can also be set
290           with $OPAMWORKINGDIR.
291

ENVIRONMENT

293       Opam makes use of the environment variables listed here. Boolean
294       variables should be set to "0", "no", "false" or the empty string to
295       disable, "1", "yes" or "true" to enable.
296
297       OPAMALLPARENS surround all filters with parenthesis.
298
299       OPAMASSUMEDEPEXTS see option `--assume-depexts'.
300
301       OPAMAUTOREMOVE see remove option `--auto-remove'.
302
303       OPAMBESTEFFORT see option `--best-effort'.
304
305       OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
306       the criteria when the `--best-effort' option is set, and is expected to
307       maximise the `opam-query' property in the solution.
308
309       OPAMBUILDDOC Removed in 2.1.
310
311       OPAMBUILDTEST Removed in 2.1.
312
313       OPAMCLI see option `--cli'.
314
315       OPAMCOLOR when set to always or never, sets a default value for the
316       `--color' option.
317
318       OPAMCONFIRMLEVEL see option `--confirm-level`. OPAMCONFIRMLEVEL has
319       priority over OPAMYES and OPAMNO.
320
321       OPAMCRITERIA specifies user preferences for dependency solving. The
322       default value depends on the solver version, use `config report' to
323       know the current setting. See also option --criteria.
324
325       OPAMCUDFFILE save the cudf graph to file-actions-explicit.dot.
326
327       OPAMCUDFTRIM controls the filtering of unrelated packages during CUDF
328       preprocessing.
329
330       OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
331       for more options.
332
333       OPAMDEBUG see options `--debug' and `--debug-level'.
334
335       OPAMDEBUGSECTIONS if set, limits debug messages to the space-separated
336       list of sections. Sections can optionally have a specific debug level
337       (for example, CLIENT:2 or CLIENT CUDF:2), but otherwise use
338       `--debug-level'.
339
340       OPAMDIGDEPTH defines how aggressive the lookup for conflicts during
341       CUDF preprocessing is.
342
343       OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
344
345       OPAMDROPWORKINGDIR overrides packages previously updated with
346       --working-dir on update. Without this variable set, opam would keep
347       them unchanged unless explicitly named on the command-line.
348
349       OPAMDRYRUN see option `--dry-run'.
350
351       OPAMEDITOR sets the editor to use for opam file editing, overrides
352       $EDITOR and $VISUAL.
353
354       OPAMERRLOGLEN sets the number of log lines printed when a sub-process
355       fails. 0 to print all.
356
357       OPAMEXTERNALSOLVER see option `--solver'.
358
359       OPAMFAKE see option `--fake'.
360
361       OPAMFETCH specifies how to download files: either `wget', `curl' or a
362       custom command where variables %{url}%, %{out}%, %{retry}%,
363       %{compress}% and %{checksum}% will be replaced. Overrides the
364       'download-command' value from the main config file.
365
366       OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup.
367
368       OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on'.
369
370       OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends'.
371
372       OPAMINPLACEBUILD see option `--inplace-build'.
373
374       OPAMJOBS sets the maximum number of parallel workers to run.
375
376       OPAMJSON log json output to the given file (use character `%' to index
377       the files).
378
379       OPAMKEEPBUILDDIR see install option `--keep-build-dir'.
380
381       OPAMKEEPLOGS tells opam to not remove some temporary command logs and
382       some backups. This skips some finalisers and may also help to get more
383       reliable backtraces.
384
385       OPAMLOCKED combination of `--locked' and `--lock-suffix' options.
386
387       OPAMLOGS logdir sets log directory, default is a temporary directory in
388       /tmp
389
390       OPAMMAKECMD set the system make command to use.
391
392       OPAMMERGEOUT merge process outputs, stderr on stdout.
393
394       OPAMNO answer no to any question asked, see options `--no` and
395       `--confirm-level`. OPAMNO is ignored if either OPAMCONFIRMLEVEL or
396       OPAMYES is set.
397
398       OPAMNOAGGREGATE with `opam admin check', don't aggregate packages.
399
400       OPAMNOASPCUD Deprecated.
401
402       OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
403       in an earlier format to the current one, on 'update' or 'init'.
404
405       OPAMNOCHECKSUMS enables option --no-checksums when available.
406
407       OPAMNODEPEXTS disables system dependencies handling, see option
408       `--no-depexts'.
409
410       OPAMNOENVNOTICE Internal.
411
412       OPAMNOSELFUPGRADE see option `--no-self-upgrade'
413
414       OPAMPINKINDAUTO sets whether version control systems should be detected
415       when pinning to a local path. Enabled by default since 1.3.0.
416
417       OPAMPRECISETRACKING fine grain tracking of directories.
418
419       OPAMPREPRO set this to false to disable CUDF preprocessing. Less
420       efficient, but might help debugging solver issue.
421
422       OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
423       available (e.g. for `opam install').
424
425       OPAMRETRIES sets the number of tries before failing downloads.
426
427       OPAMREUSEBUILDDIR see option `--reuse-build-dir'.
428
429       OPAMROOT see option `--root'. This is automatically set by `opam env
430       --root=DIR --set-root'.
431
432       OPAMROOTISOK don't complain when running as root.
433
434       OPAMSAFE see option `--safe'.
435
436       OPAMSHOW see option `--show'.
437
438       OPAMSKIPUPDATE see option `--skip-updates'.
439
440       OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
441       compatibility testing only.
442
443       OPAMSOLVERALLOWSUBOPTIMAL (default `true') allows some solvers to still
444       return a solution when they reach timeout; while the solution remains
445       assured to be consistent, there is no guarantee in this case that it
446       fits the expected optimisation criteria. If `true', opam willcontinue
447       with a warning, if `false' a timeout is an error. Currently only the
448       builtin-z3 backend handles this degraded case.
449
450       OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
451       60.0, set to 0 for unlimited. Note that all solvers may not support
452       this option.
453
454       OPAMSTATS display stats at the end of command.
455
456       OPAMSTATUSLINE display a dynamic status line showing what's currently
457       going on on the terminal. (one of one of always, never or auto)
458
459       OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.).
460
461       OPAMSWITCH see option `--switch'. Automatically set by `opam env
462       --switch=SWITCH --set-switch'.
463
464       OPAMUNLOCKBASE see install option `--unlock-base'.
465
466       OPAMUPGRADECRITERIA specifies user preferences for dependency solving
467       when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
468       are set. See also option --criteria.
469
470       OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
471
472       OPAMUSEOPENSSL force openssl use for hash computing.
473
474       OPAMUTF8 use UTF8 characters in output (one of one of always, never or
475       auto). By default `auto', which is determined from the locale).
476
477       OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
478       Implies OPAMUTF8. This is set by default on OSX only.
479
480       OPAMVALIDATIONHOOK if set, uses the `%{hook%}' command to validate an
481       opam repository update.
482
483       OPAMVERBOSE see option `--verbose'.
484
485       OPAMVERSIONLAGPOWER do not use.
486
487       OPAMWITHDOC see install option `--with-doc'.
488
489       OPAMWITHTEST see install option `--with-test.
490
491       OPAMWORKINGDIR see option `--working-dir'.
492
493       OPAMYES see options `--yes' and `--confirm-level`. OPAMYES has has
494       priority over OPAMNO and is ignored if OPAMCONFIRMLEVEL is set.
495
496       OPAMVAR_var overrides the contents of the variable var when
497       substituting `%{var}%` strings in `opam` files.
498
499       OPAMVAR_package_var overrides the contents of the variable package:var
500       when substituting `%{package:var}%` strings in `opam` files.
501

CLI VERSION

503       All scripts and programmatic invocations of opam should use `--cli' in
504       order to ensure that they work seamlessly with future versions of the
505       opam client. Additionally, blog posts or other documentation can
506       benefit, as it prevents information from becoming stale.
507
508       Although opam only supports roots (~/.opam/) for the current version,
509       it does provide backwards compatibility for its command-line interface.
510
511       Since CLI version support was only added in opam 2.1, use OPAMCLI to
512       select 2.0 support (as opam 2.0 will just ignore it), and `--cli=2.1'
513       for 2.1 (or later) versions, since an environment variable controlling
514       the parsing of syntax is brittle. To this end, opam displays a warning
515       if OPAMCLI specifies a valid version other than 2.0, and also if
516       `--cli=2.0' is specified.
517
518       The command-line version is selected by using the `--cli' option or the
519       OPAMCLI environment variable. `--cli' may be specified morethan once,
520       where the last instance takes precedence. OPAMCLI is only inspected if
521       `--cli' is not given.
522

EXIT STATUS

524       As an exception to the following, the `exec' command returns 127 if the
525       command was not found or couldn't be executed, and the command's exit
526       value otherwise.
527
528       0   Success, or true for boolean queries.
529
530       1   False. Returned when a boolean return value is expected, e.g. when
531           running with --check, or for queries like opam lint.
532
533       2   Bad command-line arguments, or command-line arguments pointing to
534           an invalid context (e.g. file not following the expected format).
535
536       5   Not found. You requested something (package, version, repository,
537           etc.) that couldn't be found.
538
539       10  Aborted. The operation required confirmation, which wasn't given.
540
541       15  Could not acquire the locks required for the operation.
542
543       20  There is no solution to the user request. This can be caused by
544           asking to install two incompatible packages, for example.
545
546       30  Error in package definition, or other metadata files. Using
547           --strict raises this error more often.
548
549       31  Package script error. Some package operations were unsuccessful.
550           This may be an error in the packages or an incompatibility with
551           your system. This can be a partial error.
552
553       40  Sync error. Could not fetch some remotes from the network. This can
554           be a partial error.
555
556       50  Configuration error. Opam or system configuration doesn't allow
557           operation, and needs fixing.
558
559       60  Solver failure. The solver failed to return a sound answer. It can
560           be due to a broken external solver, or an error in solver
561           configuration.
562
563       99  Internal error. Something went wrong, likely due to a bug in opam
564           itself.
565
566       130 User interrupt. SIGINT was received, generally due to the user
567           pressing Ctrl-C.
568

FURTHER DOCUMENTATION

570       See https://opam.ocaml.org/doc.
571

AUTHORS

573       Vincent Bernardoff <vb@luminar.eu.org>
574       Raja Boujbel <raja.boujbel@ocamlpro.com>
575       Roberto Di Cosmo <roberto@dicosmo.org>
576       Thomas Gazagnaire <thomas@gazagnaire.org>
577       Louis Gesbert <louis.gesbert@ocamlpro.com>
578       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
579       Anil Madhavapeddy <anil@recoil.org>
580       Guillem Rieu <guillem.rieu@ocamlpro.com>
581       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
582       Frederic Tuong <tuong@users.gforge.inria.fr>
583

BUGS

585       Check bug reports at https://github.com/ocaml/opam/issues.
586
587
588
589Opam 2.1.5                                                        OPAM-LINT(1)
Impressum