TIP #579 implementation: Improved auto_path for Safe Base interpreters

1 files changed, 167 insertions, 2 deletions

diff --git a/doc/safe.n b/doc/safe.n
index 819287d..6dd4033 100644
--- a/doc/safe.n
+++ b/doc/safe.n
@@ -23,10 +23,13 @@ safe \- Creating and manipulating safe interpreters
 .sp
 \fB::safe::interpFindInAccessPath\fR \fIchild\fR \fIdirectory\fR
 .sp
+\fB::safe::setSyncMode\fR ?\fInewValue\fR?
+.sp
 \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
 .SS OPTIONS
 .PP
 ?\fB\-accessPath\fR \fIpathList\fR?
+?\fB\-autoPath\fR \fIpathList\fR?
 ?\fB\-statics\fR \fIboolean\fR? ?\fB\-noStatics\fR?
 ?\fB\-nested\fR \fIboolean\fR? ?\fB\-nestedLoadOk\fR?
 ?\fB\-deleteHook\fR \fIscript\fR?
@@ -148,6 +151,15 @@ $child eval [list set tk_library \e
 .CE
 .RE
 .TP
+\fB::safe::setSyncMode\fR ?\fInewValue\fR?
+This command is used to get or set the "Sync Mode" of the Safe Base.
+When an argument is supplied, the command returns an error if the argument
+is not a boolean value, or if any Safe Base interpreters exist.  Typically
+the value will be set as part of initialization - boolean true for
+"Sync Mode" on (the default), false for "Sync Mode" off.  With "Sync Mode"
+on, the Safe Base keeps each child interpreter's ::auto_path synchronized
+with its access path.  See the section \fBSYNC MODE\fR below for details.
+.TP
 \fB::safe::setLogCmd\fR ?\fIcmd arg...\fR?
 This command installs a script that will be called when interesting
 life cycle events occur for a safe interpreter.
@@ -199,6 +211,13 @@ parent for auto-loading.
 See the section \fBSECURITY\fR below for more detail about virtual paths,
 tokens and access control.
 .TP
+\fB\-autoPath\fR \fIdirectoryList\fR
+This option sets the list of directories in the safe interpreter's
+::auto_path.  The option is undefined if the Safe Base has "Sync Mode" on
+- in that case the safe interpreter's ::auto_path is managed by the Safe
+Base and is a tokenized form of its access path.
+See the section \fBSYNC MODE\fR below for details.
+.TP
 \fB\-statics\fR \fIboolean\fR
 This option specifies if the safe interpreter will be allowed
 to load statically linked packages (like \fBload {} Tk\fR).
@@ -331,7 +350,8 @@ list will be assigned a token that will be set in
 the child \fBauto_path\fR and the first element of that list will be set as
 the \fBtcl_library\fR for that child.
 .PP
-If the access path argument is not given or is the empty list,
+If the access path argument is not given to \fB::safe::interpCreate\fR or
+\fB::safe::interpInit\fR or is the empty list,
 the default behavior is to let the child access the same packages
 as the parent has access to (Or to be more precise:
 only packages written in Tcl (which by definition cannot be dangerous
@@ -357,8 +377,153 @@ When the \fIaccessPath\fR is changed after the first creation or
 initialization (i.e. through \fBinterpConfigure -accessPath \fR\fIlist\fR),
 an \fBauto_reset\fR is automatically evaluated in the safe interpreter
 to synchronize its \fBauto_index\fR with the new token list.
+.SH TYPICAL USE
+In many cases, the properties of a Safe Base interpreter can be specified
+when the interpreter is created, and then left unchanged for the lifetime
+of the interpreter.
+.PP
+If you wish to use Safe Base interpreters with "Sync Mode" off, evaluate
+the command
+.RS
+.PP
+.CS
+ safe::setSyncMode 0
+.CE
+.RE
+.PP
+Use \fB::safe::interpCreate\fR or \fB::safe::interpInit\fR to create an
+interpreter with the properties that you require.  The simplest way is not
+to specify \fB\-accessPath\fR or \fB\-autoPath\fR, which means the safe
+interpreter will use the same paths as the parent interpreter.  However,
+if \fB\-accessPath\fR is specified, then \fB\-autoPath\fR must also be
+specified, or else it will be set to {}.
+.PP
+The value of \fB\-autoPath\fR will be that required to access tclIndex
+and pkgIndex.tcl files according to the same rules as an unsafe
+interpreter (see pkg_mkIndex(n) and library(n)).
+.PP
+With "Sync Mode" on, the option \fB\-autoPath\fR is undefined, and
+the Safe Base sets the child's ::auto_path to a tokenized form of the
+access path. In addition to the directories present if "Safe Mode" is off,
+the ::auto_path includes the numerous subdirectories and module paths
+that belong to the access path.
+.SH SYNC MODE
+Before Tcl version 8.7, the Safe Base kept each safe interpreter's
+::auto_path synchronized with a tokenized form of its access path.
+Limitations of Tcl 8.4 and earlier made this feature necessary.  This
+definition of ::auto_path did not conform its specification in library(n)
+and pkg_mkIndex(n), but nevertheless worked perfectly well for the discovery
+and loading of packages.  The introduction of Tcl modules in Tcl 8.5 added a
+large number of directories to the access path, and it is inconvenient to
+have these additional directories unnecessarily appended to the ::auto_path.
+.PP
+In order to preserve compatibility with existing code, this synchronization
+of the ::auto_path and access path ("Sync Mode" on) is still the default.
+However, the Safe Base offers the option of limiting the safe interpreter's
+::auto_path to the much shorter list of directories that is necessary for
+it to perform its function ("Sync Mode" off).  Use the command
+\fB::safe::setSyncMode\fR to choose the mode before creating any Safe
+Base interpreters.
+.PP
+In either mode, the most convenient way to initialize a safe interpreter is
+to call \fB::safe::interpCreate\fR or \fB::safe::interpInit\fR without the
+\fB\-accessPath\fR or \fB\-autoPath\fR options (or with the \fB\-accessPath\fR
+option set to the
+empty list), which will give the safe interpreter the same access as the
+parent interpreter to packages, modules, and autoloader files.  With
+"Sync Mode" off, the Safe Base will set the value of \fB\-autoPath\fR to the
+parent's ::auto_path, and will set the child's ::auto_path to a tokenized form
+of the parent's ::auto_path.
+.PP
+With "Sync Mode" off, if a value is specified for \fB\-autoPath\fR, even the empty
+list, in a call to \fB::safe::interpCreate\fR, \fB::safe::interpInit\fR, or
+\fB::safe::interpConfigure\fR, it will be tokenized and used as the safe
+interpreter's ::auto_path.  Any directories that do not also belong to the
+access path cannot be tokenized and will be silently ignored.  However, the
+value of \fB\-autoPath\fR will remain as specified, and will be used to
+re-tokenize the child's ::auto_path if \fB::safe::interpConfigure\fR is called
+to change the value of \fB\-accessPath\fR.
+.PP
+With "Sync Mode" off, if the access path is reset to the values in the
+parent interpreter by calling \fB::safe::interpConfigure\fR with arguments
+\fB\-accessPath\fR {}, then the ::auto_path will also be reset unless the argument
+\fB\-autoPath\fR is supplied to specify a different value.
+.PP
+With "Sync Mode" off, if a non-empty value of \fB\-accessPath\fR is supplied, the
+safe interpreter's ::auto_path will be set to {} (by
+\fB::safe::interpCreate\fR, \fB::safe::interpInit\fR) or left unchanged
+(by \fB::safe::interpConfigure\fR).  If the same command specifies a new
+value for \fB\-autoPath\fR, it will be applied after the \fB\-accessPath\fR argument has
+been processed.
+
+Examples of use with "Sync Mode" off: any of these commands will set the
+::auto_path to a tokenized form of its value in the parent interpreter:
+.RS
+.PP
+.CS
+ safe::interpCreate foo
+ safe::interpCreate foo -accessPath {}
+ safe::interpInit bar
+ safe::interpInit bar -accessPath {}
+ safe::interpConfigure foo -accessPath {}
+.CE
+.RE
+.TP
+Example of use with "Sync Mode" off: when initializing a safe interpreter
+with a non-empty access path, the ::auto_path will be set to {} unless its
+own value is also specified:
+.RS
+.PP
+.CS
+ safe::interpCreate foo -accessPath {
+     /usr/local/TclHome/lib/tcl8.6
+     /usr/local/TclHome/lib/tcl8.6/http1.0
+     /usr/local/TclHome/lib/tcl8.6/opt0.4
+     /usr/local/TclHome/lib/tcl8.6/msgs
+     /usr/local/TclHome/lib/tcl8.6/encoding
+     /usr/local/TclHome/lib
+ }
+
+ # The child's ::auto_path must be given a suitable value:
+
+ safe::interpConfigure foo -autoPath {
+     /usr/local/TclHome/lib/tcl8.6
+     /usr/local/TclHome/lib
+ }
+
+ # The two commands can be combined:
+
+ safe::interpCreate foo -accessPath {
+     /usr/local/TclHome/lib/tcl8.6
+     /usr/local/TclHome/lib/tcl8.6/http1.0
+     /usr/local/TclHome/lib/tcl8.6/opt0.4
+     /usr/local/TclHome/lib/tcl8.6/msgs
+     /usr/local/TclHome/lib/tcl8.6/encoding
+     /usr/local/TclHome/lib
+ } -autoPath {
+     /usr/local/TclHome/lib/tcl8.6
+     /usr/local/TclHome/lib
+ }
+.CE
+.RE
+.TP
+Example of use with "Sync Mode" off: the command
+\fBsafe::interpAddToAccessPath\fR does not change the safe interpreter's
+::auto_path, and so any necessary change must be made by the script:
+.RS
+.PP
+.CS
+ safe::interpAddToAccessPath foo /usr/local/TclHome/lib/extras/Img1.4.11
+
+ lassign [safe::interpConfigure foo -autoPath] DUM childAutoPath
+ lappend childAutoPath /usr/local/TclHome/lib/extras/Img1.4.11
+ safe::interpConfigure foo -autoPath $childAutoPath
+.CE
+.RE
+.TP
 .SH "SEE ALSO"
-interp(n), library(n), load(n), package(n), source(n), unknown(n)
+interp(n), library(n), load(n), package(n), pkg_mkIndex(n), source(n),
+tm(n), unknown(n)
 .SH KEYWORDS
 alias, auto\-loading, auto_mkindex, load, parent interpreter, safe
 interpreter, child interpreter, source