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 to do e.g. opam pin
27 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.
113 --fake
115 This option registers the actions into the opam database, without
116 actually performing them. WARNING: This option is dangerous and
117 likely to break your opam environment. You probably want
118 `--dry-run'. You've been warned.
119 --ignore-constraints-on[=PACKAGES] (default=)
121 Forces opam to ignore version constraints on all dependencies to
122 the listed packages. This can be used to test compatibility, but
123 expect builds to break when using this. Note that version
124 constraints on optional dependencies and conflicts are unaffected.
125 --inplace-build
127 When compiling a package which has its source bound to a local
128 directory, process the build and install actions directly in that
129 directory, rather than in a clean copy handled by opam. This only
130 affects packages that are explicitly listed on the command-line.
131 This is equivalent to setting $OPAMINPLACEBUILD to "true".
132 --locked[=SUFFIX] (default=locked)
134 In commands that use opam files found from pinned sources, if a
135 variant of the file with an added .SUFFIX extension is found (e.g.
136 foo.opam.locked besides foo.opam), that will be used instead. This
137 is typically useful to offer a more specific set of dependencies
138 and reproduce similar build contexts, hence the name. The opam lock
139 plugin can be used to generate such files, based on the versions of
140 the dependencies currently installed on the host. This is
141 equivalent to setting the $OPAMLOCK environment variable. Note that
142 this option doesn't generally affect already pinned packages.
143 -m MAKE, --make=MAKE
145 Use MAKE as the default 'make' command. Deprecated: use opam config
146 set[-global] make MAKE instead. Has no effect if the make variable
147 is defined.
148 --no-checksums
150 Do not verify the checksum of downloaded archives.This is
151 equivalent to setting $OPAMNOCHECKSUMS to "true".
152 --require-checksums
154 Reject the installation of packages that don't provide a checksum
155 for the upstream archives. This is equivalent to setting
156 $OPAMREQUIRECHECKSUMS to "true".
157 --reuse-build-dir
159 Reuse existing build directories (kept by using --keep-build-dir),
160 instead of compiling from a fresh clone of the source. This can be
161 faster, but also lead to failures if the build systems of the
162 packages don't handle upgrades of dependencies well. This is
163 equivalent to setting $OPAMREUSEBUILDDIR to "true".
164 --show-actions
166 Call the solver and display the actions. Don't perform any changes.
167 --skip-updates
169 When running an install, upgrade or reinstall on source-pinned
170 packages, they are normally updated from their origin first. This
171 flag disables that behaviour and will keep them to their version in
172 cache.
173 -t, --with-test, --build-test
175 Build and run the package unit-tests. This only affects packages
176 listed on the command-line. The --build-test form is deprecated as
177 this also affects installation. This is equivalent to setting
178 $OPAMWITHTEST (or the deprecated $OPAMBUILDTEST) to "true".
179 --unlock-base
181 Allow changes to the packages set as switch base (typically, the
182 main compiler). Use with caution.
183
185 These options are common to all commands.
186 --best-effort
188 Don't fail if all requested packages can't be installed: try to
189 install as many as possible. Note that not all external solvers may
190 support this option (recent versions of aspcud or mccs should).
191 --color=WHEN
193 Colorize the output. WHEN must be one of `always', `never' or
194 `auto'.
195 --criteria=CRITERIA
197 Specify user preferences for dependency solving for this run.
198 Overrides both $OPAMCRITERIA and $OPAMUPGRADECRITERIA. For details
199 on the supported language, and the external solvers available, see
200 http://opam.ocaml.org/doc/Specifying_Solver_Preferences.html. A
201 general guide to using solver preferences can be found at
202 http://www.dicosmo.org/Articles/usercriteria.pdf.
203 --cudf=FILENAME
205 Debug option: Save the CUDF requests sent to the solver to
206 FILENAME-<n>.cudf.
207 --debug
209 Print debug message to stderr. This is equivalent to setting
210 $OPAMDEBUG to "true".
211 --debug-level=LEVEL
213 Like --debug, but allows specifying the debug level (--debug sets
214 it to 1). Equivalent to setting $OPAMDEBUG to a positive integer.
215 --git-version
217 Print the git version of opam, if set (i.e. you are using a
218 development version), and exit.
219 --help[=FMT] (default=auto)
221 Show this help in format FMT. The value FMT must be one of `auto',
222 `pager', `groff' or `plain'. With `auto', the format is `pager` or
223 `plain' whenever the TERM env var is `dumb' or undefined.
224 --ignore-pin-depends
226 Ignore extra pins required by packages that get pinned, either
227 manually through opam pin or through opam install DIR. This is
228 equivalent to setting IGNOREPINDEPENDS=true.
229 --json=FILENAME
231 Save the results of the opam run in a computer-readable file. If
232 the filename contains the character `%', it will be replaced by an
233 index that doesn't overwrite an existing file. Similar to setting
234 the $OPAMJSON variable.
235 --no-auto-upgrade
237 When configuring or updating a repository that is written for an
238 earlier opam version (1.2), opam internally converts it to the
239 current format. This disables this behaviour. Note that
240 repositories should define their format version in a 'repo' file at
241 their root, or they will be assumed to be in the older format. It
242 is, in any case, preferable to upgrade the repositories manually
243 using opam admin upgrade [--mirror URL] when possible.
244 --no-self-upgrade
246 Opam will replace itself with a newer binary found at OPAMROOT/opam
247 if present. This disables this behaviour.
248 -q, --quiet
250 Disables --verbose.
251 --root=ROOT
253 Use ROOT as the current root path. This is equivalent to setting
254 $OPAMROOT to ROOT.
255 --safe, --readonly
257 Make sure nothing will be automatically updated or rewritten.
258 Useful for calling from completion scripts, for example. Will fail
259 whenever such an operation is needed ; also avoids waiting for
260 locks, skips interactive questions and overrides the $OPAMDEBUG
261 variable.
262 --solver=CMD
264 Specify the CUDF solver to use for resolving package installation
265 problems. This is either a predefined solver (this version of opam
266 supports builtin-mccs+lp(), builtin-mccs+glpk, aspcud, mccs,
267 aspcud-old, packup), or a custom command that should contain the
268 variables %{input}%, %{output}%, %{criteria}%, and optionally
269 %{timeout}%.
270 --strict
272 Fail whenever an error is found in a package definition or a
273 configuration file. The default is to continue silently if
274 possible.
275 --switch=SWITCH
277 Use SWITCH as the current compiler switch. This is equivalent to
278 setting $OPAMSWITCH to SWITCH.
279 --use-internal-solver, --no-aspcud
281 Disable any external solver, and use the built-in one (this
282 requires that opam has been compiled with a built-in solver).
283 -v, --verbose
285 Be more verbose. One -v shows all package commands, repeat to also
286 display commands called internally (e.g. tar, curl, patch etc.)
287 Repeating n times is equivalent to setting $OPAMVERBOSE to "n".
288 --version
290 Show version information.
291 -w, --working-dir
293 Whenever updating packages that are bound to a local,
294 version-controlled directory, update to the current working state
295 of their source instead of the last committed state, or the ref
296 they are pointing to. This only affects packages explicitly listed
297 on the command-line.
298 -y, --yes
300 Answer yes to all yes/no questions without prompting. This is
301 equivalent to setting $OPAMYES to "true".
302
304 Opam makes use of the environment variables listed here. Boolean
305 variables should be set to "0", "no", "false" or the empty string to
306 disable, "1", "yes" or "true" to enable.
307 OPAMCOLOR, when set to always or never, sets a default value for the
309 --color option.
310 OPAMCRITERIA specifies user preferences for dependency solving. The
312 default value depends on the solver version, use `config report` to
313 know the current setting. See also option --criteria
314 OPAMCURL can be used to select a given 'curl' program. See OPAMFETCH
316 for more options.
317 OPAMDEBUG see options `--debug' and `--debug-level'.
319 OPAMDOWNLOADJOBS sets the maximum number of simultaneous downloads.
321 OPAMERRLOGLEN sets the number of log lines printed when a sub-process
323 fails. 0 to print all.
324 OPAMEXTERNALSOLVER see option `--solver'.
326 OPAMFETCH specifies how to download files: either `wget', `curl' or a
328 custom command where variables %{url}%, %{out}%, %{retry}%,
329 %{compress}% and %{checksum}% will be replaced. Overrides the
330 'download-command' value from the main config file.
331 OPAMJOBS sets the maximum number of parallel workers to run.
333 OPAMJSON log json output to the given file (use character `%' to index
335 the files)
336 OPAMLOCK see option `--lock'.
338 OPAMNOAUTOUPGRADE disables automatic internal upgrade of repositories
340 in an earlier format to the current one, on 'update' or 'init'.
341 OPAMKEEPLOGS tells opam to not remove some temporary command logs and
343 some backups. This skips some finalisers and may also help to get more
344 reliable backtraces
345 OPAMLOCKRETRIES sets the number of tries after which OPAM gives up
347 acquiring its lock and fails. <= 0 means infinite wait.
348 OPAMNO answer no to any question asked.
350 OPAMNOASPCUD see option `--no-aspcud'.
352 OPAMNOSELFUPGRADE see option `--no-self-upgrade'.
354 OPAMPINKINDAUTO sets whether version control systems should be detected
356 when pinning to a local path. Enabled by default since 1.3.0.
357 OPAMREQUIRECHECKSUMS Enables option `--require-checksums' when
359 available (e.g. for `opam install`).
360 OPAMRETRY sets the number of tries before failing downloads.
362 OPAMROOT see option `--root'. This is automatically set by `opam env
364 --root=DIR --set-root'.
365 OPAMROOTISOK don't complain when running as root.
367 OPAMSAFE see option `--safe'
369 OPAMSKIPVERSIONCHECKS bypasses some version checks. Unsafe, for
371 compatibility testing only.
372 OPAMSOLVERTIMEOUT change the time allowance of the solver. Default is
374 60.0, set to 0 for unlimited. Note that all solvers may not support
375 this option.
376 OPAMSTATUSLINE display a dynamic status line showing what's currently
378 going on on the terminal. (one of one of `always', `never' or `auto')
379 OPAMSWITCH see option `--switch'. Automatically set by `opam env
381 --switch=SWITCH --set-switch'.
382 OPAMUPGRADECRITERIA specifies user preferences for dependency solving
384 when performing an upgrade. Overrides OPAMCRITERIA in upgrades if both
385 are set. See also option --criteria
386 OPAMUSEINTERNALSOLVER see option `--use-internal-solver'.
388 OPAMUTF8 use UTF8 characters in output (one of one of `always', `never'
390 or `auto'). By default `auto', which is determined from the locale).
391 OPAMUTF8MSGS use extended UTF8 characters (camels) in opam messages.
393 Implies OPAMUTF8. This is set by default on OSX only.
394 OPAMVAR_var overrides the contents of the variable var when
396 substituting `%{var}%` strings in `opam` files.
397 OPAMVAR_package_var overrides the contents of the variable package:var
399 when substituting `%{package:var}%` strings in `opam` files.
400 OPAMVERBOSE see option `--verbose'.
402 OPAMYES see option `--yes'.
404
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 0 Success, or true for boolean queries.
411 1 False. Returned when a boolean return value is expected, e.g. when
413 running with --check, or for queries like opam lint.
414 2 Bad command-line arguments, or command-line arguments pointing to
416 an invalid context (e.g. file not following the expected format).
417 5 Not found. You requested something (package, version, repository,
419 etc.) that couldn't be found.
420 10 Aborted. The operation required confirmation, which wasn't given.
422 15 Could not acquire the locks required for the operation.
424 20 There is no solution to the user request. This can be caused by
426 asking to install two incompatible packages, for example.
427 30 Error in package definition, or other metadata files. Using
429 --strict raises this error more often.
430 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 40 Sync error. Could not fetch some remotes from the network. This can
436 be a partial error.
437 50 Configuration error. Opam or system configuration doesn't allow
439 operation, and needs fixing.
440 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 99 Internal error. Something went wrong, likely due to a bug in opam
446 itself.
447 130 User interrupt. SIGINT was received, generally due to the user
449 pressing Ctrl-C.
450
452 See https://opam.ocaml.org/doc.
453
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 Ralf Treinen <ralf.treinen@pps.jussieu.fr>
464 Frederic Tuong <tuong@users.gforge.inria.fr>
465
467 Check bug reports at https://github.com/ocaml/opam/issues.
468Opam 2.0.1 opam-pin(1)