commit e08d07692fa7f2dd0cd139cb0c7e359be4264d8a Author: Nick Mathewson nickm@torproject.org Date: Mon Jan 6 13:31:30 2020 -0500

Add documentation about building a TAGS file.

Patch from opara. Closes ticket 32779. --- changes/ticket32779 | 3 +++ doc/HACKING/HelpfulTools.md | 24 ++++++++++++++++++++++++ 2 files changed, 27 insertions(+)

diff --git a/changes/ticket32779 b/changes/ticket32779 new file mode 100644 index 000000000..1b7ccaa7e --- /dev/null +++ b/changes/ticket32779 @@ -0,0 +1,3 @@ + o Documentation: + - Add documentation in 'HelpfulTools.md' to describe how to build a tag + file. Closes ticket 32779. diff --git a/doc/HACKING/HelpfulTools.md b/doc/HACKING/HelpfulTools.md index cba57e875..866b32128 100644 --- a/doc/HACKING/HelpfulTools.md +++ b/doc/HACKING/HelpfulTools.md @@ -315,6 +315,30 @@ If you use emacs for editing Tor and nothing else, you could always just say: There is probably a better way to do this. No, we are probably not going to clutter the files with emacs stuff.

+Building a tag file (code index) +-------------------------------- + +Many functions in tor use `MOCK_IMPL` wrappers for unit tests. Your +tag-building program must be told how to handle this syntax. + +If you're using emacs, you can generate an emacs-compatible tag file using +`make tags`. This will run your system's `etags`. Tor's build system assumes +that you're using the emacs-specific version of `etags` (bundled under the +`xemacs21-bin` package on Debian). This is incompatible with other versions of +`etags` such as the version provided by Exuberant Ctags. + +If you're using vim or emacs, you can also use Universal Ctags to build a tag +file using the syntax: + + ctags -R -D 'MOCK_IMPL(r,h,a)=r h a' . + +If you're using an older version of Universal Ctags, you can use the following +instead: + + ctags -R --mline-regex-c='/MOCK_IMPL([^,]+,\W*([a-zA-Z0-9_]+)\W*,/\1/f/{mgroup=1}' . + +A vim-compatible tag file will be generated by default. If you use emacs, add +the `-e` flag to generate an emacs-compatible tag file.

Doxygen -------