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

NAME

6       opam-source - Get the source of an opam package.
7

SYNOPSIS

9       opam source [OPTION]… PACKAGE
10

DESCRIPTION

12       Downloads the source for a given package to a local directory for
13       development, bug fixing or documentation purposes.
14

ARGUMENTS

16       PACKAGE (required)
17           A package name with an optional version constraint
18

OPTIONS

20       --dev-repo
21           Get the latest version-controlled source rather than the release
22           archive
23
24       --dir=DIR
25           The directory where to put the source.
26
27       --no
28           Answer no to all opam yes/no questions without prompting. See also
29           --confirm-level. This is equivalent to setting $OPAMNO to "true".
30
31       --pin
32           Pin the package to the downloaded source (see `opam pin').
33
34       -y, --yes
35           Answer yes to all opam yes/no questions without prompting. See also
36           --confirm-level. This is equivalent to setting $OPAMYES to "true".
37

COMMON OPTIONS

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

ENVIRONMENT

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

CLI VERSION

385       All scripts and programmatic invocations of opam should use `--cli' in
386       order to ensure that they work seamlessly with future versions of the
387       opam client. Additionally, blog posts or other documentation can
388       benefit, as it prevents information from becoming stale.
389
390       Although opam only supports roots (~/.opam/) for the current version,
391       it does provide backwards compatibility for its command-line interface.
392
393       Since CLI version support was only added in opam 2.1, use OPAMCLI to
394       select 2.0 support (as opam 2.0 will just ignore it), and `--cli=2.1'
395       for 2.1 (or later) versions, since an environment variable controlling
396       the parsing of syntax is brittle. To this end, opam displays a warning
397       if OPAMCLI specifies a valid version other than 2.0, and also if
398       `--cli=2.0' is specified.
399
400       The command-line version is selected by using the `--cli' option or the
401       OPAMCLI environment variable. `--cli' may be specified morethan once,
402       where the last instance takes precedence. OPAMCLI is only inspected if
403       `--cli' is not given.
404

EXIT STATUS

406       As an exception to the following, the `exec' command returns 127 if the
407       command was not found or couldn't be executed, and the command's exit
408       value otherwise.
409
410       0   Success, or true for boolean queries.
411
412       1   False. Returned when a boolean return value is expected, e.g. when
413           running with --check, or for queries like opam lint.
414
415       2   Bad command-line arguments, or command-line arguments pointing to
416           an invalid context (e.g. file not following the expected format).
417
418       5   Not found. You requested something (package, version, repository,
419           etc.) that couldn't be found.
420
421       10  Aborted. The operation required confirmation, which wasn't given.
422
423       15  Could not acquire the locks required for the operation.
424
425       20  There is no solution to the user request. This can be caused by
426           asking to install two incompatible packages, for example.
427
428       30  Error in package definition, or other metadata files. Using
429           --strict raises this error more often.
430
431       31  Package script error. Some package operations were unsuccessful.
432           This may be an error in the packages or an incompatibility with
433           your system. This can be a partial error.
434
435       40  Sync error. Could not fetch some remotes from the network. This can
436           be a partial error.
437
438       50  Configuration error. Opam or system configuration doesn't allow
439           operation, and needs fixing.
440
441       60  Solver failure. The solver failed to return a sound answer. It can
442           be due to a broken external solver, or an error in solver
443           configuration.
444
445       99  Internal error. Something went wrong, likely due to a bug in opam
446           itself.
447
448       130 User interrupt. SIGINT was received, generally due to the user
449           pressing Ctrl-C.
450

FURTHER DOCUMENTATION

452       See https://opam.ocaml.org/doc.
453

AUTHORS

455       Vincent Bernardoff <vb@luminar.eu.org>
456       Raja Boujbel <raja.boujbel@ocamlpro.com>
457       Roberto Di Cosmo <roberto@dicosmo.org>
458       Thomas Gazagnaire <thomas@gazagnaire.org>
459       Louis Gesbert <louis.gesbert@ocamlpro.com>
460       Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
461       Anil Madhavapeddy <anil@recoil.org>
462       Guillem Rieu <guillem.rieu@ocamlpro.com>
463
464       Ralf Treinen <ralf.treinen@pps.jussieu.fr>
465       Frederic Tuong <tuong@users.gforge.inria.fr>
466

BUGS

468       Check bug reports at https://github.com/ocaml/opam/issues.
469
470
471
472Opam 2.1.3                                                      OPAM-SOURCE(1)
Impressum