Author:         Jan Nijtmans <jan.nijtmans@gmail.com>
State:          Final
Type:           Project
Vote:           Done
Created:        08-Dec-2016
Post-History:   
Keywords:       Tcl,package
Tcl-Version:    8.7

Abstract

This TIP proposes to improve package introspection by providing a new command package files.

Rationale

This TIP is inspired by a request from FlightAware to improve Tcl's package introspection possibilities. Although only a package files command was requested, extending info loaded gives the possibility to find a shared library contained in a package more easily than searching a list.

Specification of the proposed Change

Two new additions are proposed, to the package and info commands.

1. package files name

   This command returns a list of filenames which were sourced during the initialization of package name. More specific, the files that were sourced during running the script registered using package ifneeded. Left out are Tcl's own tclIndex and pkgIndex.tcl files, which might have been accessed due to dependancy searches, otherwise this would give very misleading results.

2. info loaded ?interpreter? ?name?

   The info loaded command already exists, it gives a list of package names with corresponding shared library names which were actually loaded in the give interpreter. The additional name argument restricts the result to the filename of the loaded library only.

Tcl packages don't have to do anything special in order to be introspected correctly, just note that files containing auto_loaded commands cannot be introspected because they are not sourced during package initialization.

Rejected alternatives

Use of source -nopkg in tclIndex files. Even though this addition in the earlier TIP was explicitly undocumented, it lead to the misunderstanding that other Tcl extensions should do the same.

Earlier implementation of this TIP didn't handle the second argument of info loaded correctly in all cases, and the handling in safe interpreters was not complete. This is all corrected in the current implementation.

All filenames should be converted to absolute. This is rejected for performance and for practical reasons. It could be quite expensive to calculate because the disk has to be accessed for possible hyper-links. Second, the package mechanism is already designed such that all sourced paths are absolute (see below example). Extensions using the source command with relative paths are in danger already, this should be fixed in the extension in stead of being masked in the package files command.

Additional information about the sourced files (like mtime or checksum) was suggested to be part of the introspection information, but this has been rejected as overkill. It is much more than requested in the Tcl-bounty, and it is difficult to imagine what actual use this would bring.

Reference Implementation

This is available in the package_files branch http://core.tcl.tk/tcl/timeline?r=package_files .

Examples

$ tclsh8.7
% package files Tcl
/usr/lib/tcl8.7/init.tcl
% package require Tk
8.7a0
% package files msgcat
/usr/lib/tcl8/8.5/msgcat-1.6.0.tm
% package files Tk
/usr/lib/tk8.7/tk.tcl /usr/lib/tk8.7/msgs/en.msg /usr/lib/tk8.7/icons.tcl ...
% info loaded {} Tk
/usr/lib/libtk8.7.so

Note that package require Tk has the side-effect of loading the msgcat package, which is required by Tk.

Copyright

This document has been placed in the public domain.

Please note that any correspondence to the author concerning this TIP is considered in the public domain unless otherwise specifically requested by the individual(s) authoring said correspondence. This is to allow information about the TIP to be placed in a public forum for discussion.