ocamlfind query [ -predicates c
pc
  | c




                  -format c
fc
 |c




                  -long-format | -l |c




                  -i-format |c




                  -l-format | c




                  -a-format |c




                  -o-format | c




                  -p-format |c




                  -prefix c
pc
 |c




                  -separator c
sc
 | c




                  -suffix c
sc
 |c




                  -descendants | -d |c




                  -recursive  | -r ] c
packagec
 ...c

This command looks packages up, sorts them optionally, andc prints attributes of them. If the option -recursive (short: -r) is notc specified, exactly the packages given on the command line are lookedc up; if -recursive is present, the packages and all their ancestors, orc if -descendants (short: -d) is present, too, all their descendants are printed.c

Package lookup and the selection of the attributes of the packages canc be modified by specifying predicates; without a -predicates option thec empty set of predicates is used. Note that even the lookup isc influenced by the set of actual predicates as the "requires" variablesc may be conditional.c

What is printed about a package depends on the specified format; therec are a number of options that modify the format. Some formats denotec sets of values (such as -format %a), in which case multiple outputc records are printed for every package. (It is even possible to specifyc formats denoting the Cartesian product of sets, such as -format %a%o,c but this does not make sense.) Before the first output record thec prefix is printed, and the suffix after the last record. Between twoc records the separator is printed.c

-predicates pc Sets the set of actual predicates. The argumentc pc is a list of predicate names separatedc by commas and/or whitespace. If multiple -predicates options arec given, the union of all specified sets is effectively used.c -format fc Sets the format to the stringc fc . Characters preceded by a percent signc are interpreted as placeholders; all other characters meanc themselves. The defined placeholders are listed below.c The default format is "%d".c -long-format or -lc Sets the format such that all relevant variables are printed.c -i-formatc Same as -format "-I %d", i.e. directory options for ocamlc are printed.c -l-formatc Same as -format "-ccopt -L%d", i.e. directory options for thec linker backend are printed.c -a-formatc Same as -format "%a", i.e. archive file names are printed.c -o-formatc Same as -format "%o", i.e. linker options are printed.c -p-formatc Same as -format "%p", i.e. package names are printed.c -prefix pc Sets the prefix that is printed before the first output recordc to the given string. The default prefix is the empty string.c -suffix sc Sets the suffix that is printed after the last output recordc to the given string. The default suffix is the empty string.c -separator sc Sets the separator that is printed between output records toc the given string. The default separator is a linefeed character.c -recursive or -rc Not only the packages given on the command line are queriedc but also all ancestors or descendants. If the option -descendants isc specified, too, the descendants are printed, otherwise thec ancestors. The packages are topologically sorted.c -descendants -dc Instead of the ancestors the descendants of thec given packages are queried. This option implies -recursivec .c

%%c Replaced by a single percent signc %pc Replaced by the package namec %dc Replaced by the package directoryc %Dc Replaced by the package descriptionc %vc Replaced by the version stringc %ac Replaced by the archive filename. If there is morec than one archive, a separate output record is printed for every archive.c %Ac Replaced by the list of archive filenames.c %oc Replaced by one linker option. If there is more thanc one option, a separate output record is printed for every option.c %Oc Replaced by the list of linker options.c %(c propertyc )c Replaced by the value of the property named in parentheses,c or the empty string if not defined.c

ocamlfind ( ocamlc | ocamlcp | ocamlopt | ocamlmktop )c




          [ -package c
package-name-listc
 |c




            -linkpkg |c




            -predicates c
pred-name-listc
 |c




            -dontlink c
package-name-listc
 |c




            -syntax c
pred-name-listc
 |c




            -ppopt c
camlp4-argc
 |c




            -dllpath-pkg c
package-name-listc
 |c




            -dllpath-all |c




            -passopt c
argc
 |c




            c
standard-optionc
 ]c




          c
filec
 ...c

These subcommands are drivers for the compilers with the same names,c i.e. "ocamlfind ocamlc" is a driver for "ocamlc", and so on. Thec subcommands understand all documented options of the compilers (herec called standard-optionsc ), but also a fewc more options. If these subcommands are invoked only with standardc options, they behave as if the underlying compiler had been calledc directly. The extra options modify this.c

Internally, these subcommands transform the given list of options andc file arguments into an invocation of the driven compiler. Thisc transformation only adds options and files, and the relative order ofc the options and files passed directly is unchanged.c

If there are -package options, additional directory search specifiersc will be included ("-I", and "-ccopt -I"), such that files of all namedc packages and all ancestors can be found.c

The -linkpkg option causes that the packages listed in the -packagec options and all necessary ancestors are linked in. This means that thec archive files implementing the packages are inserted into the list ofc file arguments.c

As the package database is queried a set of predicates is needed. Mostc predicates are set automatically, see below, but additional predicatesc can be given by a -predicates option.c

If there is a -syntaxc option, the drivers assume thatc a preprocessor is to be used. In this case, the preprocessor commandc is built first in a preprocessor stage, and this command is passed to thec compiler using the -ppc option. The set of predicatesc in the preprocessor stage is different from the set in the compiler/linkerc stage.c

Here, only the additional options not interpreted by the compiler butc by the driver itself, and options with additional effects are explained.c Some options are only meaningful for the preprocessor call, and arec explained below.c

-package package-name-listc Adds the listed package names to the set of includedc packages. The package names may be separated by commas and/orc whitespace. In the transformed command, for every package of the setc of included packages and for any ancestor a directory search optionc is inserted after the already given options. This means thatc "-I" and "-ccopt -I" options are added for every package directory.c -linkpkgc Causes that in the transformed command all archivesc of the packages specified by -packages and all their ancestors arec added to the file arguments. More precisely, these archives arec inserted before the first given file argument. Furthermore, "-ccoptc -L" options for all package directories, and the linker options ofc the selected packages are added, too. Note that the archives arec inserted in topological order while the linker options are added inc reverse toplogical order.c -predicates pred-name-listc Adds the given predicates to the set of actualc predicates. The predicates must be separated by commas and/orc whitespace. -dontlink package-name-listc This option modifies the behaviour ofc -linkpkg. Packages specified here and all ancestors are not linkedc in. Again the packages are separated by commas and/or whitespace.c -dllpath-pkg package-name-listc For these packages -dllpathc optionsc are added to the compiler command. This may be useful when the ld.confc file is not properly configured.c -dllpath-allc For all linked packages -dllpathc optionsc are added to the compiler command. This may be useful when the ld.confc file is not properly configured.c -passopt argc The argument argc isc passed directly to the underlying compiler. This is needed toc specify undocumented compiler options.c -verbosec This standard option is interpreted by the driver, too.c -threadc This standard option causes that the predicate "mt"c is added to the set of actual predicates. If POSIX threads are available,c the predicate "mt_posix" is selected, too. If only VM threads arec available, the predicate "mt_vm" is included into the set, and thec compiler switch is changed into -vmthread.c

Note that the presence of the "mt" predicate triggers specialc fixup of the dependency graph (see below).c -vmthreadc This standard option causes that the predicates "mt"c and "mt_vm" are added to the set of actual predicates.c

Note that the presence of the "mt" predicate triggers specialc fixup of the dependency graph (see below).c -pc This standard option of "ocamlopt" causes that thec predicate "gprof" is added to the set of actual predicates.c

The options relevant for the preprocessor are the following:c

-package package-name-listc These packages are considered while looking up thec preprocessor arguments. (It does not cause problems that the samec -package option is used for this purpose, because the set of predicatesc is different.) It is recommended to mention at least camlp4c here if the preprocessor is going to be used.c -syntax pred-name-listc These predicates are assumed to be true in additionc to the standard preprocessor predicates. See below for a list.c -ppopt camlp4-argc This argument is passed to the camlp4 call.c

bytec The "byte" predicate means that one of the bytecode compilers isc used. It is automatically included into the predicate set if thec "ocamlc", "ocamlcp", or "ocamlmktop" compiler is used.c nativec The "native" predicate means that the native compiler is used. It isc automatically included into the predicate set if the "ocamlopt"c compiler is used.c toploopc The "toploop" predicate means that the toploop is available in thec linked program. This predicate is only set when the toploop is actuallyc being executed, not when the toploop is created (this changed in versionc 1.0.4 of findlib).c create_toploopc This predicate means that a toploop is being created (usingc ocamlmktop).c mtc The "mt" predicate means that the program is multi-threaded. It isc automatically included into the predicate set if the -thread option isc given. mt_posixc The "mt_posix" predicate means that in the case "mt" is set, too, thec POSIX libraries are used to implement threads. "mt_posix" is automaticallyc included into the predicate set if the variable "type_of_threads" in thec META description of the "threads" package has the value "posix". Thisc is normally the case if "findlib" is configured for POSIX threads.c mt_vmc The "mt_vm" predicate means that in the case "mt" is set, too, thec VM thread emulation is used to implement multi-threading.c gprofc The "gprof" predicate means that in the case "native" is set, too, thec program is compiled for profiling. It is automatically included intoc the predicate set if "ocamlopt" is used and the -p option is inc effect.c autolinkc The "autolink" predicate means that ocamlc is able to perform automaticc linking. It is automatically included into the predicate set if ocamlcc knows automatic linking (from version 3.00), but it is not set if thec -noautolink option is set.c syntaxc This predicate is set if there is a -syntaxc option. It is set both for the preprocessor and the compiler/linker stage,c and it can be used to find out whether the preprocessor is enabled or not.c

preprocessorc This predicate is always set while looking up thec preprocessor arguments. It can be used to distinguish between thec preprocessor stage and the compiler/linker stage.c syntaxc This predicate is set if there is a -syntaxc option. It is set both for the preprocessor and the compiler/linker stage,c and it can be used to find out whether the preprocessor is enabled or not.c camlp4oc This is the reserved predicate for the standard O'Caml syntax.c It can be used in the -syntaxc predicate list.c camlp4rc This is the reserved predicate for the revised O'Caml syntax.c It can be used in the -syntaxc predicate list.c

As there is a special module Topfindc thatc supports loading of packages in scripts, the "ocamlmktop" subcommandc can add initialization code for this module. This extra code isc linked into the executable if "findlib" is in the set of effectivelyc linked packages.

For a number of reasons the presence of the "mt" predicate triggersc that (1) the package "threads" is added to the list of required packagesc and (2) the package "threads" becomes prerequisite of all other packagesc (except of itself and a few hardcoded exceptions). The effect is thatc the options -thread and -vmthread automatically select the "threads"c package, and that "threads" is inserted at the right position in thec package list.c

At a number of places one can not only refer to files by absolutec or relative path names, but also by extended names. These have twoc major forms: "+c namec "c refers to the subdirectory namec of thec standard library directory, and "@c namec "c refers to the package directory of the package namec .c Both forms can be continued by a path, e.g. "@netstring/netstring_top.cma".c

You can use extended names: (1) With -Ic options,c (2) as normal file arguments of the compiler, (3) in the "archive" property of packages.c

Normally, the O'Caml bytecode compiler can be called under the namec ocamlcc . However, this is not always true; sometimes ac different name is chosen.c

You can instruct ocamlfind to call executables with other names thanc ocamlcc , ocamloptc ,c ocamlmktopc , and ocamlcpc . If present,c the environment variable OCAMLFIND_COMMANDSc is interpretedc as a mapping from the standard names to the actual names of the executables. Itc must have the following format:c

standardname1c
=c
actualname1c
 c
standardname2c
=c
actualname2c
 ...c

Example: You may set OCAMLFIND_COMMANDSc as follows:c

OCAMLFIND_COMMANDS='ocamlc=ocamlc-3.00 ocamlopt=ocamlopt-3.00'c




export OCAMLFIND_COMMANDSc

Alternatively, you can change the configuration filec findlib.confc .c

ocamlfind ocamldep [-package c
package-name-listc
 |c




                    -syntax c
pred-name-listc
 |c




                    -ppopt c
camlp4-argc
 |c




                    -passopt c
argc
 |c




                    -verbose |c




                    c
standard-optionc
] c
filec
 ...c

This command is a driver for the tool ocamldepc of thec O'Caml distribution. This driver is only useful in conjunction withc the preprocessor camlp4; otherwise it does not provide more functionsc than ocamldepc itself.c

Here, only the additional options not interpreted by ocamldepc butc by the driver itself, and options with additional effects are explained.c

-package package-name-listc The packages named here are only used to look up thec preprocessor options. The package camlp4c should bec specified anyway, but further packages that add capabilities to thec preprocessor can also be passed.c -syntax pred-name-listc The predicates that are in effect during the look-upc of the preprocessor options. At least, either camlp4oc (selecting the normal syntax), or camlp4rc (selectingc the revised syntax) should be specified.c -ppopt camlp4-argc An option that is passed through to the camlp4 call.c -passopt argc An option that is passed through to the ocamldep call.c -verbosec Displays the resulting ocamldep command (for debugging)c

A typical way of using this driver:c

ocamlfind ocamldep -package camlp4,xstrp4 -syntax camlp4r file1.ml file2.mlc

ocamlfind ocamlbrowser [-package c
package-name-listc
 |c




                        -all |c




                        -passopt c
argc
 ]c

This driver calls the ocamlbrowserc with package options.c With -packagec , the specified packages are included intoc the search path of the browser, and the modules of these packages becomec visible (in addition to the standard library). The option -allc causes that all packages are selected that are managed by findlib.c

As for other drivers, the option -passoptc can be usedc to pass arguments directly to the ocamlbrowserc program.c

ocamlfind ocamldocc




          [ -package c
package-name-listc
 |c




            -predicates c
pred-name-listc
 |c




            -syntax c
pred-name-listc
 |c




            -ppopt c
camlp4-argc
 |c




            c
standard-optionc
 ]c




          c
filec
 ...c

This subcommand is a driver for ocamldoc. It undestands all optionsc ocamldoc supports plus the mentioned findlib options. Basically,c the -package options are translated into -I options, and the selectedc syntax options are translated into camlp4 options.c

Here, only the additional options not interpreted by ocamldepc butc by the driver itself, and options with additional effects are explained.c

-package package-name-listc Adds the listed package names to the set of includedc packages. The package names may be separated by commas and/orc whitespace. In the transformed command, for every package of the setc of included packages and for any ancestor a directory search optionc is inserted after the already given options. This means thatc "-I" options are added for every package directory.c -predicates pred-name-listc Adds the given predicates to the set of actualc predicates. The predicates must be separated by commas and/orc whitespace. -syntax pred-name-listc The predicates that are in effect during the look-upc of the preprocessor options. At least, either camlp4oc (selecting the normal syntax), or camlp4rc (selectingc the revised syntax) should be specified.c -ppopt camlp4-argc An option that is passed through to the camlp4 call.c

ocamlfind install [ -destdir c
directoryc
 ]c




                  [ -metadir c
directoryc
 ]c




                  [ -ldconf c
pathc
 ]c




                  [ -dont-add-directory-directive ]c




                  [ -patch-version c
stringc
 ]c




                  [ -patch-rmpkg c
namec
 ]c




                  [ -patch-archives ]c




                  [ -dll ] [ -nodll ] [ -optional ]c




                  c
package_namec
 c
filec
 ...c

This subcommand installs a new package either at the default locationc (see the variable destdirc ofc findlib.confc ), or in the directoryc specified by the -destdir option. Thisc means that a new package directory is created and that the files onc the command line are copied to this directory. It is required that ac METAc file is one of the files copied to the targetc directory.c

Note that package directories should be flat (noc subdirectories). Existing packages are never overwritten.c

It is possible to have a separate directory for all the META files. Ifc you want that, you have either to set the variablec metadirc of findlib.confc , or to specify thec -metadir option. In this case, the file called META is copied to thec specified directory and renamed to META.p (where p is the packagec name), while all the other files are copied to the packagec directory as usual. Furthermore, the META file is modified such that thec directoryc variable contains the path of the packagec directory.

The option -dont-add-directory-directive prevents the installer fromc adding a directoryc variable.c

If there are files ending in the suffixes .soc orc .dllc , the package directory will be added to thec DLL configuration file ld.confc , such that the dynamicc loader can find the DLL. The location of this file can be overriden byc the -ldconf option. To turn this feature off, use "-ldconf ignore";c this causes that the ld.conf file is not modified.c

However, if there is a stublibs directory in site-lib, the DLLs are notc installed in the package directory, but in this directory that isc shared by all packages that are installed at the same location.c In this case, the configuration file ld.confc isc not modified, so you do not need to say "-ldconf ignore" if youc prefer this style of installation.c

The options -dll and -nodll can be used to control exactly which filesc are considered as DLLs and which not. By default, the mentionedc suffix rule is in effect: files ending in ".so" (Unix) or ".dll"c (Windows) are DLLs. The switch -dll changes this, and all followingc files are considered as DLLs, regardless of their suffix. The switch -nodll expresses that the following files are not DLLs, even if theyc have a DLL-like suffix. For example, in the following call the filesc f1 and f2 are handled by the suffix rule; f3 and f4 are DLLs anyway;c and f5 and f6 are not DLLs:c

ocamlfind install p f1 f2 -dll f3 f4 -nodll f5 f6c

The switch -optional declares that all following files are optional,c i.e. the command will not fail if files do not exist.c

The -patch options may be used to change the contents of the META filesc while it is being installed. The option -patch-version changes thec contents of the top-level "version" variable. The option -patch-rmpkgc removes the given subpackage. The option -patch-archives is experimental,c in particular it removes all non-existing files from "archive" variables,c and even whole subpackages if the archives are missing.c

ocamlfind remove [ -destdir c
directoryc
 ]c




                 [ -metadir c
directoryc
 ]c




                 [ -ldconf c
pathc
 ]c




                 c
package_namec

The package will removed if it is installed at the default location (see the variable destdirc ofc findlib.confc ). If the packagec resides at a different location, it will not be removed by default;c however, you can pass an alternate directory for packages by thec -destdir option. (This must be the same directory as specified atc installation time.)c

Note that package directories should be flat (no subdirectories); thisc subcommand cannot remove deep package directories.

If you have a separate directory for META files, you must eitherc configure this directory by the metadirc variablec of findlib.confc , or by specifyingc the -metadir option.c

The command does not fail if the package and/or the METAc file cannot be located. You will get a warning only in this case.c

If the package directory is mentioned in the ld.confc configuration file for DLLs, it will be tried to remove this entryc from the file. The location of this file can be overriden byc the -ldconf option. To turn this feature off, use "-ldconf ignore";c this causes that the ld.conf file is not modified.c

If there is a stublibs directory, it is checked whether the packagec owns any of the files in this directory, and the owned files willc be deleted.c

ocamlfind list [-describe]c

This command lists all packages in the search path. The option -describec outputs the package descriptions, too.c

ocamlfind printconf [ conf | path | destdir | metadir | stdlib | ldconf ]c

This command prints the effective configuration after reading thec configuration file, and after applying the various environmentc variables overriding settings. When called without arguments, the commandc prints all configuration options in a human-readable form. When calledc with an argument, only the value of the requested option is printed withoutc explaining texts:c

confc Prints the location of the configuration file findlib.confc pathc Prints the search path for packages. The members of thec path are separated by linefeeds.c destdirc Prints the location where package are installed andc removed by default.c metadirc Prints the location where META files are installed andc removed (if the alternative layout is used).c stdlibc Prints the location of the standard library.c ldconfc Prints the location of the ld.conf filec

ocamlfind c
pkgc
/c
cmdc
 c
argumentc
 ...c

This subcommand is useful to call programs that are installed inc package directories. It looks up the directory for pkgc and calls the command namedc cmdc in this directory. The remaining argumentsc are passed to this command.c

argv(0) contains the absolute path to the command, and argv(1) andc the following argv entries contain the arguments. The working directoryc is not changed.c

Example: To call the program "x" that is installed in package "p",c with arguments "y" and "z", run:c

ocamlfind p/x y zc

ocamlfind -toolchain c
namec
 ...c

The -toolchain option can be given before any other command,c e.g.c

ocamlfind -toolchain foo ocamlc -c file.mlc