Universal-ctags Hacking Guide

Version:Draft Authors:universal-ctags developers Web Page:https://ctags.io/

Universal-ctags was created to continue the development of Darren Hiebert’s Exuberant-ctags after activity on that project unfortunately stalled.

Reza Jelveh <reza.jelveh@gmail.com> initially created a personal fork on GitHub and as interest and participation grew it was decided to move development to a dedicated GitHub organization.

The goal of this project is to maintain a common/unified space where people interested in improving ctags can work together.

This guide is primarily intended for developers. Users should first consult the ctags.1 man page.

This is a draft document. Proofreading and pull-requests are welcome!

• Introduced changes
  • Importing changes from Exuberant-ctags
  • Parser related changes
  • New and extended options
  • Changes to the tags file format
  • Reference tags
  • Automatic parser selection
  • Pseudo tags
  • Parser own fields
  • Parser own extras
  • Parser own parameter
  • Customizing xref output
  • Incompatible changes in command line
  • Skipping utf-8 BOM
  • Readtags
• Request for extending a parser (or Reporting a bug of parser)
  • Before reporting
  • The content of report
  • An example of good report
• Contributions
  • General topics
  • Specific to add new parser and/or new kind/role
• Parsers
  • Asm parser
  • CMake parser
  • The new C/C++ parser
  • The new HTML parser
  • puppetManifest parser
  • The new Python parser
  • The new Tcl parser
  • The Vim parser
  • XSLT parser
• Output formats
  • JSON output
  • Xref output
• --_interactive Mode
  • generate-tags
  • sandbox submode
• Choosing a proper parser in ctags
• Running multiple parsers on an input file
  • Applying a parser to specified areas of input file (guest/host)
  • Tagging definitions of higher(upper) level language (sub/base)
• Building ctags
  • Building with configure (*nix including GNU/Linux)
  • Building/hacking/using on MS-Windows
  • Building on Mac OS
• Testing ctags
  • Units test facility
  • Semi-fuzz(Fuzz) testing
  • Noise testing
  • Chop and slap testing
  • Tmain: a facility for testing main part
  • Tinst installation test
  • Cspell spell checking
  • Input validation for Units
• Extending ctags
  • Extending ctags with Regex parser (optlib)
  • ctags Internal API
• Tips for hacking
  • Fussy syntax checking
  • Finding performance bottleneck
  • Checking coverage
  • Reviewing the result of Units test
  • Running cppcheck
• Relationship between other projects
  • Geany
  • Tracking other projects
  • Software using ctags
• Proposal for extended Vi tags file format
  • Introduction
  • From proposal to standard
  • Backwards compatibility
  • Security
  • Goals
  • Proposal
  • Exceptions in Universal-ctags
• The development guideline
  • Common topics
  • Rules for reviewing a pull request
  • Rules for modifying our repository
  • About documentation
• Who we are