\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#459: Tcl Package Introspection Improvements}
\date{December 08, 2016}
\author{Jan Nijtmans}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#459}&\textbf{Tcl Package Introspection Improvements}\\\hline
Author&

Jan Nijtmans \tipmail{jan.nijtmans}{gmail.com}
\\
Created&Thursday, \(\text{8}^{\text{th}}\) December 2016\\
Type&Project\\
Tcl Version&\(8.7\)\\
State&Draft\\
Vote&Pending\\
Version&\tipversion$Revision: 1.6 $\\
Keywords&Tcl, package\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP proposes to improve package introspection by providing a new command \textbf{package files}.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

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

\section{Specification of the proposed Change}

Two new additions are proposed, to the \textbf{package} and \textbf{info} commands.
\begin{enumerate}
\item{}
\textbf{package files} \textit{name}

This command returns a list of filenames which were sourced during the initialization of package \textit{name}. More specific, the files that were sourced during running the script registered using \textbf{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.
\item{}
\textbf{info loaded} ?\textit{interpreter}? ?\textit{name}?

The \textbf{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 \textit{name} argument restricts the result to the filename of the loaded library only.
\end{enumerate}

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.

\section{Rejected alternatives}

\begin{quote}
Use of \textit{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.
\end{quote}

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

\begin{quote}
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 \textbf{source} command with relative paths are in danger already, this should be fixed in the extension in stead of being masked in the \textbf{package files} command.
\end{quote}

\begin{quote}
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.
\end{quote}

\section{Reference Implementation}

This is available in the \textit{package\_files} branch [\url{http://core.tcl.tk/tcl/timeline?r=package_files}].

\section{Examples}
\begingroup\small\begin{verbatim}
$ 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
\end{verbatim}
\endgroup

Note that \textbf{package require Tk} has the side-effect of loading the \textit{msgcat} package, which is required by Tk.

\section{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.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
