--- name: "otags" section: "1" platform: "linux" package: "otags" version: "4.05.1-3" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/otags" --- # otags(1) generate tags files for emacs and vi/vim from OCaml sources ## NAME otags - generate tags files for emacs and vi/vim from OCaml sources ## SYNOPSIS **otags** \[*STATIC-OPTION*\] ... \[*FILE*\] ... \[*DYNAMIC-OPTION*\] ... \[*FILE*\] ... ## DESCRIPTION **otags** generates *TAGS* files for **emacs** and *tags* files for **vi/vim** to give these editors the ability to directly jump to function and value definitions (use **M-.** in Emacs and **^\]** in vi\[m\] with the cursor on the symbol). **otags** uses the standard **OCaml** parser from the *compiler-libs* library. This is more precise than regular expression based tagging. On the downside, **otags** can only tag syntactically correct files. Furthermore, **otags** is **OCaml** version specific: Sources to be compiled with **OCaml** version *X.Y* can, in general, only be tagged with **otags** version *X.Y.* This version of **otags** does not support *-pp* or *-ppx* preprocessors and can therefore not tag files using syntax extensions or containing top level directives. For tagging all files in a directory tree, see option **-r** below. **otags** tags all toplevel items in structures and signatures, including infix operators and nested modules and signatures. It also tags instance variables and methods in classes. Filenames **FILE** on the command line are parsed as interfaces if they have a **.mli** suffix and as implementations if they have a **.ml** suffix. (See also the dynamic options **-intf** and **-impl.)** Tag files can contain absolute and/or relative file names. **Otags** uses the file names from the command line for the tags file. Specifying relative file names on the command line will therefore give you a tag file with relative file names. Obviously, a tag file with relative file names will only work if it is located in the directory where **otags** was started. **Otags** supports writing a tags file with relative file names in a parent directory via option *-add-path.* ## STATIC OPTIONS Static options take effect on the whole program run, regardless of their position in the command line. - \-r Descend into directories. With this option, if one of the *FILE* arguments is a directory **otags** will recursively tag all files in this whole directory tree. - \-o file Write tags to *file.* The default is *TAGS* (for **emacs)** and *tags* for **vi** (if the **-vi** option is given) in the current directory. If *file* is a dash ( *-* ) the tags are written to standard output. - \-a Append to an existing TAGS file (does only work for emacs TAGS files). - \-vi Generate tags for **vi** and change the default output file into *tags.* - \-add-path path Add *path* at the front of every relative file name in the tags file. Useful when you want to put the tags file in a parent directory. - \-version Print version and exit. - \-v Verbose. Print file names as they are parsed and the command lines for externally started **camlp4** parsing processes (if any). If **-v** is the first command line argument, backtraces for exceptions are enabled and printed if an exception escapes and terminates **otags** (which is considered a bug, about which I would appreciate a bug report). - \-q Be quiet. - \-help Print the option list. - \--help Alias for **-help** ## DYNAMIC OPTIONS Dynamic options do only affect arguments that follow them on the command line. - \-intf FILE Parse and tag **FILE** as an interface. - \-impl FILE Parse and tag **FILE** as implementation. ## EXAMPLES **Tag all** *.ml* and *.mli* files in the current directory tree: **otags** **-r .** Files with syntax errors will be ignored. The error messages can be disabled with option *-q.* ## DIAGNOSTICS Parse errors are reported with normal **OCaml** error messages. No tags are generated for files that produce errors. Tagging continues with the next file, in this case. Warnings are always completely disabled. The errors "Original source not available" and "The parser delivered an invalid location" might be reported if the file contains a line directive that refers to a position and/or a file that cannot be resolved. For files containing a toplevel directive, **Otags** simply reports a syntax error (as **ocamlc** does). Escaping exceptions and assertions that terminate **otags** are considered to be bugs. If they occur, please use option **-v** as **first** command line switch to obtain an exception backtrace and submit this with all relevant information as bug report. ## EXIT STATUS - 0 everything went OK - 1 a parse error or some other error occurred and **otags** skipped the affected file - 2 a fatal error caused **otags** to abort - 3 some bug caused a crash, from which **otags** could only marginally recover ## MISSING FEATURES Appending to vi tags files requires to reread the existing tags file, because vi tags files are sorted. *-pp* and *-ppx* preprocessors are currently not supported. ## HISTORY The first **camlp4** based **OCaml** tagger has been written by Cuihtlauac Alvarado and Jean-Francois Monin. Around 2005 I took over and released a few versions for **OCaml** 3.09. All **otags** versions released up to 3.09.3.3 were written for the original **camlp4,** which is now available as **camlp5.** For 3.11 I rewrote **otags** from scratch for the new **camlp4** and released several versions under the name **otags reloaded.** The modular structure of **camlp4** made it possible to switch the parsing engine at runtime between files and to parse all syntax supported by **camlp4** at full native speed without external **camlp4** processes. However, the increasing incompatibility between **camlp4** and **OCaml** and **camlp4's** sloppiness on parsing locations created more and more difficulties. For instance, 4.02 failed on the **OCaml** standard library because **camlp4** was unable to digest the attribute annotations in there. Starting from 4.03, **otags** is based on the standard **OCaml** parser from the *compiler-libs* library and has been renamed to **otags III.** ## AUTHOR Hendrik Tews \ ## SEE ALSO [**etags**(1)](/etags/1.md), [**ctags**(1)](/ctags/1.md)