1OPAM-PIN(1) Opam Manual OPAM-PIN(1)
2
6 opam-pin - Pin a given package to a specific version or source.
7
9 opam pin [OPTION]... [COMMAND] [ARG]...
10
12 This command allows local customisation of the packages in a given
13 switch. A pinning can either just enforce a given version, or provide a
14 local, editable version of the definition of the package. It is also
15 possible to create a new package just by pinning a non-existing package
16 name.
17 Any customisation is available through the edit subcommand, but the
19 command-line gives facility for altering the source URL of the package,
20 since it is the most common use: opam pin add PKG URL modifies package
21 PKG to fetch its source from URL. If a package definition is found in
22 the package's source tree, it will be used locally.
23 If (or -) is specified, the package is pinned without a source archive.
25 The package name can be omitted if the target is a directory containing
26 one or more valid package definitions (this allows one to do e.g. opam
27 pin add . from a source directory.
28 If PACKAGE has the form name.version, the pinned package will be
30 considered as version version by opam. Beware that this doesn't relate
31 with the version of the source actually used for the package.
32 The default subcommand is list if there are no further arguments, and
34 add otherwise if unambiguous.
35
37 Without argument, defaults to list.
38 list
40 Lists pinned packages.
41 add PACKAGE TARGET
43 Pins package PACKAGE to TARGET, which may be a version, a path, or
44 a URL. PACKAGE can be omitted if TARGET contains one or more
45 package descriptions. TARGET can be replaced by --dev-repo if a
46 package by that name is already known. If TARGET is -, the package
47 is pinned as a virtual package, without any source. opam will infer
48 the kind of pinning from the format (and contents, if local) of
49 TARGET, Use --kind or an explicit URL to disable that behaviour.
50 Pins to version control systems may target a specific branch or
51 commit using #branch e.g. git://host/me/pkg#testing. If PACKAGE is
52 not a known package name, a new package by that name will be
53 locally created. For source pinnings, the package version may be
54 specified by using the format NAME.VERSION for PACKAGE, in the
55 source opam file, or with edit.
56 remove NAMES...|TARGET
58 Unpins packages NAMES, restoring their definition from the
59 repository, if any. With a TARGET, unpins everything that is
60 currently pinned to that target.
61 edit NAME
63 Opens an editor giving you the opportunity to change the package
64 definition that opam will locally use for package NAME, including
65 its version and source URL. Using the format NAME.VERSION will
66 update the version in the opam file in advance of editing, without
67 changing the actual target. The chosen editor is determined from
68 environment variables OPAM_EDITOR, VISUAL or EDITOR, in order.
69
71 --dev-repo
72 Pin to the upstream package source for the latest development
73 version
74 -e, --edit
76 With opam pin add, edit the opam file as with `opam pin edit' after
77 pinning.
78 -j JOBS, --jobs=JOBS
80 Set the maximal number of concurrent jobs to use. The default value
81 is calculated from the number of cores. You can also set it using
82 the $OPAMJOBS environment variable.
83 -k KIND, --kind=KIND
85 Sets the kind of pinning. Must be one of one of `version', `path',
86 `http', `git', `darcs', `hg', `none' or `auto'. If unset or auto,
87 is inferred from the format of the target, defaulting to the
88 appropriate version control if one is detected in the given
89 directory, or to path otherwise. OPAMPINKINDAUTO can be set to "0"
90 to disable automatic detection of version control.Use none to pin
91 without a target (for virtual packages).
92 -n, --no-action
94 Just record the new pinning status, and don't prompt for
95 (re)installation or removal of affected packages.
96 -s, --short
98 Output raw lists of names, one per line, skipping any details.
99
101 -b, --keep-build-dir
102 Keep the build directories after compiling packages. This is
103 equivalent to setting $OPAMKEEPBUILDDIR to "true".
104 -d, --with-doc, --build-doc
106 Build the package documentation. This only affects packages listed
107 on the command-line. The --build-doc form is deprecated as this
108 does also installation. This is equivalent to setting $OPAMWITHDOC
109 (or the deprecated $OPAMBUILDDOC) to "true".
110 --dry-run
112 Simulate the command, but don't actually perform any changes. This
113 also can be set with environment variable $OPAMDEBUG.
114 --fake
116 This option registers the actions into the opam database, without
117 actually performing them. WARNING: This option is dangerous and
118 likely to break your opam environment. You probably want
119 `--dry-run'. You've been warned.
120 --ignore-constraints-on[=PACKAGES] (default=)
122 Forces opam to ignore version constraints on all dependencies to
123 the listed packages. This can be used to test compatibility, but
124 expect builds to break when using this. Note that version
125 constraints on optional dependencies and conflicts are unaffected.
126 This is equivalent to setting $OPAMIGNORECONSTRAINTS.
127 --inplace-build
129 When compiling a package which has its source bound to a local
130 directory, process the build and install actions directly in that
131 directory, rather than in a clean copy handled by opam. This only
132 affects packages that are explicitly listed on the command-line.
133 This is equivalent to setting $OPAMINPLACEBUILD to "true".
134 --locked[=SUFFIX] (default=locked)
136 In commands that use opam files found from pinned sources, if a
137 variant of the file with an added .SUFFIX extension is found (e.g.
138 foo.opam.locked besides foo.opam), that will be used instead. This
139 is typically useful to offer a more specific set of dependencies
140 and reproduce similar build contexts, hence the name. The opam lock
141 plugin can be used to generate such files, based on the versions of
142 the dependencies currently installed on the host. This is
143 equivalent to setting the $OPAMLOCKED environment variable. Note
144 that this option doesn't generally affect already pinned packages.
145 -m MAKE, --make=MAKE
147 Use MAKE as the default 'make' command. Deprecated: use opam config
148 set[-global] make MAKE instead. Has no effect if the make variable
149 is defined.
150 --no-checksums
152 Do not verify the checksum of downloaded archives.This is
153 equivalent to setting $OPAMNOCHECKSUMS to "true".
154 --require-checksums
156 Reject the installation of packages that don't provide a checksum
157 for the upstream archives. This is equivalent to setting
158 $OPAMREQUIRECHECKSUMS to "true".
159 --reuse-build-dir
161 Reuse existing build directories (kept by using --keep-build-dir),
162 instead of compiling from a fresh clone of the source. This can be
163 faster, but also lead to failures if the build systems of the
164 packages don't handle upgrades of dependencies well. This is
165 equivalent to setting $OPAMREUSEBUILDDIR to "true".
166 --show-actions
168 Call the solver and display the actions. Don't perform any changes.
169 This is equivalent to setting $OPAMSHOW.
170 --skip-updates
172 When running an install, upgrade or reinstall on source-pinned
173 packages, they are normally updated from their origin first. This
174 flag disables that behaviour and will keep them to their version in
175 cache. This is equivalent to setting $OPAMSKIPUPDATE.
176 -t, --with-test, --build-test
178 Build and run the package unit-tests. This only affects packages
179 listed on the command-line. The --build-test form is deprecated as
180 this also affects installation. This is equivalent to setting
181 $OPAMWITHTEST (or the deprecated $OPAMBUILDTEST) to "true".
182 --unlock-base
184 Allow changes to the packages set as switch base (typically, the
185 main compiler). Use with caution. This is equivalent to setting the
186 $OPAMUNLOCKBASE environment variable
187
189 These options are common to all commands.
190 --best-effort
192 Don't fail if all requested packages can't be installed: try to
193 install as many as possible. Note that not all external solvers may
194 support this option (recent versions of aspcud or mccs should).
195 This is equivalent to setting $OPAMBESTEFFORT environment variable.
196 --color=WHEN
198 Colorize the output. WHEN must be one of `always', `never' or
199 `auto'.
200 --criteria=CRITERIA
202 Specify user preferences for dependency solving for this run.
203 Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
204 on the supported language, and the external solvers available, see
205 http://opam.ocaml.org/doc/External_solvers.html. A general guide to
206 using solver preferences can be found at
207 http://www.dicosmo.org/Articles/usercriteria.pdf.
208 --cudf=FILENAME
210 Debug option: Save the CUDF requests sent to the solver to
211 FILENAME-<n>.cudf.
212 --debug
214 Print debug message to stderr. This is equivalent to setting
215 $OPAMDEBUG to "true".
216 --debug-level=LEVEL
218 Like --debug, but allows specifying the debug level (--debug sets
219 it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
220 --git-version
222 Print the git version of opam, if set (i.e. you are using a
223 development version), and exit.
224 --help[=FMT] (default=auto)
226 Show this help in format FMT. The value FMT must be one of `auto',
227 `pager', `groff' or `plain'. With `auto', the format is `pager` or
228 `plain' whenever the TERM env var is `dumb' or undefined.
229 --ignore-pin-depends
231 Ignore extra pins required by packages that get pinned, either
232 manually through opam pin or through opam install DIR. This is
233 equivalent to setting IGNOREPINDEPENDS=true.
234 --json=FILENAME
236 Save the results of the opam run in a computer-readable file. If
237 the filename contains the character `%', it will be replaced by an
238 index that doesn't overwrite an existing file. Similar to setting
239 the $OPAMJSON variable.
240 --no-aspcud
242 Deprecated.
243 --no-auto-upgrade
245 When configuring or updating a repository that is written for an
246 earlier opam version (1.2), opam internally converts it to the
247 current format. This disables this behaviour. Note that
248 repositories should define their format version in a 'repo' file at
249 their root, or they will be assumed to be in the older format. It
250 is, in any case, preferable to upgrade the repositories manually
251 using opam admin upgrade [--mirror URL] when possible.
252 --no-self-upgrade
254 Opam will replace itself with a newer binary found at OPAMROOT/opam
255 if present. This disables this behaviour.
256 -q, --quiet
258 Disables --verbose.
259 --root=ROOT
261 Use ROOT as the current root path. This is equivalent to setting
262 $OPAMROOT to ROOT.
263 --safe, --readonly
265 Make sure nothing will be automatically updated or rewritten.
266 Useful for calling from completion scripts, for example. Will fail
267 whenever such an operation is needed ; also avoids waiting for
268 locks, skips interactive questions and overrides the $OPAMDEBUG
269 variable. This is equivalent to set environment variable $OPAMSAFE.
270 --solver=CMD
272 Specify the CUDF solver to use for resolving package installation
273 problems. This is either a predefined solver (this version of opam
274 supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
275 aspcud-old, packup), or a custom command that should contain the
276 variables %{input}%, %{output}%, %{criteria}%, and optionally
277 %{timeout}%. This is equivalent to setting $OPAMEXTERNALSOLVER.
278 --strict
280 Fail whenever an error is found in a package definition or a
281 configuration file. The default is to continue silently if
282 possible.
283 --switch=SWITCH
285 Use SWITCH as the current compiler switch. This is equivalent to
286 setting $OPAMSWITCH to SWITCH.
287 --use-internal-solver
289 Disable any external solver, and use the built-in one (this
290 requires that opam has been compiled with a built-in solver). This
291 is equivalent to setting $OPAMNOASPCUD or $OPAMUSEINTERNALSOLVER.
292 -v, --verbose
294 Be more verbose. One -v shows all package commands, repeat to also
295 display commands called internally (e.g. tar, curl, patch etc.)
296 Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
297 --version
299 Show version information.
300 -w, --working-dir
302 Whenever updating packages that are bound to a local,
303 version-controlled directory, update to the current working state
304 of their source instead of the last committed state, or the ref
305 they are pointing to. This only affects packages explicitly listed
306 on the command-line.It can also be set with $OPAMWORKINGDIR.
307 -y, --yes
309 Answer yes to all yes/no questions without prompting. This is
310 equivalent to setting $OPAMYES to "true".
311
313 Opam makes use of the environment variables listed here. Boolean
314 variables should be set to "0", "no", "false" or the empty string to
315 disable, "1", "yes" or "true" to enable.
316 OPAMALLPARENS surround all filters with parenthesis
318 OPAMAUTOREMOVE see remove option `--auto-remove`
320 OPAMBESTEFFORT see option `--best-effort`
322 OPAMBESTEFFORTPREFIXCRITERIA sets the string that must be prepended to
324 the criteria when the `--best-effort` option is set, and is expected to
325 maximise the `opam-query` property in the solution
326 OPAMCOLOR, when set to always or never, sets a default value for the
328 --color option.
329 OPAMCRITERIA specifies user preferences for dependency solving. The
331 default value depends on the solver version, use `config report` to
332 know the current setting. See also option --criteria
333 OPAMCUDFFILE file save the cudf graph to file-actions-explicit.dot
335 OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
337 for more options.
338 OPAMDEBUG see options `--debug' and `--debug-level'.
340 OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
342 OPAMDRYRUN see option `--dry-run`
344 OPAMEDITOR sets the editor to use for opam file editing, overrides
346 $EDITOR and $VISUAL
347 OPAMERRLOGLEN sets the number of log lines printed when a sub-process
349 fails. 0 to print all.
350 OPAMEXTERNALSOLVER see option `--solver'.
352 OPAMFAKE see option `--fake`
354 OPAMFETCH specifies how to download files: either `wget', `curl' or a
356 custom command where variables %{url}%, %{out}%, %{retry}%,
357 %{compress}% and %{checksum}% will be replaced. Overrides the
358 'download-command' value from the main config file.
359 OPAMFIXUPCRITERIA same as OPAMUPGRADECRITERIA, but specific to fixup
361 OPAMIGNORECONSTRAINTS see install option `--ignore-constraints-on`
363 OPAMIGNOREPINDEPENDS see option `--ignore-pin-depends`
365 OPAMJOBS sets the maximum number of parallel workers to run.
367 OPAMJSON log json output to the given file (use character `%' to index
369 the files)
370 OPAMLOCKED see install option `--locked`
372 OPAMLOGS logdir sets log directory, default is a temporary directory in
374 /tmp
375 OPAMMAKECMD set the system make command to use
377 OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
379 in an earlier format to the current one, on 'update' or 'init'.
380 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 OPAMLOCKRETRIES sets the number of tries after which opam gives up
386 acquiring its lock and fails. <= 0 means infinite wait.
387 OPAMMERGEOUT merge process outputs, stderr on stdout
389 OPAMNO answer no to any question asked.
391 OPAMNOASPCUD Deprecated.
393 OPAMNOCHECKSUMS enables option --no-checksums when available.
395 OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
397 OPAMPINKINDAUTO sets whether version control systems should be detected
399 when pinning to a local path. Enabled by default since 1.3.0.
400 OPAMPRECISETRACKING fine grain tracking of directories
402 OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
404 available (e.g. for `opam install`).
405 OPAMRETRES sets the number of tries before failing downloads.
407 OPAMROOT see option `--root'. This is automatically set by `opam env
409 --root=DIR --set-root'.
410 OPAMROOTISOK don't complain when running as root.
412 OPAMSAFE see option `--safe'
414 OPAMSHOW see option `--show`
416 OPAMSKIPUPDATE see option `--skip-updates`
418 OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
420 compatibility testing only.
421 OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
423 60.0, set to 0 for unlimited. Note that all solvers may not support
424 this option.
425 OPAMSTATUSLINE display a dynamic status line showing what's currently
427 going on on the terminal. (one of one of `always', `never' or `auto')
428 OPAMSTATS display stats at the end of command
430 OPAMSTRICT fail on inconsistencies (file reading, switch import, etc.)
432 OPAMSWITCH see option `--switch'. Automatically set by `opam env
434 --switch=SWITCH --set-switch'.
435 OPAMUNLOCKBASE see install option `--unlock-base`
437 OPAMUPGRADECRITERIA specifies user preferences for dependency solving
439 when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
440 are set. See also option --criteria
441 OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
443 OPAMUSEOPENSSL force openssl use for hash computing
445 OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
447 or `auto'). By default `auto', which is determined from the locale).
448 OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
450 Implies OPAMUTF8. This is set by default on OSX only.
451 OPAMVALIDATIONHOOK hook if set, uses the `%{hook%}` command to validate
453 an opam repository update
454 OPAMVAR_var overrides the contents of the variable var when
456 substituting `%{var}%` strings in `opam` files.
457 OPAMVAR_package_var overrides the contents of the variable package:var
459 when substituting `%{package:var}%` strings in `opam` files.
460 OPAMVERBOSE see option `--verbose'.
462 OPAMWORKINGDIR see option `--working-dir`
464 OPAMYES see option `--yes'.
466
468 As an exception to the following, the `exec' command returns 127 if the
469 command was not found or couldn't be executed, and the command's exit
470 value otherwise.
471 0 Success, or true for boolean queries.
473 1 False. Returned when a boolean return value is expected, e.g. when
475 running with --check, or for queries like opam lint.
476 2 Bad command-line arguments, or command-line arguments pointing to
478 an invalid context (e.g. file not following the expected format).
479 5 Not found. You requested something (package, version, repository,
481 etc.) that couldn't be found.
482 10 Aborted. The operation required confirmation, which wasn't given.
484 15 Could not acquire the locks required for the operation.
486 20 There is no solution to the user request. This can be caused by
488 asking to install two incompatible packages, for example.
489 30 Error in package definition, or other metadata files. Using
491 --strict raises this error more often.
492 31 Package script error. Some package operations were unsuccessful.
494 This may be an error in the packages or an incompatibility with
495 your system. This can be a partial error.
496 40 Sync error. Could not fetch some remotes from the network. This can
498 be a partial error.
499 50 Configuration error. Opam or system configuration doesn't allow
501 operation, and needs fixing.
502 60 Solver failure. The solver failed to return a sound answer. It can
504 be due to a broken external solver, or an error in solver
505 configuration.
506 99 Internal error. Something went wrong, likely due to a bug in opam
508 itself.
509 130 User interrupt. SIGINT was received, generally due to the user
511 pressing Ctrl-C.
512
514 See https://opam.ocaml.org/doc.
515
517 Vincent Bernardoff <vb@luminar.eu.org>
518 Raja Boujbel <raja.boujbel@ocamlpro.com>
519 Roberto Di Cosmo <roberto@dicosmo.org>
520 Thomas Gazagnaire <thomas@gazagnaire.org>
521 Louis Gesbert <louis.gesbert@ocamlpro.com>
522 Fabrice Le Fessant <Fabrice.Le_fessant@inria.fr>
523 Anil Madhavapeddy <anil@recoil.org>
524 Guillem Rieu <guillem.rieu@ocamlpro.com>
525 Ralf Treinen <ralf.treinen@pps.jussieu.fr>
526 Frederic Tuong <tuong@users.gforge.inria.fr>
527
529 Check bug reports at https://github.com/ocaml/opam/issues.
530Opam 2.0.6 OPAM-PIN(1)