Jim Brooks
http://www.jimbrooks.org/hypersrc/
2006/11/05

Synopsis
========

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

Legal
=====

This is "copy-left software" that is distributed with, protected by,
and licensed under the GNU General Public License (see "LICENSE.txt").
This software is provided "AS-IS" without any express or implied warranty nor guarantee.
In no event will the author be held liable for any damages arising from
the use of this software nor derivative works.

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

The latest version is available at:
http://www.jimbrooks.org/hypersrc/
http://freshmeat.net/projects/hypersrc/

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

- GNU system, GTK 1.2.x and GNOME 1.x

  These packages are now considered obsolete [in 2006].
  Modern Linux distributions no longer install them.

  FreeBSD:
  hypersrc is maintained as a FreeBSD port.

  Linux Fedora 5:
  yum install gnome-libs gtk+ glib
  yum install gnome-libs-devel gtk+-devel glib-devel

  Linux Fedora 3:
  glib-devel-1.2.10-15.i386.rpm
  gtk+-devel-1.2.10-33.i386.rpm
  gnome-libs-1.4.1.2.90-44.i386.rpm
  gnome-libs-devel-1.4.1.2.90-44.i386.rpm
  compat-db-4.1.25-6.i386.rpm
  imlib-devel-1.9.13-21.i386.rpm
  libIDL-devel-0.8.4-1.i386.rpm
  ORBit-0.5.17-14.i386.rpm
  ORBit-devel-0.5.17-14.i386.rpm

  Old (pre 200) distros:
  Minimum GTK+ 1.2.6.
  GTK+ 1.2.3 had a bug that caused segfault when a tag is clicked (see below).

- "Exuberant ctags" 3.2 (or newer) by Darren Hiebert.

  (Usually installed)
  hypersrc won't work with GNU ctags, but will if Exuberant ctags is
  also installed somewhere (see the next section about the -ctags arg).
  Exuberant ctags webpage is: http://ctags.sourceforge.net
  and various versions of it are at: http://www.rpmfind.net

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

See INSTALL.txt

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

The executable "hypersrc" isn't (normally) intended to be run directly.
Rather, 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.
In case you have GNU ctags also installed or Hypersrc.pl fails to find
Exuberant ctags automatically, pass -ctags [pathname] to Hypersrc.pl.
See "Hypersrc.pl -help".

Examples:

  Hypersrc.pl                        # browse C based on CWD (descends a few subdirs)
  Hypersrc.pl  src/gui  src/inc      # browse C in two dirs  (descends a few 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:

  Hypersrc.pl  -descend 0            # don't descend down to any subdir
  Hypersrc.pl  -descend 1            # descend only one subdir level
  Hypersrc.pl  -lang c++,perl        # browse only C++ and Perl source files
  Hypersrc.pl  -lang c++ perl        # WRONG, must be one comma-separated word
  Hypersrc.pl  -langmap=c:+.d *.d    # treat .d files as C src files
  Hypersrc.pl  -exclude obj/,bak/    # exclude files in these subdirs
  Hypersrc.pl  -ext .cc              # browse only source files ending with .cc
  Hypersrc.pl  -geom 80 160 940 600  # set size/position of main window
  Hypersrc.pl  -max-tags 500000      # set limit of tags to process

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

Many 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 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 "-fast" to speed startup.
Even faster is "-fast -no-functree" (but forfeits tree views).
For the daring, build an optimized executable:  "make speed install"
But the drawback is that many self-checks won't be compiled.

Pass "-conserve" to reduce memory consumption.

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.
  For example, on a Pentium II, the program will take more than 90 minutes
  and 105 megs when starting to browse the entire Linux 2.4 source!

- Can't handle filenames containing spaces.

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,
  manually edit the line with $ctags in Hypersrc.pl.

- Won't browse K&R (Kernighan & Ritchie) style C source files:

  Try passing -knr (by default K&R functions are skipped for better parsing).

  Eg:
  int func( a )
            int a;
  {
  }

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

- Functions are missing in the tree view.

  - By design, functions (except inline class methods) whose opening braces
    aren't the first char on the line won't be parsed:
    int foo ( int a ) {
    }
  - hypersrc requires the -knr arg to parse K&R style functions.
  - Source code heavily infested with #if directives just won't be parsed correctly.

- 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.  See also section about speeding hypersrc.
  Try passing any of:
  -fast
  -no-functree : to skip parsing phase but forfeit tree views of functions
  -descend     : to limit the amount of subdirs to descend
  -max-tags    : to limit the amount of tags to be processed
  -exclude     : to exclude some dirs/files

- 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.

- 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, which can happen if a browsed function
  is called hundreds of times.

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

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

   ./configure.sh
   make debug install

   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.

Testing
=======

- Exuberant ctags 5.5.x
- Mandrake 8.1, Redhat 8, Debian 3.0, FreeBSD 4.6.2, Fedora 3 and 5
- CPU: x86-32, x86-64
- GTK+ 1.2.10
- XFree86 4.1/4.2
- gcc 2.95/3.3.3/3.4/4.1
- Valgrind

Misc
====

For programmers wishing to modify hypersrc's source code, "make docs"
will auto-generate HTML docs from hypersrc's source code using doxygen.
