1ocamlfind(1) General Commands Manual ocamlfind(1)
2
6 ocamlfind - [Command-line interface of the Package manager]
7
9 ocamlfind query [-help | other options] package_name ...
10 or: ocamlfind ocamlc [-help | other options] file ...
11 or: ocamlfind ocamlcp [-help | other options] file ...
12 or: ocamlfind ocamlmktop [-help | other options] file ...
13 or: ocamlfind ocamlopt [-help | other options] file ...
14 or: ocamlfind ocamldoc [-help | other options] file ...
15 or: ocamlfind ocamldep [-help | other options] file ...
16 or: ocamlfind ocamlbrowser [-help | other options]
17 or: ocamlfind install [-help | other options] package_name file ...
18 or: ocamlfind remove [-help | other options] package_name
19 or: ocamlfind list [-describe]
20 or: ocamlfind printconf [ variable ]
21 or: ocamlfind package/command arg ...
22 Optional toolchain selection by:
24 ocamlfind -toolchain name ...
25
27 Synopsis
28 ocamlfind query [ -predicates p |
29 -format f |
30 -long-format | -l |
31 -i-format |
32 -l-format |
33 -a-format |
34 -o-format |
35 -p-format |
36 -prefix p |
37 -separator s |
38 -suffix s |
39 -descendants | -d |
40 -recursive | -r ] package ...
41 Description
43 This command looks packages up, sorts them optionally, and prints
44 attributes of them. If the option -recursive (short: -r) is not speci‐
45 fied, exactly the packages given on the command line are looked up; if
46 -recursive is present, the packages and all their ancestors, or if
47 -descendants (short: -d) is present, too, all their descendants are
48 printed.
49 Package lookup and the selection of the attributes of the packages can
51 be modified by specifying predicates; without a -predicates option the
52 empty set of predicates is used. Note that even the lookup is influ‐
53 enced by the set of actual predicates as the "requires" variables may
54 be conditional.
55 What is printed about a package depends on the specified format; there
57 are a number of options that modify the format. Some formats denote
58 sets of values (such as -format %a), in which case multiple output
59 records are printed for every package. (It is even possible to specify
60 formats denoting the Cartesian product of sets, such as -format %a%o,
61 but this does not make sense.) Before the first output record the pre‐
62 fix is printed, and the suffix after the last record. Between two
63 records the separator is printed.
64 Options
66 -predicates p
67 Sets the set of actual predicates. The argument p is a list of
69 predicate names separated by commas and/or whitespace. If mul‐
70 tiple -predicates options are given, the union of all specified
71 sets is effectively used.
72 -format f
74 Sets the format to the string f. Characters preceded by a per‐
76 cent sign are interpreted as placeholders; all other characters
77 mean themselves. The defined placeholders are listed below.
78 The default format is "%d".
79 -long-format or -l
81 Sets the format such that all relevant variables are printed.
83 -i-format
85 Same as -format "-I %d", i.e. directory options for ocamlc are
87 printed.
88 -l-format
90 Same as -format "-ccopt -L%d", i.e. directory options for the
92 linker backend are printed.
93 -a-format
95 Same as -format "%a", i.e. archive file names are printed.
97 -o-format
99 Same as -format "%o", i.e. linker options are printed.
101 -p-format
103 Same as -format "%p", i.e. package names are printed.
105 -prefix p
107 Sets the prefix that is printed before the first output record
109 to the given string. The default prefix is the empty string.
110 -suffix s
112 Sets the suffix that is printed after the last output record to
114 the given string. The default suffix is the empty string.
115 -separator s
117 Sets the separator that is printed between output records to
119 the given string. The default separator is a linefeed character.
120 -recursive or -r
122 Not only the packages given on the command line are queried but
124 also all ancestors or descendants. If the option -descendants is
125 specified, too, the descendants are printed, otherwise the
126 ancestors. The packages are topologically sorted.
127 -descendants -d
129 Instead of the ancestors the descendants of the given packages
131 are queried. This option implies -recursive.
132 Placeholders meaningful in the -format option
134 %%
135 Replaced by a single percent sign
137 %p
139 Replaced by the package name
141 %d
143 Replaced by the package directory
145 %D
147 Replaced by the package description
149 %v
151 Replaced by the version string
153 %a
155 Replaced by the archive filename. If there is more than one ar‐
157 chive, a separate output record is printed for every archive.
158 %A
160 Replaced by the list of archive filenames.
162 %o
164 Replaced by one linker option. If there is more than one
166 option, a separate output record is printed for every option.
167 %O
169 Replaced by the list of linker options.
171 %(property)
173 Replaced by the value of the property named in parentheses, or
175 the empty string if not defined.
176
178 Synopsis
179 ocamlfind ( ocamlc | ocamlcp | ocamlopt | ocamlmktop )
180 [ -package package-name-list |
181 -linkpkg |
182 -predicates pred-name-list |
183 -dontlink package-name-list |
184 -syntax pred-name-list |
185 -ppopt camlp4-arg |
186 -dllpath-pkg package-name-list |
187 -dllpath-all |
188 -passopt arg |
189 standard-option ]
190 file ...
191 Description
193 These subcommands are drivers for the compilers with the same names,
194 i.e. "ocamlfind ocamlc" is a driver for "ocamlc", and so on. The sub‐
195 commands understand all documented options of the compilers (here
196 called standard-options), but also a few more options. If these subcom‐
197 mands are invoked only with standard options, they behave as if the
198 underlying compiler had been called directly. The extra options modify
199 this.
200 Internally, these subcommands transform the given list of options and
202 file arguments into an invocation of the driven compiler. This trans‐
203 formation only adds options and files, and the relative order of the
204 options and files passed directly is unchanged.
205 If there are -package options, additional directory search specifiers
207 will be included ("-I", and "-ccopt -I"), such that files of all named
208 packages and all ancestors can be found.
209 The -linkpkg option causes that the packages listed in the -package
211 options and all necessary ancestors are linked in. This means that the
212 archive files implementing the packages are inserted into the list of
213 file arguments.
214 As the package database is queried a set of predicates is needed. Most
216 predicates are set automatically, see below, but additional predicates
217 can be given by a -predicates option.
218 If there is a -syntax option, the drivers assume that a preprocessor is
220 to be used. In this case, the preprocessor command is built first in a
221 preprocessor stage, and this command is passed to the compiler using
222 the -pp option. The set of predicates in the preprocessor stage is dif‐
223 ferent from the set in the compiler/linker stage.
224 Options for compiling and linking
226 Here, only the additional options not interpreted by the compiler but
227 by the driver itself, and options with additional effects are
228 explained. Some options are only meaningful for the preprocessor call,
229 and are explained below.
230 -package package-name-list
232 Adds the listed package names to the set of included packages.
234 The package names may be separated by commas and/or whitespace.
235 In the transformed command, for every package of the set of
236 included packages and for any ancestor a directory search option
237 is inserted after the already given options. This means that
238 "-I" and "-ccopt -I" options are added for every package direc‐
239 tory.
240 -linkpkg
242 Causes that in the transformed command all archives of the
244 packages specified by -packages and all their ancestors are
245 added to the file arguments. More precisely, these archives are
246 inserted before the first given file argument. Furthermore,
247 "-ccopt -L" options for all package directories, and the linker
248 options of the selected packages are added, too. Note that the
249 archives are inserted in topological order while the linker
250 options are added in reverse toplogical order.
251 -predicates pred-name-list
253 Adds the given predicates to the set of actual predicates. The
255 predicates must be separated by commas and/or whitespace.
256 -dontlink package-name-list
258 This option modifies the behaviour of -linkpkg. Packages speci‐
260 fied here and all ancestors are not linked in. Again the pack‐
261 ages are separated by commas and/or whitespace.
262 -dllpath-pkg package-name-list
264 For these packages -dllpath options are added to the compiler
266 command. This may be useful when the ld.conf file is not prop‐
267 erly configured.
268 -dllpath-all
270 For all linked packages -dllpath options are added to the com‐
272 piler command. This may be useful when the ld.conf file is not
273 properly configured.
274 -passopt arg
276 The argument arg is passed directly to the underlying compiler.
278 This is needed to specify undocumented compiler options.
279 -verbose
281 This standard option is interpreted by the driver, too.
283 -thread
285 This standard option causes that the predicate "mt" is added to
287 the set of actual predicates. If POSIX threads are available,
288 the predicate "mt_posix" is selected, too. If only VM threads
289 are available, the predicate "mt_vm" is included into the set,
290 and the compiler switch is changed into -vmthread.
291 Note that the presence of the "mt" predicate triggers special
293 fixup of the dependency graph (see below).
294 -vmthread
296 This standard option causes that the predicates "mt" and
298 "mt_vm" are added to the set of actual predicates.
299 Note that the presence of the "mt" predicate triggers special
301 fixup of the dependency graph (see below).
302 -p
304 This standard option of "ocamlopt" causes that the predicate
306 "gprof" is added to the set of actual predicates.
307 Options for preprocessing
309 The options relevant for the preprocessor are the following:
310 -package package-name-list
312 These packages are considered while looking up the preprocessor
314 arguments. (It does not cause problems that the same -package
315 option is used for this purpose, because the set of predicates
316 is different.) It is recommended to mention at least camlp4
317 here if the preprocessor is going to be used.
318 -syntax pred-name-list
320 These predicates are assumed to be true in addition to the
322 standard preprocessor predicates. See below for a list.
323 -ppopt camlp4-arg
325 This argument is passed to the camlp4 call.
327 Predicates for compiling and linking
329 byte
330 The "byte" predicate means that one of the bytecode compilers is
332 used. It is automatically included into the predicate set if the
333 "ocamlc", "ocamlcp", or "ocamlmktop" compiler is used.
334 native
336 The "native" predicate means that the native compiler is used.
338 It is automatically included into the predicate set if the
339 "ocamlopt" compiler is used.
340 toploop
342 The "toploop" predicate means that the toploop is available in
344 the linked program. This predicate is only set when the toploop
345 is actually being executed, not when the toploop is created
346 (this changed in version 1.0.4 of findlib).
347 create_toploop
349 This predicate means that a toploop is being created (using
351 ocamlmktop).
352 mt
354 The "mt" predicate means that the program is multi-threaded. It
356 is automatically included into the predicate set if the -thread
357 option is given.
358 mt_posix
360 The "mt_posix" predicate means that in the case "mt" is set,
362 too, the POSIX libraries are used to implement threads.
363 "mt_posix" is automatically included into the predicate set if
364 the variable "type_of_threads" in the META description of the
365 "threads" package has the value "posix". This is normally the
366 case if "findlib" is configured for POSIX threads.
367 mt_vm
369 The "mt_vm" predicate means that in the case "mt" is set, too,
371 the VM thread emulation is used to implement multi-threading.
372 gprof
374 The "gprof" predicate means that in the case "native" is set,
376 too, the program is compiled for profiling. It is automatically
377 included into the predicate set if "ocamlopt" is used and the -p
378 option is in effect.
379 autolink
381 The "autolink" predicate means that ocamlc is able to perform
383 automatic linking. It is automatically included into the predi‐
384 cate set if ocamlc knows automatic linking (from version 3.00),
385 but it is not set if the -noautolink option is set.
386 syntax
388 This predicate is set if there is a -syntax option. It is set
390 both for the preprocessor and the compiler/linker stage, and it
391 can be used to find out whether the preprocessor is enabled or
392 not.
393 Predicates for preprocessing
395 preprocessor
396 This predicate is always set while looking up the preprocessor
398 arguments. It can be used to distinguish between the preproces‐
399 sor stage and the compiler/linker stage.
400 syntax
402 This predicate is set if there is a -syntax option. It is set
404 both for the preprocessor and the compiler/linker stage, and it
405 can be used to find out whether the preprocessor is enabled or
406 not.
407 camlp4o
409 This is the reserved predicate for the standard O'Caml syntax.
411 It can be used in the -syntax predicate list.
412 camlp4r
414 This is the reserved predicate for the revised O'Caml syntax.
416 It can be used in the -syntax predicate list.
417 Special behaviour of 'ocamlmktop'
419 As there is a special module Topfind that supports loading of packages
420 in scripts, the "ocamlmktop" subcommand can add initialization code for
421 this module. This extra code is linked into the executable if "findlib"
422 is in the set of effectively linked packages.
423 Fixup of the dependency graph for multi-threading
425 For a number of reasons the presence of the "mt" predicate triggers
426 that (1) the package "threads" is added to the list of required pack‐
427 ages and (2) the package "threads" becomes prerequisite of all other
428 packages (except of itself and a few hardcoded exceptions). The effect
429 is that the options -thread and -vmthread automatically select the
430 "threads" package, and that "threads" is inserted at the right position
431 in the package list.
432 Extended file naming
434 At a number of places one can not only refer to files by absolute or
435 relative path names, but also by extended names. These have two major
436 forms: "+name" refers to the subdirectory name of the standard library
437 directory, and "@name" refers to the package directory of the package
438 name. Both forms can be continued by a path, e.g. "@netstring/net‐
439 string_top.cma".
440 You can use extended names: (1) With -I options, (2) as normal file
442 arguments of the compiler, (3) in the "archive" property of packages.
443 How to set the names of the compiler executables
445 Normally, the O'Caml bytecode compiler can be called under the name
446 ocamlc. However, this is not always true; sometimes a different name is
447 chosen.
448 You can instruct ocamlfind to call executables with other names than
450 ocamlc, ocamlopt, ocamlmktop, and ocamlcp. If present, the environment
451 variable OCAMLFIND_COMMANDS is interpreted as a mapping from the stan‐
452 dard names to the actual names of the executables. It must have the
453 following format:
454 standardname1=actualname1 standardname2=actualname2 ...
456 Example: You may set OCAMLFIND_COMMANDS as follows:
458 OCAMLFIND_COMMANDS='ocamlc=ocamlc-3.00 ocamlopt=ocamlopt-3.00'
460 export OCAMLFIND_COMMANDS
461 Alternatively, you can change the configuration file findlib.conf.
463
465 Synopsis
466 ocamlfind ocamldep [-package package-name-list |
467 -syntax pred-name-list |
468 -ppopt camlp4-arg |
469 -passopt arg |
470 -verbose |
471 standard-option] file ...
472 Description
474 This command is a driver for the tool ocamldep of the O'Caml distribu‐
475 tion. This driver is only useful in conjunction with the preprocessor
476 camlp4; otherwise it does not provide more functions than ocamldep
477 itself.
478 Options
480 Here, only the additional options not interpreted by ocamldep but by
481 the driver itself, and options with additional effects are explained.
482 -package package-name-list
484 The packages named here are only used to look up the preproces‐
486 sor options. The package camlp4 should be specified anyway, but
487 further packages that add capabilities to the preprocessor can
488 also be passed.
489 -syntax pred-name-list
491 The predicates that are in effect during the look-up of the pre‐
493 processor options. At least, either camlp4o (selecting the nor‐
494 mal syntax), or camlp4r (selecting the revised syntax) should be
495 specified.
496 -ppopt camlp4-arg
498 An option that is passed through to the camlp4 call.
500 -passopt arg
502 An option that is passed through to the ocamldep call.
504 -verbose
506 Displays the resulting ocamldep command (for debugging)
508 Example
510 A typical way of using this driver:
511 ocamlfind ocamldep -package camlp4,xstrp4 -syntax camlp4r file1.ml file2.ml
513 This command outputs the dependencies of file1.ml and file2.ml,
514 although these modules make use of the syntax extensions provided by
515 xstrp4 and are written in revised syntax.
516
518 Synopsis
519 ocamlfind ocamlbrowser [-package package-name-list |
520 -all |
521 -passopt arg ]
522 Description
524 This driver calls the ocamlbrowser with package options. With -package,
525 the specified packages are included into the search path of the
526 browser, and the modules of these packages become visible (in addition
527 to the standard library). The option -all causes that all packages are
528 selected that are managed by findlib.
529 As for other drivers, the option -passopt can be used to pass arguments
531 directly to the ocamlbrowser program.
532
534 Synopsis
535 ocamlfind ocamldoc
536 [ -package package-name-list |
537 -predicates pred-name-list |
538 -syntax pred-name-list |
539 -ppopt camlp4-arg |
540 standard-option ]
541 file ...
542 Description
544 This subcommand is a driver for ocamldoc. It undestands all options
545 ocamldoc supports plus the mentioned findlib options. Basically, the
546 -package options are translated into -I options, and the selected syn‐
547 tax options are translated into camlp4 options.
548 Options
550 Here, only the additional options not interpreted by ocamldep but by
551 the driver itself, and options with additional effects are explained.
552 -package package-name-list
554 Adds the listed package names to the set of included packages.
556 The package names may be separated by commas and/or whitespace.
557 In the transformed command, for every package of the set of
558 included packages and for any ancestor a directory search option
559 is inserted after the already given options. This means that
560 "-I" options are added for every package directory.
561 -predicates pred-name-list
563 Adds the given predicates to the set of actual predicates. The
565 predicates must be separated by commas and/or whitespace.
566 -syntax pred-name-list
568 The predicates that are in effect during the look-up of the pre‐
570 processor options. At least, either camlp4o (selecting the nor‐
571 mal syntax), or camlp4r (selecting the revised syntax) should be
572 specified.
573 -ppopt camlp4-arg
575 An option that is passed through to the camlp4 call.
577
579 Synopsis
580 ocamlfind install [ -destdir directory ]
581 [ -metadir directory ]
582 [ -ldconf path ]
583 [ -dont-add-directory-directive ]
584 [ -patch-version string ]
585 [ -patch-rmpkg name ]
586 [ -patch-archives ]
587 [ -dll ] [ -nodll ] [ -optional ]
588 package_name file ...
589 Description
591 This subcommand installs a new package either at the default location
592 (see the variable destdir of findlib.conf), or in the directory speci‐
593 fied by the -destdir option. This means that a new package directory is
594 created and that the files on the command line are copied to this
595 directory. It is required that a META file is one of the files copied
596 to the target directory.
597 Note that package directories should be flat (no subdirectories).
599 Existing packages are never overwritten.
600 It is possible to have a separate directory for all the META files. If
602 you want that, you have either to set the variable metadir of find‐
603 lib.conf, or to specify the -metadir option. In this case, the file
604 called META is copied to the specified directory and renamed to META.p
605 (where p is the package name), while all the other files are copied to
606 the package directory as usual. Furthermore, the META file is modified
607 such that the directory variable contains the path of the package
608 directory.
609 The option -dont-add-directory-directive prevents the installer from
611 adding a directory variable.
612 If there are files ending in the suffixes .so or .dll, the package
614 directory will be added to the DLL configuration file ld.conf, such
615 that the dynamic loader can find the DLL. The location of this file can
616 be overriden by the -ldconf option. To turn this feature off, use
617 "-ldconf ignore"; this causes that the ld.conf file is not modified.
618 However, if there is a stublibs directory in site-lib, the DLLs are not
620 installed in the package directory, but in this directory that is
621 shared by all packages that are installed at the same location. In this
622 case, the configuration file ld.conf is not modified, so you do not
623 need to say "-ldconf ignore" if you prefer this style of installation.
624 The options -dll and -nodll can be used to control exactly which files
626 are considered as DLLs and which not. By default, the mentioned suffix
627 rule is in effect: files ending in ".so" (Unix) or ".dll" (Windows) are
628 DLLs. The switch -dll changes this, and all following files are consid‐
629 ered as DLLs, regardless of their suffix. The switch -nodll expresses
630 that the following files are not DLLs, even if they have a DLL-like
631 suffix. For example, in the following call the files f1 and f2 are han‐
632 dled by the suffix rule; f3 and f4 are DLLs anyway; and f5 and f6 are
633 not DLLs:
634 ocamlfind install p f1 f2 -dll f3 f4 -nodll f5 f6
636 The switch -optional declares that all following files are optional,
638 i.e. the command will not fail if files do not exist.
639 The -patch options may be used to change the contents of the META files
641 while it is being installed. The option -patch-version changes the con‐
642 tents of the top-level "version" variable. The option -patch-rmpkg
643 removes the given subpackage. The option -patch-archives is experimen‐
644 tal, in particular it removes all non-existing files from "archive"
645 variables, and even whole subpackages if the archives are missing.
646
648 Synopsis
649 ocamlfind remove [ -destdir directory ]
650 [ -metadir directory ]
651 [ -ldconf path ]
652 package_name
653 Description
655 The package will removed if it is installed at the default location
656 (see the variable destdir of findlib.conf). If the package resides at a
657 different location, it will not be removed by default; however, you can
658 pass an alternate directory for packages by the -destdir option. (This
659 must be the same directory as specified at installation time.)
660 Note that package directories should be flat (no subdirectories); this
662 subcommand cannot remove deep package directories.
663 If you have a separate directory for META files, you must either con‐
665 figure this directory by the metadir variable of findlib.conf, or by
666 specifying the -metadir option.
667 The command does not fail if the package and/or the META file cannot be
669 located. You will get a warning only in this case.
670 If the package directory is mentioned in the ld.conf configuration file
672 for DLLs, it will be tried to remove this entry from the file. The
673 location of this file can be overriden by the -ldconf option. To turn
674 this feature off, use "-ldconf ignore"; this causes that the ld.conf
675 file is not modified.
676 If there is a stublibs directory, it is checked whether the package
678 owns any of the files in this directory, and the owned files will be
679 deleted.
680
682 Synopsis
683 ocamlfind list [-describe]
684 Description
686 This command lists all packages in the search path. The option
687 -describe outputs the package descriptions, too.
688
690 Synopsis
691 ocamlfind printconf [ conf | path | destdir | metadir | stdlib | ldconf ]
692 Description
694 This command prints the effective configuration after reading the con‐
695 figuration file, and after applying the various environment variables
696 overriding settings. When called without arguments, the command prints
697 all configuration options in a human-readable form. When called with an
698 argument, only the value of the requested option is printed without
699 explaining texts:
700 conf
702 Prints the location of the configuration file findlib.conf
704 path
706 Prints the search path for packages. The members of the path
708 are separated by linefeeds.
709 destdir
711 Prints the location where package are installed and removed by
713 default.
714 metadir
716 Prints the location where META files are installed and removed
718 (if the alternative layout is used).
719 stdlib
721 Prints the location of the standard library.
723 ldconf
725 Prints the location of the ld.conf file
727
729 Synopsis
730 ocamlfind pkg/cmd argument ...
731 Description
733 This subcommand is useful to call programs that are installed in pack‐
734 age directories. It looks up the directory for pkg and calls the com‐
735 mand named cmd in this directory. The remaining arguments are passed to
736 this command.
737 argv(0) contains the absolute path to the command, and argv(1) and the
739 following argv entries contain the arguments. The working directory is
740 not changed.
741 Example: To call the program "x" that is installed in package "p", with
743 arguments "y" and "z", run:
744 ocamlfind p/x y z
746
748 The configuration file and environment variables are documented in the
749 manual page for findlib.conf.
750
752 Synopsis
753 ocamlfind -toolchain name ...
754 Description
756 The -toolchain option can be given before any other command, e.g.
757 ocamlfind -toolchain foo ocamlc -c file.ml
759 compiles file.ml with toolchain "foo". By selecting toolchains one can
760 switch to different command sets. For instance, the toolchain "foo" may
761 consist of a patched ocamlc compiler. See findlib.conf how to config‐
762 ure toolchains.
763User Manual The findlib package manager for OCaml ocamlfind(1)