z3c.recipe.tag 1.0

Introduction

This recipe generates a TAGS database file that can be used with a number of different editors to quickly look up class and function definitions in your package’s source files and egg dependencies.

Dependencies

Before running a tags enabled buildout, you must install the appropriate command line tag generation tools: exuberant-ctags and id-utils. In Ubuntu, you can install these with apt-get:

$ sudo apt-get install exuberant-ctags id-utils

On a Mac, download and install port from http://www.macports.org/ and then install ctags and idutils in this way:

$ sudo port install ctags idutils

How to use this recipe

[tags]
recipe = z3c.recipe.tag
eggs = MyApplication

$ ./bin/tags

usage: build_tags [options]

options:
  -h, --help            show this help message and exit
  -l LANGUAGES, --languages=LANGUAGES
                        ctags comma-separated list of languages. defaults to
                        ``-JavaScript``
  -e, --ctags-emacs     flag to build emacs ctags ``TAGS`` file
  -v, --ctags-vi        flag to build vi ctags ``tags`` file
  -b, --ctags-bbedit    flag to build bbedit ctags ``tags`` file
  -i, --idutils         flag to build idutils ``ID`` file

[tags]
recipe = z3c.recipe.tag
eggs = MyApplication
default = ['-v']

my_venv/bin/pip install z3c.recipe.tag
my_venv/bin/build_tags

import z3c.recipe.tag

$ paver z3c.recipe.tag.tags

Additional Resources

For additional information on using tags tables with different editors see the following websites:

• Emacs: http://www.gnu.org/software/emacs/manual/html_node/emacs/Tags.html

  • to jump to the location of a tag, type M-x find-tag and the name of the tag. Or use M-. to jump to the tag matching the token the cursor is currently on. The first time you do this, you will be prompted for the location of the TAGS file.

• VIM: http://vimdoc.sourceforge.net/htmldoc/tagsrch.html

• BBEdit: http://pine.barebones.com/manual/BBEdit_9_User_Manual.pdf Chapter 14, page 324

For more information on ctags, visit http://ctags.sourceforge.net/

(BBEdit is a Macintosh text editor.)

For more information about GNU id-utils (basically a local text indexing/search engine; think of it as a very fast version of grep -w), see the id-utils manual.

1.0 (2023-02-09)

• Drop support for Python < 3.7.

• Add support for Python 3.7 up to 3.11.

• Require zc.buildout >= 3.

0.8 (2014-10-20)

• Add –tag-relative option to support relative tag generation.

0.7 (2013-03-22)

• Support and require zc.buildout 2.0.

• Add supported Python version (3.6, 2.7, 3.2, 3.3) classifiers to setup.py

0.6 (2012-09-07)

• Update manifest to allow package generation fron non-VCS export. Counters the 0.5 “brown bag” release.

0.5 (2012-09-06)

• Exclude Python import statements by default from showing up as tags.

• Add ‘defaults’ option to allow adding default command line options (e.g. to set ‘-v’ by default)

0.4.1 (2012-01-11)

• Skip nonexistent sys.path directories to avoid ctags warnings.

0.4.0 (2010-08-29)

• Support new script features from zc.buildout 1.5 and higher. This version requires zc.buildout 1.5 or higher.

• Also index Mako and HTML files with id-utils.

0.3.0 (2009-08-16)

• Add support for using this recipe as a paver task.

• Also index Javascript, CSS and ReStructuredText files with id-utils.

• Define a default entry point for zc.buildout, so you can simply say:

  [ctags]
  recipe = z3c.recipe.tag

0.2.0 (2008-08-28)

• Allow command-line choices for what files to build, and what languages ctags should parse. (Note that the default behavior of running ./bin/tags is the same as previous releases.)

• Support the Mac OS X packaging system “macports” (exuberant ctags is ctags-exuberant in Ubuntu and ctags in macports).

• Support creating BBEdit-style ctags files.

• Small changes for development (use bootstrap external, set svn:ignore)

0.1.0 (2008-03-16)

• Initial release.

  • buildout recipe for generating ctags of eggs used.