Some things to beware of when using pkg_mkIndex:

If a script in the library directory fails for any reason when it is ''source''d, then any '''package provide''' statements in that script will not be reflected in the ''pkgIndex.tcl'' file.  Probably the most common cause for failure is that a script calls '''package require''' for a dependant package which cannot be loaded.  For example, package scripts which '''package require Tk''' will fail (on Unix) if the $DISPLAY is not set.  

A more subtle problem: package scripts which '''package require''' other  packages defined by scripts in the same directory will fail the first time you run ''pkg_mkIndex'', but may succeed the second time.  If there are many package interdependencies, it may be necessary to "iterate until convergence" before a working ''pkgIndex.tcl'' comes out.

It is a very good idea for package authors to include prebuilt ''pkgIndex.tcl'' files in the distribution instead of having end-users run ''pkg_mkIndex'' as part of the installation process.  There are too many things that can go wrong.

More often than not, ''pkg_mkIndex'' is overkill anyway: for simple packages it's just as easy to create a ''pkgIndex.tcl'' (or ''pkgIndex.tcl.in'') by hand.

The canonical [TEA] build structure (as of May 2002) uses pkg_mkIndex to build the package index as part of the installation process.  [Don't do that].