\[\begin{split}\newcommand{\alors}{\textsf{then}} \newcommand{\alter}{\textsf{alter}} \newcommand{\as}{\kw{as}} \newcommand{\Assum}[3]{\kw{Assum}(#1)(#2:#3)} \newcommand{\bool}{\textsf{bool}} \newcommand{\case}{\kw{case}} \newcommand{\conc}{\textsf{conc}} \newcommand{\cons}{\textsf{cons}} \newcommand{\consf}{\textsf{consf}} \newcommand{\conshl}{\textsf{cons\_hl}} \newcommand{\Def}[4]{\kw{Def}(#1)(#2:=#3:#4)} \newcommand{\emptyf}{\textsf{emptyf}} \newcommand{\End}{\kw{End}} \newcommand{\kwend}{\kw{end}} \newcommand{\EqSt}{\textsf{EqSt}} \newcommand{\even}{\textsf{even}} \newcommand{\evenO}{\textsf{even}_\textsf{O}} \newcommand{\evenS}{\textsf{even}_\textsf{S}} \newcommand{\false}{\textsf{false}} \newcommand{\filter}{\textsf{filter}} \newcommand{\Fix}{\kw{Fix}} \newcommand{\fix}{\kw{fix}} \newcommand{\for}{\textsf{for}} \newcommand{\forest}{\textsf{forest}} \newcommand{\from}{\textsf{from}} \newcommand{\Functor}{\kw{Functor}} \newcommand{\haslength}{\textsf{has\_length}} \newcommand{\hd}{\textsf{hd}} \newcommand{\ident}{\textsf{ident}} \newcommand{\In}{\kw{in}} \newcommand{\Ind}[4]{\kw{Ind}[#2](#3:=#4)} \newcommand{\ind}[3]{\kw{Ind}~[#1]\left(#2\mathrm{~:=~}#3\right)} \newcommand{\Indp}[5]{\kw{Ind}_{#5}(#1)[#2](#3:=#4)} \newcommand{\Indpstr}[6]{\kw{Ind}_{#5}(#1)[#2](#3:=#4)/{#6}} \newcommand{\injective}{\kw{injective}} \newcommand{\kw}[1]{\textsf{#1}} \newcommand{\lb}{\lambda} \newcommand{\length}{\textsf{length}} \newcommand{\letin}[3]{\kw{let}~#1:=#2~\kw{in}~#3} \newcommand{\List}{\textsf{list}} \newcommand{\lra}{\longrightarrow} \newcommand{\Match}{\kw{match}} \newcommand{\Mod}[3]{{\kw{Mod}}({#1}:{#2}\,\zeroone{:={#3}})} \newcommand{\ModA}[2]{{\kw{ModA}}({#1}=={#2})} \newcommand{\ModS}[2]{{\kw{Mod}}({#1}:{#2})} \newcommand{\ModType}[2]{{\kw{ModType}}({#1}:={#2})} \newcommand{\mto}{.\;} \newcommand{\Nat}{\mathbb{N}} \newcommand{\nat}{\textsf{nat}} \newcommand{\Nil}{\textsf{nil}} \newcommand{\nilhl}{\textsf{nil\_hl}} \newcommand{\nO}{\textsf{O}} \newcommand{\node}{\textsf{node}} \newcommand{\nS}{\textsf{S}} \newcommand{\odd}{\textsf{odd}} \newcommand{\oddS}{\textsf{odd}_\textsf{S}} \newcommand{\ovl}[1]{\overline{#1}} \newcommand{\Pair}{\textsf{pair}} \newcommand{\plus}{\mathsf{plus}} \newcommand{\Prod}{\textsf{prod}} \newcommand{\Prop}{\textsf{Prop}} \newcommand{\return}{\kw{return}} \newcommand{\Set}{\textsf{Set}} \newcommand{\si}{\textsf{if}} \newcommand{\sinon}{\textsf{else}} \newcommand{\Sort}{\mathcal{S}} \newcommand{\Str}{\textsf{Stream}} \newcommand{\Struct}{\kw{Struct}} \newcommand{\subst}[3]{#1\{#2/#3\}} \newcommand{\tl}{\textsf{tl}} \newcommand{\tree}{\textsf{tree}} \newcommand{\trii}{\triangleright_\iota} \newcommand{\true}{\textsf{true}} \newcommand{\Type}{\textsf{Type}} \newcommand{\unfold}{\textsf{unfold}} \newcommand{\WEV}[3]{\mbox{$#1[] \vdash #2 \lra #3$}} \newcommand{\WEVT}[3]{\mbox{$#1[] \vdash #2 \lra$}\\ \mbox{$ #3$}} \newcommand{\WF}[2]{{\mathcal{W\!F}}(#1)[#2]} \newcommand{\WFE}[1]{\WF{E}{#1}} \newcommand{\WFT}[2]{#1[] \vdash {\mathcal{W\!F}}(#2)} \newcommand{\WFTWOLINES}[2]{{\mathcal{W\!F}}\begin{array}{l}(#1)\\\mbox{}[{#2}]\end{array}} \newcommand{\with}{\kw{with}} \newcommand{\WS}[3]{#1[] \vdash #2 <: #3} \newcommand{\WSE}[2]{\WS{E}{#1}{#2}} \newcommand{\WT}[4]{#1[#2] \vdash #3 : #4} \newcommand{\WTE}[3]{\WT{E}{#1}{#2}{#3}} \newcommand{\WTEG}[2]{\WTE{\Gamma}{#1}{#2}} \newcommand{\WTM}[3]{\WT{#1}{}{#2}{#3}} \newcommand{\zeroone}[1]{[{#1}]} \newcommand{\zeros}{\textsf{zeros}} \end{split}\]

# The Coq commands

There are three Coq commands:

- `coqtop`: the Coq toplevel (interactive mode);

- `coqc`: the Coq compiler (batch compilation);

- `coqchk`: the Coq checker (validation of compiled libraries).

The options are (basically) the same for the first two commands, and roughly described below. You can also look at the `man` pages of `coqtop` and `coqc` for more details.

## Interactive use (coqtop)

In the interactive mode, also known as the Coq toplevel, the user can develop his theories and proofs step by step. The Coq toplevel is run by the command `coqtop`.

There are two different binary images of Coq: the byte-code one and the native-code one (if OCaml provides a native-code compiler for your platform, which is supposed in the following). By default, `coqtop` executes the native-code version; run `coqtop.byte` to get the byte-code version.

The byte-code toplevel is based on an OCaml toplevel (to allow dynamic linking of tactics). You can switch to the OCaml toplevel with the command `Drop.`, and come back to the Coq toplevel with the command `Coqloop.loop();;`.

## Batch compilation (coqc)

The `coqc` command takes a name file as argument. Then it looks for a vernacular file named file.v, and tries to compile it into a file.vo file (See Compiled files).

Caution

The name file should be a regular Coq identifier as defined in Section Lexical conventions. It should contain only letters, digits or underscores (_). For example `/bar/foo/toto.v` is valid, but `/bar/foo/to-to.v` is not.

## Customization at launch time

### By resource file

When Coq is launched, with either `coqtop` or `coqc`, the resource file `$XDG_CONFIG_HOME/coq/coqrc.xxx`, if it exists, will be implicitly prepended to any document read by Coq, whether it is an interactive session or a file to compile. Here, `$XDG_CONFIG_HOME` is the configuration directory of the user (by default it's `~/.config`) and `xxx` is the version number (e.g. 8.8). If this file is not found, then the file `$XDG_CONFIG_HOME/coqrc` is searched. If not found, it is the file `~/.coqrc.xxx` which is searched, and, if still not found, the file `~/.coqrc`. If the latter is also absent, no resource file is loaded. You can also specify an arbitrary name for the resource file (see option `-init-file` below).

The resource file may contain, for instance, `Add LoadPath` commands to add directories to the load path of Coq. It is possible to skip the loading of the resource file with the option `-q`.

### By environment variables

Load path can be specified to the Coq system by setting up `$COQPATH` environment variable. It is a list of directories separated by `:` (`;` on Windows). Coq will also honor `$XDG_DATA_HOME` and `$XDG_DATA_DIRS` (see Section Libraries and filesystem).

Some Coq commands call other Coq commands. In this case, they look for the commands in directory specified by `$COQBIN`. If this variable is not set, they look for the commands in the executable path.

The `$COQ_COLORS` environment variable can be used to specify the set of colors used by `coqtop` to highlight its output. It uses the same syntax as the `$LS_COLORS` variable from GNU’s ls, that is, a colon-separated list of assignments of the form `name=attr*;` where `name` is the name of the corresponding highlight tag and each `attr` is an ANSI escape code. The list of highlight tags can be retrieved with the `-list-tags` command-line option of `coqtop`.

The string uses ANSI escape codes to represent attributes. For example:

> `export COQ_COLORS=”diff.added=4;48;2;0;0;240:diff.removed=41”`

sets the highlights for added text in diffs to underlined (the 4) with a background RGB color (0, 0, 240) and for removed text in diffs to a red background. Note that if you specify `COQ_COLORS`, the predefined attributes are ignored.

### By command line options

The following command-line options are recognized by the commands `coqc` and `coqtop`, unless stated otherwise:

-I directory, -include directory

  Add physical path directory to the OCaml loadpath.

  See also

  Names of libraries and the command Declare ML Module Section Compiled files.

-Q directory dirpath

  Add physical path directory to the list of directories where Coq looks for a file and bind it to the logical directory dirpath. The subdirectory structure of directory is recursively available from Coq using absolute names (extending the dirpath prefix) (see Section Qualified names).Note that only those subdirectories and files which obey the lexical conventions of what is an `ident` are taken into account. Conversely, the underlying file systems or operating systems may be more restrictive than Coq. While Linux’s ext4 file system supports any Coq recursive layout (within the limit of 255 bytes per filename), the default on NTFS (Windows) or HFS+ (MacOS X) file systems is on the contrary to disallow two files differing only in the case in the same directory.

  See also

  Section Names of libraries.

-R directory dirpath

  Do as -Q directory dirpath but make the subdirectory structure of directory recursively visible so that the recursive contents of physical directory is available from Coq using short or partially qualified names.

  See also

  Section Names of libraries.

-top dirpath

  Set the toplevel module name to dirpath instead of Top. Not valid for `coqc` as the toplevel module name is inferred from the name of the output file.

-exclude-dir directory

  Exclude any subdirectory named directory while processing options such as -R and -Q. By default, only the conventional version control management directories named CVS and_darcs are excluded.

-nois

  Start from an empty state instead of loading the Init.Prelude module.

-init-file file

  Load file as the resource file instead of loading the default resource file from the standard configuration directories.

-q

  Do not to load the default resource file.

-load-ml-source file

  Load the OCaml source file file.

-load-ml-object file

  Load the OCaml object file file.

-l file, -load-vernac-source file

  Load and execute the Coq script from file.v.

-lv file, -load-vernac-source-verbose file

  Load and execute the Coq script from file.v. Write its contents to the standard output as it is executed.

-load-vernac-object dirpath

  Load Coq compiled library dirpath. This is equivalent to runningRequire dirpath.

-require dirpath

  Load Coq compiled library dirpath and import it. This is equivalent to running Require Import dirpath.

-batch

  Exit just after argument parsing. Available for `coqtop` only.

-compile file.v

  Compile file file.v into file.vo. This option implies -batch (exit just after argument parsing). It is available only for `coqtop`, as this behavior is the purpose of `coqc`.

-compile-verbose file.v

  Same as -compile but also output the content of file.v as it is compiled.

-verbose

  Output the content of the input file as it is compiled. This option is available for `coqc` only; it is the counterpart of -compile-verbose.

-w (all|none|w₁,…,wₙ)

  Configure the display of warnings. This option expects all, none or a comma-separated list of warning names or categories (see Section Controlling display).

-color (on|off|auto)

  Coqtop only. Enable or disable color output. Default is auto, meaning color is shown only if the output channel supports ANSI escape sequences.

-diffs (on|off|removed)

  Coqtop only. Controls highlighting of differences between proof steps. `on` highlights added tokens, `removed` highlights both added and removed tokens. Requires that `–color` is enabled. (see Section Showing differences between proof steps).

-beautify

  Pretty-print each command to file.beautified when compiling file.v, in order to get old-fashioned syntax/definitions/notations.

-emacs, -ide-slave

  Start a special toplevel to communicate with a specific IDE.

-impredicative-set

  Change the logical theory of Coq by declaring the sort Set impredicative.

  Warning

  This is known to be inconsistent with some standard axioms of classical mathematics such as the functional axiom of choice or the principle of description.

-type-in-type

  Collapse the universe hierarchy of Coq.

  Warning

  This makes the logic inconsistent.

-mangle-names ident

  Experimental: Do not depend on this option. Replace Coq's auto-generated name scheme with names of the form ident0, ident1, etc. The command `Set Mangle Names` turns the behavior on in a document, and `Set Mangle Names Prefix "ident"` changes the used prefix. This feature is intended to be used as a linter for developments that want to be robust to changes in the auto-generated name scheme. The options are provided to facilitate tracking down problems.

-compat version

  Attempt to maintain some backward-compatibility with a previous version.

-dump-glob file

  Dump references for global names in file file (to be used by coqdoc, see Documenting Coq files with coqdoc). By default, if file.v is being compiled, file.glob is used.

-no-glob

  Disable the dumping of references for global names.

-image file

  Set the binary image to be used by `coqc` to be file instead of the standard one. Not of general use.

-bindir directory

  Set the directory containing Coq binaries to be used by `coqc`. It is equivalent to doing export COQBIN= directory before launching `coqc`.

-where

  Print the location of Coq’s standard library and exit.

-config

  Print the locations of Coq’s binaries, dependencies, and libraries, then exit.

-filteropts

  Print the list of command line arguments that `coqtop` has recognized as options and exit.

-v

  Print Coq’s version and exit.

-list-tags

  Print the highlight tags known by Coq as well as their currently associated color and exit.

-h, --help

  Print a short usage and exit.

## Compiled libraries checker (coqchk)

The `coqchk` command takes a list of library paths as argument, described either by their logical name or by their physical filename, hich must end in `.vo`. The corresponding compiled libraries (`.vo` files) are searched in the path, recursively processing the libraries they depend on. The content of all these libraries is then type checked. The effect of `coqchk` is only to return with normal exit code in case of success, and with positive exit code if an error has been found. Error messages are not deemed to help the user understand what is wrong. In the current version, it does not modify the compiled libraries to mark them as successfully checked.

Note that non-logical information is not checked. By logical information, we mean the type and optional body associated to names. It excludes for instance anything related to the concrete syntax of objects (customized syntax rules, association between short and long names), implicit arguments, etc.

This tool can be used for several purposes. One is to check that a compiled library provided by a third-party has not been forged and that loading it cannot introduce inconsistencies 1. Another point is to get an even higher level of security. Since `coqtop` can be extended with custom tactics, possibly ill-typed code, it cannot be guaranteed that the produced compiled libraries are correct. `coqchk` is a standalone verifier, and thus it cannot be tainted by such malicious code.

Command-line options `-Q`, `-R`, `-where` and `-impredicative-set` are supported by `coqchk` and have the same meaning as for `coqtop`. As there is no notion of relative paths in object files `-Q` and `-R` have exactly the same meaning.

-norec module

  Check module but do not check its dependencies.

-admit module

  Do not check module and any of its dependencies, unless explicitly required.

-o

  At exit, print a summary about the context. List the names of all assumptions and variables (constants without body).

-silent

  Do not write progress information to the standard output.

Environment variable `$COQLIB` can be set to override the location of the standard library.

The algorithm for deciding which modules are checked or admitted is the following: assuming that `coqchk` is called with argument `M`, option `-norec N`, and `-admit A`. Let us write \(\overline{S}\) for the set of reflexive transitive dependencies of set \(S\). Then:

- Modules \(C = \overline{M} \backslash \overline{A} \cup M \cup N\) are loaded and type checked before being added to the context.

- And \(M \cup N \backslash C\) is the set of modules that are loaded and added to the context without type checking. Basic integrity checks (checksums) are nonetheless performed.

As a rule of thumb, -admit can be used to tell Coq that some libraries have already been checked. So `coqchk A B` can be split in `coqchk A` && `coqchk B -admit A` without type checking any definition twice. Of course, the latter is slightly slower since it makes more disk access. It is also less secure since an attacker might have replaced the compiled library `A` after it has been read by the first command, but before it has been read by the second command.

1

  Ill-formed non-logical information might for instance bind Coq.Init.Logic.True to short name False, so apparently False is inhabited, but using fully qualified names, Coq.Init.Logic.False will always refer to the absurd proposition, what we guarantee is that there is no proof of this latter constant.