.. _command-line-options: ******************** Command-line options ******************** Command-line options -------------------- Agda accepts the following options on the command line. Where noted, these options can also serve as *pragma options*, i.e., be supplied in a file via the ``{-# OPTIONS ... #-}`` pragma or in the ``flags`` section of an ``.agda-lib`` file. Setup and information ~~~~~~~~~~~~~~~~~~~~~ Some options cause Agda to perform tasks at startup like mandatory setup or printing some information. These options are not exclusive, they can be used with other options, albeit this seldom makes sense. They are not executed in the order given on the command line, but in the fixed order listed in the following: .. option:: --setup .. versionadded:: 2.8.0 Extract Agda's data files (primitive library, emacs mode etc.) to the data directory (see :option:`--print-data-dir`). .. option:: --version, -V Show version number and cabal flags used in this build of Agda. Overwrites :option:`--numeric-version`. .. option:: --numeric-version Show just the version number. Overwrites :option:`--version`. .. option:: --help[={TOPIC}], -?[{TOPIC}] Show basically this help, or more help about ``TOPIC``. Available topics: - ``emacs-mode``: Explain the option :option:`--emacs-mode`. - ``error``: List the names of Agda's errors. - ``warning``: List warning groups and individual warnings and their default status. Instruct how to toggle benign warnings. Overwrites itself, i.e., only the last of several :option:`--help` options is effective. .. option:: --print-options .. versionadded:: 2.9.0 Print a simple list of all options, suitable for implementing bash completion. .. option:: --build-library .. versionadded:: 2.8.0 Expects an ``.agda-lib`` file in the current directory (or in a parent directory) and type-checks all Agda files found in the ``include`` directories of the library or in subdirectories thereof. .. option:: --print-app-dir .. versionadded:: 2.6.4.1 Outputs the (:envvar:`AGDA_DIR`) directory containing Agda's application configuration files, such as the ``defaults`` and ``libraries`` files, as described in :ref:`package-system`. .. option:: --print-data-dir .. versionadded:: 2.6.4.1 Outputs the root of the directory structure holding Agda's data files such as core libraries, style files for the backends, etc. Since 2.8.0, the data directory is determined as follows: - The *default data directory* is defined at build time, either as the standard data directory defined by Cabal, or, if the ``use-xdg-data-home`` Cabal flag is enabled, as ``$XDG_DATA_HOME/agda/$AGDA_VERSION``. - The *data directory* can be set at runtime using the :envvar:`Mikan_datadir` environment variable and defaults to the default data directory. It can be printed with this flag. .. option:: --emacs-mode={COMMAND} .. versionadded:: 2.8.0 Administer the Agda Emacs mode, a task previously managed by the ``agda-mode`` executable. Available commands: - ``setup``: Install the Emacs mode into ``.emacs``. - ``compile``: Compile the Elisp files of the Emacs mode. - ``locate``: Print the path to the Emacs mode. More information in :ref:`Section Emacs `. This option can be given several times to perform several commands. General options ~~~~~~~~~~~~~~~ .. option:: --interaction For use with the Emacs mode (no need to invoke yourself). .. option:: --parallel[=N], -j[N] .. versionadded:: 2.9.0 Type check in parallel. N is optional, and controls the number of threads to use for checking. If ``N`` is omitted, or explicitly set to 0, the number of processors is used. The default, ``-j1``, means type checking is sequential. Parallelism has module granularity. Parallel type checking trades space for time, with (generally) a decrease in wall-clock time *larger* than the corresponding increase in total memory usage. Type-checking of a module can not start until all of its dependencies have been checked, so wider dependency graphs will see more speedup than taller dependency graphs. Using *too many* cores can make the space-time tradeoff worse. The appropriate number will depend on the specifics of the project being checked. A reasonable number to start with is ``-j8``. .. option:: --interaction-json .. versionadded:: 2.6.1 For use with other editors such as Atom (no need to invoke yourself). .. option:: --interaction-exit-on-error .. versionadded:: 2.6.3 Makes Agda exit with a non-zero exit code if :option:`--interaction` or :option:`--interaction-json` are used and a type error is encountered. The option also makes Agda exit with exit code 113 if Agda fails to parse a command. This option might for instance be used if Agda is controlled from a script. .. option:: --trace-imports[=(0|1|2|3)] .. versionadded:: 2.6.4 Configure printing of messages when an imported module is accessed during type-checking. .. list-table:: * - ``0`` - Do not print any messages about checking a module. * - ``1`` - | Print only `Checking ...` when an access to an uncompiled module occurs. | This is the default behavior if ``--trace-imports`` is not specified. * - ``2`` - | Use the effect of ``1``, but also print `Finished ...` | when a compilation of an uncompiled module is finished. | This is the behavior if ``--trace-imports`` is specified without a value. * - ``3`` - | Use the effect of ``2``, but also print `Loading ...` | when a compiled module (interface) is accessed during the type-checking. .. option:: --colour[=(auto|always|never)], --color[=(auto|always|never)] .. versionadded:: 2.6.4 Configure whether or not Agda's standard output diagnostics should use ANSI terminal colours for syntax highlighting (e.g. error messages, warnings). .. list-table:: * - ``always`` - Always print diagnostic in colour. * - ``auto`` - | Automatically determine whether or not it is safe for | standard output to include colours. Colours will be used | when writing directly to a terminal device on Linux and | macOS. | | This is the default value. * - ``never`` - Never print output in colour. The American spelling, ``--color``, is also accepted. **Note:** Currently, the colour scheme for terminal output can not be configured. If the colours are not legible on your terminal, please use ``--colour=never`` for now. .. option:: --only-scope-checking .. versionadded:: 2.5.3 Only scope-check the top-level module, do not type-check it (see :ref:`quickLaTeX`). .. option:: --transliterate .. versionadded:: 2.6.3 When writing to stdout or stderr Agda will (hopefully) replace code points that are not supported by the current locale or code page by something else, perhaps question marks. This option is not supported when :option:`--interaction` or :option:`--interaction-json` are used, because when those options are used Agda uses UTF-8 when writing to stdout (and when reading from stdin). .. _literate-options: Literate programming ~~~~~~~~~~~~~~~~~~~~ .. option:: --literate-markdown-only-agda-blocks .. versionadded:: 2.9.0 In literate Markdown (``.lagda.md``) and Typst (``.lagda.typ``) files, only treat code blocks explicitly marked with ``````agda`` as Agda code. Unmarked code blocks (``````) are treated as verbatim text and are not type-checked. See :ref:`literate-markdown-only-agda-blocks` for more details. .. option:: --no-literate-markdown-only-agda-blocks .. versionadded:: 2.9.0 Treat also unmarked code blocks as Agda code in literate Markdown and Typst files (default). .. _compilation-options: Compilation ~~~~~~~~~~~ .. option:: --no-main Do not treat the requested/current module as the main module of a program when compiling. Pragma option since 2.5.3. .. option:: --main .. versionadded:: 2.6.4 Default, opposite of :option:`--no-main`. Generating highlighted source code ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. option:: --dependency-graph={FILE} .. versionadded:: 2.3.0 Generate a Dot_ file ``FILE`` with a module dependency graph. .. option:: --dependency-graph-include={LIBRARY} .. versionadded:: 2.6.3 Include modules from the given library in the dependency graph. This option can be used multiple times to include modules from several libraries. If this option is not used at all, then all modules are included. (Note that the module given on the command line might not be included.) A module ``M`` is considered to be in the library ``L`` if ``L`` is the ``name`` of an ``.agda-lib`` file :ref:`associated` to ``M`` (even if ``M``'s file cannot be found via the ``include`` paths given in the ``.agda-lib`` file). .. option:: --html .. versionadded:: 2.2.0 Generate HTML files with highlighted source code (see :ref:`generating-html` for description and further options). .. option:: --latex .. versionadded:: 2.3.2 Generate LaTeX with highlighted source code (see :ref:`generating-latex` for description and further options). .. option:: --vim Generate Vim_ highlighting files. Imports and libraries ~~~~~~~~~~~~~~~~~~~~~ (see :ref:`package-system`) .. option:: --ignore-all-interfaces .. versionadded:: 2.6.0 Don't read *any* interface files, including builtin and primitive modules; only use this if you know what you are doing! .. option:: --ignore-interfaces Don't read interface files (re-type check everything, except for builtin and primitive modules). .. option:: --no-write-interfaces .. versionadded:: 2.9.0 Don't write out interface files after type-checking a module. .. option:: --include-path={DIR}, -i {DIR} Look for imports in ``DIR``. This option can be given multiple times. .. option:: --library={DIR}, -l {LIB} .. versionadded:: 2.5.1 Use library ``LIB``. .. option:: --library-file={FILE} .. versionadded:: 2.5.1 Use ``FILE`` instead of the standard ``libraries`` file. .. option:: --defaults-file={FILE} .. versionadded:: Mikan Use ``FILE`` instead of the standard ``defaults`` file. .. option:: --no-default-libraries .. versionadded:: 2.5.1 Don't use default library files. .. option:: --no-libraries .. versionadded:: 2.5.2 Don't use any library files. .. _command-line-pragmas: Command-line and pragma options ------------------------------- The following options can also be given in Agda files using the :ref:`OPTIONS` pragma. Performance ~~~~~~~~~~~ .. option:: --auto-inline .. versionadded:: 2.6.2 Turn on automatic compile-time inlining. See :ref:`inline-pragma` for more information. .. option:: --no-auto-inline .. versionadded:: 2.5.4 Disable automatic compile-time inlining (default). Only definitions marked ``INLINE`` will be inlined. Default since 2.6.2. .. option:: --caching, --no-caching .. versionadded:: 2.5.4 Enable or disable caching of typechecking. Default: ``--caching``. .. option:: --call-by-name .. versionadded:: 2.6.2 Disable call-by-need evaluation in the Agda Abstract Machine. .. option:: --no-call-by-name .. versionadded:: 2.6.4 Default, opposite of :option:`--call-by-name`. .. option:: --no-fast-reduce .. versionadded:: 2.6.0 Disable reduction using the Agda Abstract Machine. .. option:: --fast-reduce .. versionadded:: 2.6.4 Default, opposite of :option:`--no-fast-reduce`. .. option:: --no-forcing .. versionadded:: 2.2.10 Disable the forcing optimisation. Since Agda 2.6.1 it is a pragma option. .. option:: --forcing .. versionadded:: 2.6.4 Default, opposite of :option:`--no-forcing`. .. option:: --no-projection-like .. versionadded:: 2.6.1 Turn off the analysis whether a type signature likens that of a projection. Projection-likeness is an optimization that reduces the size of terms by dropping parameter-like reconstructible function arguments. Thus, it is advisable to leave this optimization on, the flag is meant for debugging Agda. See also the :ref:`NOT_PROJECTION_LIKE` pragma. .. option:: --projection-like .. versionadded:: 2.6.4 Default, opposite of :option:`--no-projection-like`. Printing and debugging ~~~~~~~~~~~~~~~~~~~~~~ .. option:: --no-unicode .. versionadded:: 2.5.4 Do not use unicode characters to print terms. .. option:: --unicode .. versionadded:: 2.6.4 Default, opposite of :option:`--no-unicode`. .. option:: --show-identity-substitutions .. versionadded:: 2.6.2 Show all arguments of metavariables when pretty-printing a term, even if they amount to just applying all the variables in the context. .. option:: --no-show-identity-substitutions .. versionadded:: 2.6.4 Default, opposite of :option:`--show-identity-substitutions`. .. option:: --show-implicit Show implicit arguments when printing. .. option:: --no-show-implicit .. versionadded:: 2.6.4 Default, opposite of :option:`--show-implicit`. .. option:: --show-irrelevant .. versionadded:: 2.3.2 Show arguments of sort ``Prop`` when printing. .. option:: --no-show-irrelevant .. versionadded:: 2.6.4 Default, opposite of :option:`--show-irrelevant`. .. option:: --verbose={N}, -v {N} Set verbosity level to ``N``. This only has an effect if Agda was installed with the ``debug`` Cabal flag. See :ref:`debugging` for more information. .. option:: --profile={PROF} .. versionadded:: 2.6.3 Turn on profiling option ``PROF``. Available options are .. list-table:: * - ``internal`` - Measure time taken by various parts of the system (type checking, serialization, etc) * - ``modules`` - Measure time spent on individual (Agda) modules * - ``definitions`` - Measure time spent on individual (Agda) definitions * - ``sharing`` - Measure things related to sharing * - ``serialize`` - Collect detailed statistics about serialization * - ``constraints`` - Collect statistics about constraint solving * - ``metas`` - Count number of created metavariables * - ``interactive`` - Measure time of interactive commands * - ``conversion`` - Count number of times various steps of the conversion algorithm are used (reduction, eta-expansion, syntactic equality, etc) Only one of ``internal``, ``modules``, and ``definitions`` can be turned on at a time. You can also give ``--profile=all`` to turn on all profiling options (choosing ``internal`` over ``modules`` and ``definitions``, use ``--profile=modules --profile=all`` to pick ``modules`` instead). Copatterns and projections ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. option:: --copatterns, --no-copatterns .. versionadded:: 2.4.0 Enable or disable definitions by copattern matching (see :ref:`copatterns`). Default: ``--copatterns`` (since 2.4.2.4). .. option:: --postfix-projections .. versionadded:: 2.5.2 Make postfix projection notation the default. On by default since 2.7.0. .. option:: --no-postfix-projections .. versionadded:: 2.6.4 Opposite of :option:`--postfix-projections`. Experimental features ~~~~~~~~~~~~~~~~~~~~~ .. option:: --allow-exec .. versionadded:: 2.6.2 Enable system calls during type checking (see :ref:`reflection`). .. option:: --no-allow-exec .. versionadded:: 2.6.4 Default, opposite of :option:`--allow-exec`. .. option:: --lossy-unification, --no-lossy-unification .. versionadded:: 2.6.2 Enable a constraint-solving heuristic akin to first-order unification, see :ref:`lossy-unification`. Implies :option:`--no-require-unique-meta-solutions`. .. option:: --no-lossy-unification .. versionadded:: 2.6.4 Default, opposite of :option:`--lossy-unification`. .. option:: --require-unique-meta-solutions, --no-require-unique-meta-solutions .. versionadded:: 2.7.0 When turned off, type checking is allowed to use heuristics to solve meta variables that do not necessarily guarantee unique solutions. In particular, it can make use of :ref:`INJECTIVE_FOR_INFERENCE ` pragmas. ``--no-require-unique-meta-solutions`` is implied by the :option:`--lossy-unification` flag. Default: ``--require-unique-meta-solutions`` .. option:: --prop, --no-prop .. versionadded:: 2.6.0 Enable or disable declaration and use of definitionally proof-irrelevant propositions (see :ref:`proof-irrelevant propositions `). Default: ``--no-prop``. In this case, ``Prop`` is since 2.6.4 not in scope by default (:option:`--import-sorts`). Errors and warnings ~~~~~~~~~~~~~~~~~~~ .. option:: --allow-incomplete-matches .. versionadded:: 2.6.1 Succeed and create interface file regardless of incomplete pattern-matching definitions. See also the :ref:`NON_COVERING` pragma. .. option:: --no-allow-incomplete-matches .. versionadded:: 2.6.4 Default, opposite of :option:`--allow-incomplete-matches`. .. option:: --allow-unsolved-metas Succeed and create interface file regardless of unsolved meta variables (see :ref:`metavariables`). .. option:: --no-allow-unsolved-metas .. versionadded:: 2.6.4 Default, opposite of :option:`--allow-unsolved-metas`. .. option:: --no-positivity-check Do not warn about not strictly positive data types (see :ref:`positivity-checking`). .. option:: --positivity-check .. versionadded:: 2.6.4 Default, opposite of :option:`--no-positivity-check`. .. option:: --no-termination-check Do not warn about possibly nonterminating code (see :ref:`termination-checking`). .. option:: --termination-check .. versionadded:: 2.6.4 Default, opposite of :option:`--no-termination-check`. .. option:: --warning={GROUP|FLAG}, -W {GROUP|FLAG} .. versionadded:: 2.5.3 Set warning group or flag (see :ref:`warnings`). Pattern matching and equality ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. option:: --exact-split, --no-exact-split .. versionadded:: 2.5.1 Require [do not require] all clauses in a definition to hold as definitional equalities unless marked ``CATCHALL`` (see :ref:`case-trees`). Default: ``--no-exact-split``. .. option:: --hidden-argument-puns, --no-hidden-argument-puns .. versionadded:: 2.6.4 Enable [disable] :ref:`hidden argument puns `. Default: ``--no-hidden-argument-puns``. .. option:: --no-eta-equality .. versionadded:: 2.5.1 Default records to ``no-eta-equality`` (see :ref:`eta-expansion`). .. option:: --eta-equality .. versionadded:: 2.6.4 Default, opposite of :option:`--no-eta-equality`. .. option:: --occurrence-analysis, --no-occurrence-analysis .. versionadded:: 2.9.0 Turns on or off automated occurrence analysis for functions. See :ref:`occurrence_analysis`. Default: :option:`--occurrence-analysis`. .. option:: --no-pattern-matching .. versionadded:: 2.4.0 Disable pattern matching completely. .. option:: --pattern-matching .. versionadded:: 2.6.4 Default, opposite of :option:`--no-pattern-matching`. .. option:: --keep-pattern-variables .. versionadded:: 2.6.1 Prevent interactive case splitting from replacing variables with dot patterns (see :ref:`dot-patterns`). Default since 2.7.0. .. option:: --no-keep-pattern-variables .. versionadded:: 2.6.4 Opposite of :option:`--keep-pattern-variables`. .. option:: --infer-absurd-clauses, --no-infer-absurd-clauses .. versionadded:: 2.6.4 ``--no-infer-absurd-clauses`` prevents interactive case splitting and coverage checking from automatically filtering out absurd clauses. This means that these absurd clauses have to be written out in the Agda text. Try this option if you experience type checking performance degradation with omitted absurd clauses. Default: ``--infer-absurd-clauses``. Recursion ~~~~~~~~~ .. option:: --termination-depth={N} .. versionadded:: 2.2.8 Allow termination checker to count decrease/increase upto ``N``, see :ref:`termination-checking`. Defaults to 3 since 2.9.0. Sorts and universes ~~~~~~~~~~~~~~~~~~~ .. option:: --level-universe, --no-level-universe .. versionadded:: 2.6.4 Makes ``Level`` live in its own universe ``LevelUniv`` and disallows having levels depend on terms that are not levels themselves. When this option is turned off, ``LevelUniv`` still exists, but reduces to ``Type`` (see :ref:`level-universe `). Note: This option is currently not compatible with cubical builtin files. Default: :option:`--no-level-universe`. Search depth and instances ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. option:: --instance-search-depth={N} .. versionadded:: 2.5.2 Set instance search depth to ``N`` (default: 500; see :ref:`instance-arguments`). .. option:: --inversion-max-depth={N} .. versionadded:: 2.5.4 Set maximum depth for pattern match inversion to ``N`` (default: 50). Should only be needed in pathological cases. .. option:: --backtracking-instance-search, --no-backtracking-instance-search .. versionadded:: 2.7.0 Consider [do not consider] recursive instance arguments during pruning of instance candidates, see :ref:`backtracking-instances` Default: ``--no-backtracking-instance-search``. This option used to be called ``--overlapping-instances``. .. option:: --qualified-instances, --no-qualified-instances .. versionadded:: 2.6.2 Consider [do not consider] instances that are (only) in scope under a qualified name. Default: ``--qualified-instances``. .. option:: --experimental-lazy-instances, --no-experimental-lazy-instances .. versionadded:: 2.8.0 Opt into the experimental, faster implementation of instance search. This is presently optional since it may potentially introduce regressions in code which relies on the order of constraint solving. Default: ``--no-experimental-lazy-instances``. The ``--experimental-lazy-instances`` behaviour will be made the default and this flag will be removed in the future. Other features ~~~~~~~~~~~~~~ .. option:: --double-check Enable double-checking of all terms using the internal typechecker. Off by default. .. option:: --no-double-check .. versionadded:: 2.6.2 Opposite of :option:`--double-check`. On by default. .. option:: --keep-covering-clauses .. versionadded:: 2.6.3 Save function clauses computed by the coverage checker to the interface file. Required by some external backends. .. option:: --no-keep-covering-clauses .. versionadded:: 2.6.4 Opposite of :option:`--keep-covering-clauses`, default. .. option:: --no-print-pattern-synonyms .. versionadded:: 2.5.4 Always expand :ref:`pattern-synonyms` during printing. With this option enabled you can use pattern synonyms freely, but Agda will not use any pattern synonyms when printing goal types or error messages, or when generating patterns for case splits. .. option:: --print-pattern-synonyms .. versionadded:: 2.6.4 Default, opposite of :option:`--no-print-pattern-synonyms`. .. option:: --safe .. versionadded:: 2.3.0 Disable postulates and unsafe :ref:`OPTIONS` pragmas. Further reading: :ref:`safe-agda`. .. option:: --no-import-sorts .. versionadded:: 2.6.2 Disable the implicit statement ``open import Agda.Primitive using (Type; ...)`` at the start of each top-level Agda module. .. option:: --import-sorts .. versionadded:: 2.6.4 Default, opposite of :option:`--no-import-sorts`. Brings ``Type``, ``Typeω``, ``SSet`` and ``SSetω`` into scope, and if :option:`--prop` is active, also ``Prop``. .. option:: --no-load-primitives .. versionadded:: 2.6.3 Do not load the primitive modules (``Agda.Primitive``, ``Agda.Primitive.Cubical``) when type-checking this program. This is useful if you want to declare Agda's very magical primitives in a Literate Agda file of your choice. If you are using this option, it is your responsibility to ensure that all of the ``BUILTIN`` things defined in those modules are loaded. Agda will not work otherwise. Implies :option:`--no-import-sorts`. Incompatible with :option:`--safe`. .. option:: --load-primitives .. versionadded:: 2.6.4 Default, opposite of :option:`--no-load-primitives`. .. option:: --save-metas, --no-save-metas .. versionadded:: 2.6.3 Save [or do not save] meta-variables in ``.agdai`` files. Not saving means that all meta-variable solutions are inlined into the interface. Currently, even if :option:`--save-metas` is used, very few meta-variables are actually saved, and this option is more like an anticipation of possible future optimizations. Default: :option:`--no-save-metas`. .. option:: --lossy-unification .. versionadded:: 2.6.4 Enable lossy unification, see :ref:`lossy-unification`. .. option:: --quote-metas .. versionadded:: 2.9.0 Allow typechecking to quote terms that contain metas, see :ref:`quote-metas`. .. option:: --no-quote-metas .. versionadded:: 2.9.0 Block typechecking when attempting to quote terms that contain metas. Opposite of :option:`--quote-metas`, default. .. _warnings: Warnings -------- The :option:`-W` or :option:`--warning` option can be used to disable or enable different warnings. The flag ``-W error`` (or ``--warning=error``) can be used to turn all warnings into errors, while ``-W noerror`` turns this off again. A group of warnings can be enabled by ``-W {GROUP}``, where ``GROUP`` is one of the following: .. option:: all All of the existing warnings. .. option:: warn Default warning level. .. option:: ignore Ignore all warnings. The command ``agda --help=warning`` provides information about which warnings are turned on by default. Benign warnings ~~~~~~~~~~~~~~~ Individual non-fatal warnings can be turned on and off by ``-W {NAME}`` and ``-W no{NAME}`` respectively. The list containing any warning ``NAME`` can be produced by ``agda --help=warning``: .. option:: AbsurdPatternRequiresAbsentRHS .. versionadded:: 2.8.0 (Previously named ``AbsurdPatternRequiresNoRHS``.) RHS given despite an absurd pattern in the LHS. .. option:: BuiltinDeclaresIdentifier .. versionadded:: 2.7.0 A ``BUILTIN`` pragma that declares an identifier, but has been given an existing one. .. option:: AsPatternShadowsConstructorOrPatternSynonym .. versionadded:: 2.6.2 ``@``-patterns that shadow constructors or pattern synonyms. .. option:: CantGeneralizeOverSorts .. versionadded:: 2.6.0 Attempts to generalize over sort metas in ``variable`` declaration. .. option:: ClashesViaRenaming .. versionadded:: 2.6.1 Clashes introduced by ``renaming``. .. option:: ConflictingPragmaOptions .. versionadded:: 2.7.0 Conflicting pragma options. For instance, both ``--this`` and ``--no-that`` when ``--this`` implies ``--that``. .. option:: CoverageNoExactSplit .. versionadded:: 2.5.3 Failed exact split checks. .. option:: DeprecationWarning .. versionadded:: 2.5.3 Deprecated features. .. option:: DefinitionBeforeDeclaration .. versionadded:: 2.9.0 Definitions that occur in ``mutual`` blocks before their declarations. .. option:: DuplicateFields .. versionadded:: 2.6.4 ``record`` expression with duplicate field names. .. option:: DuplicateRecordDirective .. versionadded:: 2.7.0 Conflicting directives in a record declaration. .. option:: DuplicateUsing .. versionadded:: 2.6.2 Repeated names in ``using`` directive. .. option:: DisplayPragmaInParametrisedModule .. versionadded:: 2.9.0 Display pragma has been declared in a parametrised module. .. option:: EmptyAbstract .. versionadded:: 2.5.4 Empty ``abstract`` blocks. .. option:: EmptyConstructor .. versionadded:: 2.6.2 Empty ``data _ where`` blocks. .. option:: EmptyField .. versionadded:: 2.6.1 Empty ``field`` blocks. .. option:: EmptyGeneralize .. versionadded:: 2.6.0 Empty ``variable`` blocks. .. option:: EmptyInstance .. versionadded:: 2.5.4 Empty ``instance`` blocks. .. option:: EmptyMacro .. versionadded:: 2.5.4 Empty ``macro`` blocks. .. option:: EmptyMutual .. versionadded:: 2.5.4 Empty ``mutual`` blocks. .. option:: EmptyPolarityPragma .. versionadded:: 2.8.0 :ref:`POLARITY pragmas ` not giving any polarities. .. option:: EmptyPostulate .. versionadded:: 2.5.4 Empty ``postulate`` blocks. .. option:: EmptyPrimitive .. versionadded:: 2.6.0 Empty ``primitive`` blocks. .. option:: EmptyPrivate .. versionadded:: 2.5.4 Empty ``private`` blocks. .. option:: EmptyWhere .. versionadded:: 2.6.2 Empty ``where`` blocks. .. option:: FaceConstraintCannotBeHidden .. versionadded:: 2.6.4 Face constraint patterns that are given as implicit arguments. .. option:: FaceConstraintCannotBeNamed .. versionadded:: 2.6.4 Face constraint patterns that are given as named arguments. .. option:: FixityInRenamingModule .. versionadded:: 2.6.1 Fixity annotations in ``renaming`` directives for a ``module``. .. option:: HiddenGeneralize .. versionadded:: 2.6.3 Hidden identifiers in ``variable`` blocks. .. option:: IllegalDeclarationInDataDefinition .. versionadded:: 2.6.4 Declarations inside of a ``data`` definition that are not constructor type signatures. .. option:: IllformedAsClause .. versionadded:: 2.6.0 Illformed ``as``-clauses in ``import`` statements. .. option:: InlineNoExactSplit .. versionadded:: 2.6.4 Failed exact splits after inlining a constructor, see :ref:`inline-pragma`. .. option:: InstanceNoOutputTypeName .. versionadded:: 2.6.0 Instance arguments whose type does not end in a named or variable type; such are never considered by instance search. .. option:: InstanceArgWithExplicitArg .. versionadded:: 2.6.0 Instance arguments with explicit arguments; such are never considered by instance search. .. option:: InstanceWithExplicitArg .. versionadded:: 2.6.0 Instance declarations with explicit arguments; such are never considered by instance search. .. option:: InteractionMetaBoundaries .. versionadded:: 2.6.4 Interaction meta variables that have unsolved boundary constraints. .. option:: InvalidCatchallPragma .. versionadded:: 2.5.4 :ref:`CATCHALL` pragmas before a non-function clause. .. option:: InvalidCharacterLiteral .. versionadded:: 2.6.4 Illegal character literals such as surrogate code points. .. option:: InvalidConstructorBlock .. versionadded:: 2.6.2 ``constructor`` blocks outside of ``interleaved mutual`` blocks. .. option:: InvalidCoverageCheckPragma .. versionadded:: 2.6.1 :ref:`NON_COVERING ` pragmas before non-function or ``mutual`` blocks. .. option:: InvalidDataOrRecDefParameter .. versionadded:: 2.9.0 A ``data/record D parameters where`` definition where the parameters do not match up with the previously given signature or contain more than just names with hiding information. .. option:: InvalidNoPositivityCheckPragma .. versionadded:: 2.5.4 :ref:`NO_POSITIVITY_CHECK ` pragmas before something that is neither a ``data`` nor ``record`` declaration nor a ``mutual`` block. .. option:: InvalidNoUniverseCheckPragma .. versionadded:: 2.6.0 :ref:`NO_UNIVERSE_CHECK ` pragmas before declarations other than ``data`` or ``record`` declarations. .. option:: InvalidTacticAttribute .. versionadded:: 2.9.0 :ref:`@(tactic ...) ` attributes where they are not supported. .. option:: InvalidTerminationCheckPragma .. versionadded:: 2.5.4 :ref:`Termination checking pragmas ` before non-function or ``mutual`` blocks. .. option:: InversionDepthReached .. versionadded:: 2.5.4 Inversions of pattern-matching failed due to exhausted inversion depth. .. option:: LibUnknownField .. versionadded:: 2.6.0 Unknown fields in library files. .. option:: MisplacedAttributes .. versionadded:: 2.8.0 Attributes where they cannot appear. .. option:: MissingTypeSignatureForOpaque .. versionadded:: 2.7.0 ``abstract`` or ``opaque`` definitions that lack a type signature. .. option:: ModuleDoesntExport .. versionadded:: 2.6.0 Names mentioned in an import statement which are not exported by the module in question. .. option:: NoMain .. versionadded:: 2.7.0 Invoking the compiler on a module without a ``main`` function. See also :option:`--no-main`. .. option:: NotAffectedByOpaque .. versionadded:: 2.6.4 Declarations that should not be inside ``opaque`` blocks. .. option:: NotInScope .. versionadded:: 2.6.1 Out of scope names. .. option:: OldBuiltin .. versionadded:: 2.5.2 Deprecated :ref:`BUILTIN` pragmas. .. option:: OpenImportAbstract .. versionadded:: 2.8.0 ``open`` or ``import`` statements in ``abstract`` blocks. .. option:: OpenImportPrivate .. versionadded:: 2.8.0 ``open`` or ``import`` statements in ``private`` blocks. .. option:: OptionRenamed .. versionadded:: 2.6.3 Renamed options. .. option:: PatternShadowsConstructor .. versionadded:: 2.6.4 Pattern variables that shadow constructors. .. option:: PolarityPragmasButNotPostulates .. versionadded:: 2.5.4 Polarity pragmas for non-postulates. .. option:: PragmaCompileWrongName .. versionadded:: 2.8.0 `COMPILE` pragmas referring to identifiers that are neither definitions nor constructors. .. option:: PragmaExpectsDefinedSymbol .. versionadded:: 2.8.0 Pragmas referring to identifiers that are not defined symbols. .. option:: PragmaExpectsUnambiguousConstructorOrFunction .. versionadded:: 2.8.0 Pragmas referring to identifiers that are not unambiguous constructors or functions. .. option:: PragmaExpectsUnambiguousProjectionOrFunction .. versionadded:: 2.8.0 Pragmas referring to identifiers that are not unambiguous projections or functions. .. option:: PragmaNoTerminationCheck .. versionadded:: 2.6.0 :ref:`NO_TERMINATION_CHECK` pragmas; such are deprecated. .. option:: InvalidDisplayForm .. versionadded:: 2.8.0 An illegal :ref:`DISPLAY ` form; it will be ignored. .. option:: RewritesNothing .. versionadded:: 2.8.0 ``rewrite`` clauses that do not fire. .. option:: ShadowingInTelescope .. versionadded:: 2.6.1 Repeated variable name in telescope. .. option:: ShouldBeEtaRecordPattern .. versionadded:: 2.9.0 Irrefutable record pattern without eta. .. option:: TooManyArgumentsToSort .. versionadded:: 2.8.0 E.g. ``Type`` used with more than one argument. .. option:: TooManyFields .. versionadded:: 2.6.4 Record expression with invalid field names. .. option:: TooManyPolarities .. versionadded:: 2.8.0 :ref:`POLARITY pragma ` with too many polarities given. .. option:: UnfoldingWrongName .. versionadded:: 2.8.0 Names in an ``unfolding`` clause that are not unambiguous definitions. .. option:: UnfoldTransparentName .. versionadded:: 2.6.4 Non-``opaque`` names mentioned in an ``unfolding`` clause. .. option:: UnknownAttribute .. versionadded:: 2.8.0 Unknown attributes. .. option:: UnknownFixityInMixfixDecl .. versionadded:: 2.5.4 Mixfix names without an associated fixity declaration. .. option:: UnknownPolarity .. versionadded:: 2.8.0 Unknown polarities. .. option:: UnreachableClauses .. versionadded:: 2.5.3 Unreachable function clauses. .. option:: UnsupportedAttribute .. versionadded:: 2.6.2 Unsupported attributes. .. option:: UnsupportedIndexedMatch .. versionadded:: 2.6.3 Failures to compute full equivalence when splitting on indexed family. .. option:: UnusedImports .. versionadded:: 2.9.0 Warn about openings of modules that do not bring identifiers into scope that are subsequently used. If the ``open`` comes with an explicit ``using`` or ``renaming`` directive, warn about individual unused identifiers (typically those mentioned in the directive). There is no warning about ``public`` openings. In the presence of option:`--no-qualified-instances`, there are also no warnings about unused instances brought into scope. This warning is off by default. .. option:: UnusedImports=all .. versionadded:: 2.9.0 Same as :option:`UnusedImports`, but warn about each unused identifier also when no ``using`` or ``renaming`` directive is given. Option ``-WnoUnusedImports`` disables both :option:`UnusedImports` and :option:`UnusedImports=all`. .. option:: UnusedVariablesInDisplayPragma .. versionadded:: 2.8.0 :ref:`DISPLAY ` forms that bind variables they do not use. .. option:: UselessAbstract .. versionadded:: 2.5.4 ``abstract`` blocks where they have no effect. .. option:: UselessHiding .. versionadded:: 2.6.2 Names in ``hiding`` directive that are anyway not imported. .. option:: UselessInline .. versionadded:: 2.5.3 :ref:`INLINE` pragmas where they have no effect. .. option:: UselessImport .. versionadded:: 2.9.0 ``import`` statements that do not bring anything into scope. .. option:: UselessInstance .. versionadded:: 2.5.4 ``instance`` blocks where they have no effect. .. option:: UselessMacro .. versionadded:: 2.7.0 ``macro`` blocks where they have no effect. .. option:: UselessOpaque .. versionadded:: 2.6.4 ``opaque`` blocks that have no effect. .. option:: UselessPatternDeclarationForRecord .. versionadded:: 2.6.2 ``pattern`` directives where they have no effect. .. option:: UselessPragma .. versionadded:: 2.6.4 Pragmas that get ignored. .. option:: UselessPrivate .. versionadded:: 2.5.4 ``private`` blocks where they have no effect. .. option:: UselessPublic .. versionadded:: 2.5.3 ``public`` directives where they have no effect. .. option:: UselessTactic .. versionadded:: 2.8.0 ``@tactic`` attributes in non-hidden and instance arguments. .. option:: UserWarning .. versionadded:: 2.5.4 User-defined warnings added using one of the ``WARNING_ON_*`` pragmas. .. option:: WarningProblem .. versionadded:: 2.7.0 Problem encountered with option :option:`-W`, like an unknown warning or the attempt to switch off a non-benign warning. .. option:: WithClauseProjectionFixityMismatch .. versionadded:: 2.8.0 Projection fixity different in with-clause compared to its parent clause. .. option:: WrongInstanceDeclaration .. versionadded:: 2.6.0 Terms marked as eligible for instance search whose type does not end with a name. .. option:: CustomBackendWarning .. versionadded:: 2.7.0 Warnings from custom backends. Error warnings ~~~~~~~~~~~~~~ Some warnings are fatal; those are errors Agda first ignores but eventually raises. Such *error warnings* are always on, they cannot be toggled by :option:`-W`. .. option:: AbstractInLetBindings .. versionadded:: 2.8.0 Let bindings can not be made abstract. .. option:: CoinductiveEtaRecord .. versionadded:: 2.7.0 Declaring a ``record`` type as both ``coinductive`` and having ``eta-equality``. .. option:: CoInfectiveImport .. versionadded:: 2.6.0 Importing a file not using e.g. :option:`--safe` from one which does. .. option:: ConstructorDoesNotFitInData .. versionadded:: 2.7.0 Constructor with arguments in a universe higher than the one of its data type. .. option:: CoverageIssue .. versionadded:: 2.5.3 Failed coverage checks. .. option:: HiddenNotInArgumentPosition .. versionadded:: 2.8.0 Hidden arguments ``{ x }`` can only appear as arguments to functions, not as expressions by themselves. .. option:: InfectiveImport .. versionadded:: 2.6.0 Importing a file using e.g. :option:`--prop` into one which does not. .. option:: InstanceNotInArgumentPosition .. versionadded:: 2.8.0 Instance arguments ``⦃ x ⦄`` can only appear as arguments to functions, not as expressions by themselves. .. option:: MacroInLetBindings .. versionadded:: 2.8.0 Macros can not be let-bound. .. option:: MismatchedBrackets .. versionadded:: 2.9.0 An idiom bracket opened with unicode (resp. ASCII) syntax must also be closed with unicode (resp. ASCII) syntax. .. option:: MissingDataDeclaration .. versionadded:: 2.8.0 Constructor definitions not associated to a data declaration. .. option:: MissingDefinitions .. versionadded:: 2.6.0 Names declared without an accompanying definition. .. option:: NotAllowedInMutual .. versionadded:: 2.6.0 Declarations that are not allowed in a mutual block. .. option:: NotStrictlyPositive .. versionadded:: 2.5.2 Failed strict positivity checks. .. option:: OverlappingTokensWarning .. versionadded:: 2.5.4 Multi-line comments spanning one or more literate text blocks. .. option:: PragmaCompiled .. versionadded:: 2.6.0 `COMPILE` pragmas not allowed in safe mode. .. option:: RecursiveRecordNeedsInductivity .. versionadded:: 2.7.0 Recursive records that are neither declared ``inductive`` nor ``coinductive``. .. option:: SafeFlagEta .. versionadded:: 2.6.1 :ref:`ETA ` pragmas with the :option:`--safe` flag. .. option:: SafeFlagInjective .. versionadded:: 2.6.1 :ref:`INJECTIVE ` pragmas with the :option:`--safe` flag. .. option:: SafeFlagNoCoverageCheck .. versionadded:: 2.6.1 :ref:`NON_COVERING ` pragmas with the :option:`--safe` flag. .. option:: SafeFlagNonTerminating .. versionadded:: 2.5.3 :ref:`NON_TERMINATING ` pragmas with the :option:`--safe` flag. .. option:: SafeFlagNoPositivityCheck .. versionadded:: 2.5.3 :ref:`NO_POSITIVITY_CHECK ` pragmas with the :option:`--safe` flag. .. option:: SafeFlagNoUniverseCheck .. versionadded:: 2.6.0 :ref:`NO_UNIVERSE_CHECK ` pragmas with the :option:`--safe` flag. .. option:: SafeFlagPolarity .. versionadded:: 2.5.3 :ref:`POLARITY ` pragmas with the :option:`--safe` flag. .. option:: SafeFlagPostulate .. versionadded:: 2.5.3 ``postulate`` blocks with the :option:`--safe` flag. .. option:: SafeFlagPragma .. versionadded:: 2.5.3 Unsafe :ref:`OPTIONS ` pragmas with the :option:`--safe` flag. .. option:: SafeFlagTerminating .. versionadded:: 2.5.3 :ref:`TERMINATING ` pragmas with the :option:`--safe` flag. .. option:: TerminationIssue .. versionadded:: 2.5.2 Failed termination checks. .. option:: UnknownNamesInFixityDecl .. versionadded:: 2.5.4 Names not declared in the same scope as their syntax or fixity declaration. .. option:: UnknownNamesInPolarityPragmas .. versionadded:: 2.5.4 Names not declared in the same scope as their polarity pragmas. .. option:: UnsolvedConstraints .. versionadded:: 2.5.2 Unsolved constraints. .. option:: UnsolvedInteractionMetas .. versionadded:: 2.5.2 Unsolved interaction meta variables. .. option:: UnsolvedMetaVariables .. versionadded:: 2.5.2 Unsolved meta variables. Command-line examples --------------------- Run Agda with all warnings enabled, except for warnings about empty ``abstract`` blocks: .. code-block:: console agda -W all --warning=noEmptyAbstract file.agda Run Agda on a file which uses the standard library. Note that you must have already created a ``libraries`` file as described in :ref:`package-system`. .. code-block:: console agda -l standard-library -i. file.agda (Or if you have added ``standard-library`` to your ``defaults`` file, simply ``agda file.agda``.) .. _consistency-checking-options: Checking options for consistency -------------------------------- Agda checks that options used in imported modules are consistent with each other. An *infective* option is an option that if used in one module, must be used in all modules that depend on this module. The following options are infective: * :option:`--prop` A *coinfective* option is an option that if used in one module, must be used in all modules that this module depends on. The following options are coinfective: * :option:`--level-universe` * :option:`--safe` Agda records the options used when generating an interface file. If any of the following options differ when trying to load the interface again, the source file is re-typechecked instead: * :option:`--allow-exec` * :option:`--allow-incomplete-matches` * :option:`--allow-unsolved-metas` * :option:`--backtracking-instance-search` * :option:`--call-by-name` * :option:`--copatterns` * :option:`--double-check` * :option:`--exact-split` * :option:`--hidden-argument-puns` * :option:`--infer-absurd-clauses` * :option:`--instance-search-depth` * :option:`--inversion-max-depth` * :option:`--keep-covering-clauses` * :option:`--lossy-unification` * :option:`--no-auto-inline` * :option:`--no-eta-equality` * :option:`--no-fast-reduce` * :option:`--no-forcing` * :option:`--no-import-sorts` * :option:`--no-load-primitives` * :option:`--no-pattern-matching` * :option:`--no-positivity-check` * :option:`--no-projection-like` * :option:`--no-termination-check` * :option:`--no-unicode` * :option:`--prop` * :option:`--qualified-instances` * :option:`--quote-metas` * :option:`--safe` * :option:`--save-metas` * :option:`--termination-depth` * :option:`--warning` .. _Vim: https://www.vim.org/ .. _Dot: http://www.graphviz.org/content/dot-language .. _command-line-options-refs: References ---------- [1] Jesper Cockx and Dominique Devriese. `"Proof-relevant unification: Dependent pattern matching with only the axioms of your type theory." `_ In Journal of Functional Programming 28, 2018.