Jim Brooks
jim@jimbrooks.org
2001/02/17

Synopsis
========

"hypersrc" is a freeware GTK+/GNOME program for browsing source code. 

Webpage & Updates
=================

The latest version is available at:
http://www.jimbrooks.org/web/hypersrc/hypersrc.html

Requirements
============

- A UNIX system with GNU tools.

  Has been known to compile/run on Linux and FreeBSD 4.2.

- GTK+/GLIB 1.2.6 (recommend 1.2.8 or newer)

  At least one old GTK+ version (1.2.3) definitely has a bug
  that causes a segfault when a tag is clicked (see below).

- GNOME (a recent version)

- "Exuberant ctags" 2.0.3 (recommend 4.0.3 or newer) by Darren Hiebert.

  You probably already have it, if you have a recent Linux distribution.

  hypersrc requires a program capable of producing output equivalent
  to ctags -x option.  hypersrc won't work with plain-old GNU ctags.
  Exuberant ctags webpage is: http://ctags.sourceforge.net

Building/Installing/Quickstart
==============================

See INSTALL.txt

Running hypersrc
================

Use the provided Perl script "Hypersrc.pl" to run hypersrc.

If Hypersrc.pl is called without options, by default, it will gather C src files
in the CWD and in a few subdir levels, and will pass them to hypersrc.

See "Hypersrc.pl -help".

Examples:

  Hypersrc.pl                        # browse C based on CWD (descends into subdirs)
  Hypersrc.pl  src/gui  src/inc      # browse C in two dirs  (descends into subdirs)
  Hypersrc.pl  *.f77                 # browse Fortran files  (in CWD only)
  Hypersrc.pl  myprog/perl           # this will browse C files, not Perl scripts
  Hypersrc.pl  myprog/perl/*.pl      # this will browse Perl scripts

More Examples:
                                     # (each below example descends into subdirs)
  Hypersrc.pl  -descend 1            # descend only one subdir level
  Hypersrc.pl  -lang perl            # browse only Perl source files
  Hypersrc.pl  -lang c  -lang c++    # browse both C and C++ source files
  Hypersrc.pl  -ext .cc              # browse only C++ source files ending with .cc
  Hypersrc.pl  -geom 80 160 940 600  # set size/position of main window
  Hypersrc.pl  -maxtags 9000         # increase tag limit

Customization and Options
=========================

Some preferences can be edited/saved via the GUI.
Preferences can be overridden by corresponding cmd-line options.
All preferences can be ignored by passing "-ignore-prefs".

hypersrc has a set of command line options to support customizing
the maximum amount of tags, tab width, window geometries, fonts, etc.
See "hypersrc -help".

Hypersrc.pl also has its own set of options (see "Hypersrc.pl -help").
Options not recognized by Hypersrc.pl will be passed thru to hypersrc.

Speed/Memory Options
====================

Pass -no-functree to speed startup and conserve memory (but forfeit tree views).

Testing
=======

Recent development/testing has been done using:

- GTK+/GLIB 1.2.6 & 1.2.8
- Exuberant ctags 4.0.3
- Red Hat 6.x
- XFree86 4.0.1 & 3.3.5
- flex 2.5.4a-7, bison 1.28-1
- gcc [egcs] 2.91.66

Limitations
===========

- The maximum amount of tags is ultimately limited by #define MAX_TAGS_ABSOLUTE.

- Be warned that trying to browse everything in a very large source tree will
  TAKE A LARGE AMOUNT OF MEMORY and several minutes to start.  Instead browse
  a few subdirs at a time (cd in a subdir, or pass -dirs and/or -descend).

  For example, on a PentiumII, the program will take more than 90 mintues
  and 105 megs when starting to browse the entire Linux 2.4 source!

- Exuberant ctags, and consequently hypersrc, won't process src files
  in MSDOG (CR/LF) format.

Solutions to Common Problems
============================

- Hypersrc.pl complains about ctags even though my system has it.

  Probably, it only located the GNU (emacs) version of ctags,
  which hypersrc can't use.

  Copy Exuberant ctags to somewhere in PATH.
  Or, if you prefer to copy it somewhere outside of PATH,
  then edit the line with $ctags in Hypersrc.pl.

- On FreeBSD, "make" causes lots of errors.

  Instead use gmake (GNU make).
  And you might need to install a few GNU tools (probably just bison).

Known Problems/Issues
=====================

- hypersrc quits silently while trying to jump to a tag.

  Upgrade to GTK+ 1.2.8 if you are using an older version.
  GTK+ 1.2.3 definitely has a bug which hypersrc encounters.
  Other old versions might have this bug also.

  If this problem still persists, as a last resort, try deselecting the
  preference: "Misc / process GTK+ events while busy".
  However, be advised the program won't redraw itself while it is busy.

- Sometimes, pressing Enter in a find dialog triggers two searches.

  Keyboard rate is too fast?

- Sometimes, parser fails to recognize some function calls/blocks,
  resulting in an empty tree view.

- All functions with the same name will appear in the the "called by"
  tree, regardless if some don't really call this function.

- Rarely, the scrollbar beside a tree will stop working if the tree tries
  to show too many nodes/leafs.

- To browse everything in a humongous source tree, such as the Linux 2.4
  kernel, hypersrc takes a long time to start and lots of memory.

  Yes.

  Try: Hypersrc.pl -no-functree

Trouble-shooting
================

To run hypersrc under gdb (and this enables warning messages, extra checks):

   make debug; make install			# use gmake (GNU make) on BSD

   Hypersrc.pl -gdb

Unsupported Source Files
========================

If you have a source file that Exuberant ctags doesn't support,
then you could write your own parser that produces output
that is similar to the -x option of Exuberant ctags,
and pass the output directly to hypersrc (see "Directly Invoking hypersrc").

Directly Invoking hypersrc
==========================

The only mandatory option for hypersrc is "-ctags-x <file>" which specifies a file
that contains tags in the format used by the -x option of Exuberant ctags, eg:

   ctags  -x *.c  >  tags
   hypersrc  -ctags-x  tags

[ Or instead, -stdin can be used to pipe ctags -x output into hypersrc. ]

See "hypersrc -help" for other options.

Legal
=====

hypersrc is "copy-lefted software" that is distributed and protected
by the GNU General Public License (see "LICENSE.txt").
