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


                  -qe | -qo] 
package
 ...

Description¶

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

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

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

Options¶

Placeholders meaningful in the -format option¶

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. The subcommands understand all documented options of the compilers (here called standard-options), but also a few more options. If these subcommands are invoked only with standard options, they behave as if the underlying compiler had been called directly. The extra options modify this.

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

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

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

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

If there is a -syntax option, the drivers assume that a preprocessor is to be used. In this case, the preprocessor command is built first in a preprocessor stage, and this command is passed to the compiler using the -pp option. The set of predicates in the preprocessor stage is different from the set in the compiler/linker stage.

Options for compiling and linking¶

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

Options for preprocessing¶

The options relevant for the preprocessor are the following:

Predicates for compiling and linking¶

Predicates for preprocessing¶

Special behaviour of 'ocamlmktop'¶

As there is a special module Topfind that supports loading of packages in scripts, the "ocamlmktop" subcommand can add initialization code for this module. This extra code is linked into the executable if "findlib" is in the set of effectively linked packages.

Fixup of the dependency graph for multi-threading¶

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

Extended file naming¶

At a number of places one can not only refer to files by absolute or relative path names, but also by extended names. These have two major forms: "+name" refers to the subdirectory name of the standard 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 -I options, (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 OCaml bytecode compiler can be called under the name ocamlc. However, this is not always true; sometimes a different name is chosen.

You can instruct ocamlfind to call executables with other names than ocamlc, ocamlopt, ocamlmktop, and ocamlcp. If present, the environment variable OCAMLFIND_COMMANDS is interpreted as a mapping from the standard names to the actual names of the executables. It must have the following format:

standardname1
=
actualname1
 
standardname2
=
actualname2
 ...

Example: You may set OCAMLFIND_COMMANDS as follows:

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


export OCAMLFIND_COMMANDS

Alternatively, you can change the configuration file findlib.conf.

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 and DLLs. In addition to the standard options, one can use -package to add 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.

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 ocamldep of the OCaml distribution. This driver is only useful in conjunction with the preprocessor camlp4; otherwise it does not provide more functions than ocamldep itself.

Options¶

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

Example¶

A typical way of using this driver:

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

Synopsis¶

ocamlfind ocamlbrowser [-package 
package-name-list
 |



                        -all |


                        -passopt 
arg
 



                        -passrest ]

Description¶

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

As for other drivers, the options -passopt and -passrest can be used to pass arguments directly to the ocamlbrowser program.

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 options ocamldoc supports plus the mentioned findlib options. Basically, the -package options are translated into -I options, and the selected syntax options are translated into camlp4 options.

Options¶

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

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 destdir of findlib.conf), or in the directory specified by the -destdir option. This means that a new package directory is created and that the files on the command line are copied to this directory. It is required that a META file is one of the files copied to the target directory.

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

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

The option -dont-add-directory-directive prevents the installer from adding a directory variable.

If there are files ending in the suffixes .so or .dll, the package directory will be added to the DLL configuration file ld.conf, such that the dynamic loader can find the DLL. The location of this file can be overriden by the -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 not installed in the package directory, but in this directory that is shared by all packages that are installed at the same location. In this case, the configuration file ld.conf is not modified, so you do not need to say "-ldconf ignore" if you prefer this style of installation.

The options -dll and -nodll can be used to control exactly which files are considered as DLLs and which not. By default, the mentioned suffix rule is in effect: files ending in ".so" (Unix) or ".dll" (Windows) are DLLs. The switch -dll changes this, and all following files are considered as DLLs, regardless of their suffix. The switch -nodll expresses that the following files are not DLLs, even if they have a DLL-like suffix. For example, in the following call the files f1 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 files while it is being installed. The option -patch-version changes the contents of the top-level "version" variable. The option -patch-rmpkg removes 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 installed packages.

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 destdir of findlib.conf). If the package resides 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 at installation time.)

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

If you have a separate directory for META files, you must either configure this directory by the metadir variable of findlib.conf, or by specifying the -metadir option.

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

If the package directory is mentioned in the ld.conf configuration file for DLLs, it will be tried to remove this entry from the file. The location of this file can be overriden by the -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 package owns any of the files in this directory, and the owned files will be deleted.

Synopsis¶

ocamlfind list [-describe]

Description¶

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

Synopsis¶

ocamlfind printppx


          [ -predicates 
pred-name-list
 ]



          [ -ppxopt 
package
,
arg
 ]



          
package
 ...

Description¶

This command prints the ppx preprocessor options as they would occur in an OCaml compiler invocation for the packages listed in the command. The output includes one "-ppx" option for each preprocessor. The possible options have the same meaning as for "ocamlfind ocamlc". The option "-predicates" adds assumed predicates and "-ppxopt package,arg" adds "arg" to the ppx invocation of package package.

The output of "ocamlfind printppx" will contain quotes """ for ppx commands that contain space-separated arguments. In this case $(ocamlfind printppx ...) won't work as naively expected, because many shells (including bash and dash) perform field splitting on the result of command substitutions without honoring quotes.

Synopsis¶

ocamlfind lint 
file

Description¶

Checks the META file, and reports possible problems.

Synopsis¶

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

Description¶

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

Synopsis¶

ocamlfind 
pkg
/
cmd
 
argument
 ...

Description¶

This subcommand is useful to call programs that are installed in package directories. It looks up the directory for pkg and calls the command named cmd in this directory. The remaining arguments are passed to this command.

argv(0) contains the absolute path to the command, and argv(1) and the following argv entries contain the arguments. The working directory is 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

Synopsis¶

ocamlfind -toolchain 
name
 ...

Description¶

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

ocamlfind -toolchain foo ocamlc -c file.ml