ocamlfind(1)

NAME
ocamlfind - [Command-line interface of the Package manager]

SYNOPSIS
       ocamlfind query [-help | other options]
package_name
 ...

   or: ocamlfind ocamlc [-help | other options]
file
 ...

   or: ocamlfind ocamlcp [-help | other options]
file
 ...

   or: ocamlfind ocamlmktop [-help | other options]
file
 ...

   or: ocamlfind ocamlopt [-help | other options]
file
 ...

   or: ocamlfind ocamldoc [-help | other options]
file
 ...

   or: ocamlfind ocamldep [-help | other options]
file
 ...

   or: ocamlfind ocamlmklib [-help | other options]
file
 ...

   or: ocamlfind ocamlbrowser [-help | other options]

   or: ocamlfind install [-help | other options]
package_name

file
 ...

   or: ocamlfind remove [-help | other options]
package_name

   or: ocamlfind lint
META

   or: ocamlfind list [-describe]

   or: ocamlfind printconf [ variable ]

   or: ocamlfind
package
/
command

arg
 ...

Optional toolchain selection by:

  ocamlfind -toolchain
name
 ...

THE 'query' SUBCOMMAND

  Synopsis
ocamlfind query [ -predicates
p
  |

                  -format
f
 |

                  -long-format | -l |

                  -i-format |

                  -l-format |

                  -a-format |

                  -o-format |

                  -p-format |

                  -prefix
p
 |

                  -separator
s
 |

                  -suffix
s
 |

                  -pp |

                  -descendants | -d |

                  -recursive  | -r ]
package
 ...

  Description
This command looks packages up, sorts them optionally, andprints attributes of them. If the option -recursive (short: -r) is notspecified, exactly the packages given on the command line are lookedup; if -recursive is present, the packages and all their ancestors, orif -descendants (short: -d) is present, too, all their descendants are printed.

Package lookup and the selection of the attributes of the packages canbe modified by specifying predicates; without a -predicates option theempty set of predicates is used. Note that even the lookup isinfluenced by the set of actual predicates as the "requires" variablesmay be conditional.

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

  Options
    -predicates p

    Sets the set of actual predicates. The argumentpis a list of predicate names separatedby commas and/or whitespace. If multiple -predicates options aregiven, the union of all specified sets is effectively used.

    -format f

    Sets the format to the stringf. Characters preceded by a percent signare interpreted as placeholders; all other characters meanthemselves. The defined placeholders are listed below.The default format is "%d".

    -long-format or -l

    Sets the format such that all relevant variables are printed.

    -i-format

    Same as -format "-I %d", i.e. directory options for ocamlc are printed.

    -l-format

    Same as -format "-ccopt -L%d", i.e. directory options for thelinker backend are printed.

    -a-format

    Same as -format "%+a", i.e. archive file names are printed.

    -o-format

    Same as -format "%o", i.e. linker options are printed.

    -p-format

    Same as -format "%p", i.e. package names are printed.

    -prefix p

    Sets the prefix that is printed before the first output recordto the given string. The default prefix is the empty string.

    -suffix s

    Sets the suffix that is printed after the last output recordto the given string. The default suffix is the empty string.

    -separator s

    Sets the separator that is printed between output records tothe given string. The default separator is a linefeed character.

    -recursive or -r

    Not only the packages given on the command line are queriedbut also all ancestors or descendants. If the option -descendants isspecified, too, the descendants are printed, otherwise theancestors. The packages are topologically sorted.

    -descendants -d

    Instead of the ancestors the descendants of thegiven packages are queried. This option implies -recursive.

    -pp

    Query preprocessor packages (camlp4 syntax extensions). Normallyit is not needed to set -predicates, except you need the archives (then add-predicates byte). This option implies -recursive.

  Placeholders meaningful in the -format option
    %%

    Replaced by a single percent sign

    %p

    Replaced by the package name

    %d

    Replaced by the package directory

    %m

    Replaced by the path to the META file (new since findlib-1.6)

    %D

    Replaced by the package description

    %v

    Replaced by the version string

    %a

    Replaced by the archive filename. If there is morethan one archive, a separate output record is printed for every archive.

    %+a

    Like %a, but the filenames are converted to absolutepaths ("+" and "@" notations are resolved)

    %A

    Replaced by the list of archive filenames.

    %+A

    Like %A, but the filenames are converted to absolutepaths ("+" and "@" notations are resolved)

    %o

    Replaced by one linker option. If there is more thanone option, a separate output record is printed for every option.

    %O

    Replaced by the list of linker options.

    %(property)

    Replaced by the value of the property named in parentheses,or the empty string if not defined.

THE SUBCOMMANDS 'ocamlc', 'ocamlcp', 'ocamlopt', and 'ocamlmktop'

  Synopsis
ocamlfind ( ocamlc | ocamlcp | ocamlopt | ocamlmktop )

          [ -package
package-name-list
 |

            -linkpkg |

            -predicates
pred-name-list
 |

            -dontlink
package-name-list
 |

            -syntax
pred-name-list
 |

            -ppopt
camlp4-arg
 |

            -ppxopt
package
,
arg
 |

            -dllpath-pkg
package-name-list
 |

            -dllpath-all |

            -passopt
arg
 |

            -passrest
arg...
 |

            -only-show |

standard-option
 ]

file
 ...

  Description
These subcommands are drivers for the compilers with the same names,i.e. "ocamlfind ocamlc" is a driver for "ocamlc", and so on. Thesubcommands understand all documented options of the compilers (herecalled standard-options), but also a fewmore options. If these subcommands are invoked only with standardoptions, they behave as if the underlying compiler had been calleddirectly. The extra options modify this.

Internally, these subcommands transform the given list of options andfile arguments into an invocation of the driven compiler. Thistransformation only adds options and files, and the relative order ofthe options and files passed directly is unchanged.

If there are -package options, additional directory search specifierswill be included ("-I", and "-ccopt -I"), such that files of all namedpackages and all ancestors can be found.

The -linkpkg option causes that the packages listed in the -packageoptions and all necessary ancestors are linked in. This means that thearchive files implementing the packages are inserted into the list offile arguments.

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

If there is a -syntaxoption, the drivers assume thata preprocessor is to be used. In this case, the preprocessor commandis built first in a preprocessor stage, and this command is passed to thecompiler using the -ppoption. The set of predicatesin the preprocessor stage is different from the set in the compiler/linkerstage.

  Options for compiling and linking
Here, only the additional options not interpreted by the compiler butby the driver itself, and options with additional effects are explained.Some options are only meaningful for the preprocessor call, and areexplained below.

    -package package-name-list

    Adds the listed package names to the set of includedpackages. The package names may be separated by commas and/orwhitespace. In the transformed command, for every package of the setof included packages and for any ancestor a directory search optionis inserted after the already given options. This means that"-I" and "-ccopt -I" options are added for every package directory.

    -linkpkg

    Causes that in the transformed command all archivesof the packages specified by -packages and all their ancestors areadded to the file arguments. More precisely, these archives areinserted before the first given file argument. Furthermore, "-ccopt-L" options for all package directories, and the linker options ofthe selected packages are added, too. Note that the archives areinserted in topological order while the linker options are added inreverse toplogical order.

    -predicates pred-name-list

    Adds the given predicates to the set of actualpredicates. The predicates must be separated by commas and/orwhitespace.

    -dontlink package-name-list

    This option modifies the behaviour of-linkpkg. Packages specified here and all ancestors are not linkedin. Again the packages are separated by commas and/or whitespace.

    -dllpath-pkg package-name-list

    For these packages -dllpathoptionsare added to the compiler command. This may be useful when the ld.conffile is not properly configured.

    -dllpath-all

    For all linked packages -dllpathoptionsare added to the compiler command. This may be useful when the ld.conffile is not properly configured.

    -passopt arg

    The argument argispassed directly to the underlying compiler. This is needed tospecify undocumented compiler options.

    -passrest arg...

    All following arguments arg...arepassed directly to the underlying compiler. This is needed tospecify undocumented compiler options.

    -only-show

    Only prints the constructed command (ocamlc/ocamlopt) tostdout, but does not execute the command. (This is for the unlikely eventthat you need a wrapper around ocamlfind.)

    -verbose

    This standard option is interpreted by the driver, too.

    -thread

    This standard option causes that the predicate "mt"is added to the set of actual predicates. If POSIX threads are available,the predicate "mt_posix" is selected, too. If only VM threads areavailable, the predicate "mt_vm" is included into the set, and thecompiler switch is changed into -vmthread.

    Note that the presence of the "mt" predicate triggers specialfixup of the dependency graph (see below).

    -vmthread

    This standard option causes that the predicates "mt"and "mt_vm" are added to the set of actual predicates.

    Note that the presence of the "mt" predicate triggers specialfixup of the dependency graph (see below).

    -p

    This standard option of "ocamlopt" causes that thepredicate "gprof" is added to the set of actual predicates.

  Options for preprocessing
The options relevant for the preprocessor are the following:

    -package package-name-list

    These packages are considered while looking up thepreprocessor arguments. (It does not cause problems that the same-package option is used for this purpose, because the set of predicatesis different.) It is recommended to mention at least camlp4here if the preprocessor is going to be used.

    -syntax pred-name-list

    These predicates are assumed to be true in additionto the standard preprocessor predicates. See below for a list.

    -ppopt camlp4-arg

    This argument is passed to the camlp4 call.

  Predicates for compiling and linking
    byte

    The "byte" predicate means that one of the bytecode compilers isused. It is automatically included into the predicate set if the"ocamlc", "ocamlcp", or "ocamlmktop" compiler is used.

    native

    The "native" predicate means that the native compiler is used. It isautomatically included into the predicate set if the "ocamlopt"compiler is used.

    toploop

    The "toploop" predicate means that the toploop is available in thelinked program. This predicate is only set when the toploop is actuallybeing executed, not when the toploop is created (this changed in version1.0.4 of findlib).

    create_toploop

    This predicate means that a toploop is being created (usingocamlmktop).

    mt

    The "mt" predicate means that the program is multi-threaded. It isautomatically included into the predicate set if the -thread option isgiven.

    mt_posix

    The "mt_posix" predicate means that in the case "mt" is set, too, thePOSIX libraries are used to implement threads. "mt_posix" is automaticallyincluded into the predicate set if the variable "type_of_threads" in theMETA description of the "threads" package has the value "posix". Thisis normally the case if "findlib" is configured for POSIX threads.

    mt_vm

    The "mt_vm" predicate means that in the case "mt" is set, too, theVM thread emulation is used to implement multi-threading.

    gprof

    The "gprof" predicate means that in the case "native" is set, too, theprogram is compiled for profiling. It is automatically included intothe predicate set if "ocamlopt" is used and the -p option is ineffect.

    autolink

    The "autolink" predicate means that ocamlc is able to perform automaticlinking. It is automatically included into the predicate set if ocamlcknows automatic linking (from version 3.00), but it is not set if the-noautolink option is set.

    syntax

    This predicate is set if there is a -syntaxoption. It is set both for the preprocessor and the compiler/linker stage,and it can be used to find out whether the preprocessor is enabled or not.

  Predicates for preprocessing
    preprocessor

    This predicate is always set while looking up thepreprocessor arguments. It can be used to distinguish between thepreprocessor stage and the compiler/linker stage.

    syntax

    This predicate is set if there is a -syntaxoption. It is set both for the preprocessor and the compiler/linker stage,and it can be used to find out whether the preprocessor is enabled or not.

    camlp4o

    This is the reserved predicate for the standard O'Caml syntax.It can be used in the -syntaxpredicate list.

    camlp4r

    This is the reserved predicate for the revised O'Caml syntax.It can be used in the -syntaxpredicate list.

  Special behaviour of 'ocamlmktop'
As there is a special module Topfindthatsupports loading of packages in scripts, the "ocamlmktop" subcommandcan add initialization code for this module. This extra code islinked into the executable if "findlib" is in the set of effectivelylinked packages.

  Fixup of the dependency graph for multi-threading
For a number of reasons the presence of the "mt" predicate triggersthat (1) the package "threads" is added to the list of required packagesand (2) the package "threads" becomes prerequisite of all other packages(except of itself and a few hardcoded exceptions). The effect is thatthe options -thread and -vmthread automatically select the "threads"package, and that "threads" is inserted at the right position in thepackage list.

  Extended file naming
At a number of places one can not only refer to files by absoluteor relative path names, but also by extended names. These have twomajor forms: "+name"refers to the subdirectory nameof thestandard library directory, and "@name"refers to the package directory of the package name.Both forms can be continued by a path, e.g. "@netstring/netstring_top.cma".

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

  How to set the names of the compiler executables
Normally, the O'Caml bytecode compiler can be called under the nameocamlc. However, this is not always true; sometimes adifferent name is chosen.

You can instruct ocamlfind to call executables with other names thanocamlc, ocamlopt,ocamlmktop, and ocamlcp. If present,the environment variable OCAMLFIND_COMMANDSis interpretedas a mapping from the standard names to the actual names of the executables. Itmust have the following format:

standardname1
=
actualname1

standardname2
=
actualname2
 ...

Example: You may set OCAMLFIND_COMMANDSas follows:

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

export OCAMLFIND_COMMANDS

Alternatively, you can change the configuration filefindlib.conf.

THE SUBCOMMAND 'ocamlmklib'

  Synopsis
ocamlfind ocamlmklib

          [ -package
package-name-list
 |

            -predicates
pred-name-list
 |

            -dllpath-pkg
package-name-list
 |

            -dllpath-all |

            -passopt
arg
 |

            -passrest
arg...
 |

standard-option
 ]

file
 ...

  Description
This is a wrapper around ocamlmklib, and creates library archives andDLLs. In addition to the standard options, one can use -package toadd the search path of packages. Note that no predicates are set by default -the wrapper does not know whether this is about byte or native code linking.

This wrapper is mostly provided for completeness.

THE 'ocamldep' SUBCOMMAND

  Synopsis
ocamlfind ocamldep [-package
package-name-list
 |

                    -syntax
pred-name-list
 |

                    -ppopt
camlp4-arg
 |

                    -passopt
arg
 |

                    -passrest
arg...
 |

                    -verbose |

standard-option
]
file
 ...

  Description
This command is a driver for the tool ocamldepof theO'Caml distribution. This driver is only useful in conjunction withthe preprocessor camlp4; otherwise it does not provide more functionsthan ocamldepitself.

  Options
Here, only the additional options not interpreted by ocamldepbutby the driver itself, and options with additional effects are explained.

    -package package-name-list

    The packages named here are only used to look up thepreprocessor options. The package camlp4should bespecified anyway, but further packages that add capabilities to thepreprocessor can also be passed.

    -syntax pred-name-list

    The predicates that are in effect during the look-upof the preprocessor options. At least, either camlp4o(selecting the normal syntax), or camlp4r(selectingthe revised syntax) should be specified.

    -ppopt camlp4-arg

    An option that is passed through to the camlp4 call.

    -passopt arg

    An option that is passed through to the ocamldep call.

    -passrest arg...

    All further arguments are passed down to ocamldepunprocessed

    -verbose

    Displays the resulting ocamldep command (for debugging)

  Example
A typical way of using this driver:

ocamlfind ocamldep -package camlp4,xstrp4 -syntax camlp4r file1.ml file2.ml
This command outputs the dependencies of file1.mlandfile2.ml, although these modules make use of thesyntax extensions provided by xstrp4and are writtenin revised syntax.

THE 'ocamlbrowser' SUBCOMMAND

  Synopsis
ocamlfind ocamlbrowser [-package
package-name-list
 |

                        -all |

                        -passopt
arg

                        -passrest ]

  Description
This driver calls the ocamlbrowserwith package options.With -package, the specified packages are included intothe search path of the browser, and the modules of these packages becomevisible (in addition to the standard library). The option -allcauses that all packages are selected that are managed by findlib.

As for other drivers, the options -passoptand-passrestcan be usedto pass arguments directly to the ocamlbrowserprogram.

THE SUBCOMMAND 'ocamldoc'

  Synopsis
ocamlfind ocamldoc

          [ -package
package-name-list
 |

            -predicates
pred-name-list
 |

            -syntax
pred-name-list
 |

            -ppopt
camlp4-arg
 |

standard-option
 ]

file
 ...

  Description
This subcommand is a driver for ocamldoc. It undestands all optionsocamldoc supports plus the mentioned findlib options. Basically,the -package options are translated into -I options, and the selectedsyntax options are translated into camlp4 options.

  Options
Here, only the additional options not interpreted by ocamldepbutby the driver itself, and options with additional effects are explained.

    -package package-name-list

    Adds the listed package names to the set of includedpackages. The package names may be separated by commas and/orwhitespace. In the transformed command, for every package of the setof included packages and for any ancestor a directory search optionis inserted after the already given options. This means that"-I" options are added for every package directory.

    -predicates pred-name-list

    Adds the given predicates to the set of actualpredicates. The predicates must be separated by commas and/orwhitespace.

    -syntax pred-name-list

    The predicates that are in effect during the look-upof the preprocessor options. At least, either camlp4o(selecting the normal syntax), or camlp4r(selectingthe revised syntax) should be specified.

    -ppopt camlp4-arg

    An option that is passed through to the camlp4 call.

THE 'install' SUBCOMMAND

  Synopsis
ocamlfind install [ -destdir
directory
 ]

                  [ -metadir
directory
 ]

                  [ -ldconf
path
 ]

                  [ -dont-add-directory-directive ]

                  [ -patch-version
string
 ]

                  [ -patch-rmpkg
name
 ]

                  [ -patch-archives ]

                  [ -dll ] [ -nodll ] [ -optional ] [ -add ]

package_name

file
 ...

  Description
This subcommand installs a new package either at the default location(see the variable destdiroffindlib.conf), or in the directoryspecified by the -destdir option. Thismeans that a new package directory is created and that the files onthe command line are copied to this directory. It is required that aMETAfile is one of the files copied to the targetdirectory.

Note that package directories should be flat (nosubdirectories). Existing packages are never overwritten.

It is possible to have a separate directory for all the META files. Ifyou want that, you have either to set the variablemetadirof findlib.conf, or to specify the-metadir option. In this case, the file called META is copied to thespecified directory and renamed to META.p (where p is the packagename), while all the other files are copied to the packagedirectory as usual. Furthermore, the META file is modified such that thedirectoryvariable contains the path of the packagedirectory.

The option -dont-add-directory-directive prevents the installer fromadding a directoryvariable.

If there are files ending in the suffixes .soor.dll, the package directory will be added to theDLL configuration file ld.conf, such that the dynamicloader can find the DLL. The location of this file can be overriden bythe -ldconf option. To turn this feature off, use "-ldconf ignore";this causes that the ld.conf file is not modified.

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

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

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

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

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

The effect of -add is to add further files to an already installedpackages.

THE 'remove' SUBCOMMAND

  Synopsis
ocamlfind remove [ -destdir
directory
 ]

                 [ -metadir
directory
 ]

                 [ -ldconf
path
 ]

package_name

  Description
The package will removed if it is installed at the default location (see the variable destdiroffindlib.conf). If the packageresides at a different location, it will not be removed by default;however, you can pass an alternate directory for packages by the-destdir option. (This must be the same directory as specified atinstallation time.)

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

If you have a separate directory for META files, you must eitherconfigure this directory by the metadirvariableof findlib.conf, or by specifyingthe -metadir option.

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

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

If there is a stublibs directory, it is checked whether the packageowns any of the files in this directory, and the owned files willbe deleted.

THE 'list' SUBCOMMAND

  Synopsis
ocamlfind list [-describe]

  Description
This command lists all packages in the search path. The option -describeoutputs the package descriptions, too.

THE 'lint' SUBCOMMAND

  Synopsis
ocamlfind lint
file

  Description
Checks the META file, and reports possible problems.

THE 'printconf' SUBCOMMAND

  Synopsis
ocamlfind printconf [ conf | path | destdir | metadir | metapath | stdlib | ldconf ]

  Description
This command prints the effective configuration after reading theconfiguration file, and after applying the various environmentvariables overriding settings. When called without arguments, the commandprints all configuration options in a human-readable form. When calledwith an argument, only the value of the requested option is printed withoutexplaining texts:

    conf

    Prints the location of the configuration file findlib.conf

    path

    Prints the search path for packages. The members of thepath are separated by linefeeds.

    destdir

    Prints the location where package are installed andremoved by default.

    metadir

    Prints the location where META files are installed andremoved (if the alternative layout is used).

    metapath

    Prints the path where the META file is installed fora fictive package. The name of the package is marked with '%s' in thepath. For instance, this command could output "/some/path/%s/META" or"/some/path/META.%s", depending on the layout.

    stdlib

    Prints the location of the standard library.

    ldconf

    Prints the location of the ld.conf file

THE SUBCOMMAND CALLING PACKAGE PROGRAMS

  Synopsis
ocamlfind
pkg
/
cmd

argument
 ...

  Description
This subcommand is useful to call programs that are installed inpackage directories. It looks up the directory for pkgand calls the command namedcmdin this directory. The remaining argumentsare passed to this command.

argv(0) contains the absolute path to the command, and argv(1) andthe following argv entries contain the arguments. The working directoryis not changed.

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

ocamlfind p/x y z

CONFIGURATION FILE, ENVIRONMENT VARIABLES
The configuration file and environment variables are documentedin the manual page forfindlib.conf.

HOW TO SET THE TOOLCHAIN

  Synopsis
ocamlfind -toolchain
name
 ...

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

ocamlfind -toolchain foo ocamlc -c file.ml
compiles file.ml with toolchain "foo". By selecting toolchains onecan switch to different command sets. For instance, the toolchain"foo" may consist of a patched ocamlc compiler. See findlib.confhow toconfigure toolchains.