• View
• Edit
• History
• Print

AlphaTcl Indices

Starting with version 8.2a3, AlphaTcl introduces a new mechanism to manage the caches it maintains to control its various components (packages and libraries of Tcl code). The new proposed mechanism is open to discussion.

For efficiency reasons, AlphaTcl caches information in two kinds of files:

• package specific information is stored in special caches which gather information obtained from the declarations of the various menus, modes, libraries or features and is kept in separate files corresponding to individual properties. These files will be referred to, in this document, as Package Caches.
• information about all the procs defined in the entire AlphaTcl library and in third party packages is kept in index files. There is one index file in every folder of the search paths list specified by the $auto_path variable. These index files are used by AlphaTcl when it needs to execute a command which has not yet been loaded: they let the interpreter locate the file in which this proc is defined and source it. These files will be referred to, in this document, as Tcl Index files.

When a package is removed or added, or when its declaration block is modified, the Package Caches must be rebuilt so that the information remains up-to-date. When a new proc is introduced in AlphaTcl or when an existing proc is moved to another file or deleted, the Tcl Index files must be rebuilt. Rebuilding the caches is a time consuming process which has always annoyed the Alpha users: especially when it is forced by the application during startup, as was previously the case each time a new version was released. The new mechanism manages the cache files in a much more efficient and flexible manner. In particular, the AlphaTcl library distributed inside the application now comes with a pre-built package cache and pre-built index files. Rebuilding the indices would be necessary only if the user installed third party packages. It is now possible to specify precisely in which part of the installation caches or indices must be rebuilt.

The four domains

There are now four locations where AlphaTcl packages can be found:

1. inside the application bundle. This is where the basic AlphaTcl library is stored. Users should never have to modify this library.
2. in the Local Application Support folder found in : /Library/Application Support/AlphaX/AlphaTcl. One can install in this folder third party packages which are available to all the users of the machine. Installing packages in this area requires admin privileges.
3. in the User Application Support folder found in : ~/Library/Application Support/AlphaX/AlphaTcl. Each user can install there third party packages which are only available when she is currently logged.
4. in the User Packages folder found in the Alpha Preferences folder. There are several possibilities concerning the location of the Alpha Preferences folder. The current location is always stored in the PREFS variable. Any user can install private packages there. These packages are available only to this user and for this version of Alpha.

These four locations are referred to as the internal, local, user and prefs domains respectively. It is a new feature of the proposed model that the User Packages folder can be structured with SystemCode, Modes, Menus, Packages subfolders like the other three folders. In the previous model, all the packages had to be stored there at the top level.

Rebuilding the indices

In the new model, package info caches and Tcl index files can be rebuilt in each domain separately: it is not anymore necessary to rebuild all the indices when only one file has been modified, say, in the user domain. Furthermore, the caches of the internal domain are now pre-built. This is a great improvement because, if the application is installed in the Applications folder, rebuilding the indices raises many problems due to write permissions. Normally a simple user should never have to rebuild the indices there: only developers would be interested in modifying the source files inside the bundle and rebuild the corresponding indices. One command is now exposed to the users in the Packages submenu of the Config menu:

• Rebuild External Packages Info

It lets a user rebuild both the package caches and the tcl indices corresponding to the external locations (user, local and prefs domains). One must have sufficient permissions to write in the local domain: if it is not the case, the indices will be rebuilt only in the User Application Support folder and in the Preferences folder. If you need to rebuild the internal cache or the index files inside the application bundle, see the following sections.

Rebuilding the Tcl Index files

The Tcl Indices submenu of the Tcl mode menu has been enhanced. It contains new items which let you rebuild the Tcl Index files selectively for one or several of the four domains. The Tcl menu must be activated (i-e present in the menu bar) in order to use these commands. There are also commands, in this submenu, to build a Tcl Index file for a particular folder or for the folder corresponding to the frontmost document window.

Rebuilding the Package Info caches

The AlphaDev menu has an item called Rebuild AlphaTcl Indices. This command has been enhanced: it now displays a dialog in which one can specify which kind of indices must be rebuilt (package info, or Tcl indices, or both) and for which domain(s). For this command to be available, one must activate the AlphaDeveloper Menu.

Developers information

There is a Cache folder in each domain. Precisely, Alpha now uses the following for paths:

 
     $HOME/Cache
     $SUPPORT(local)/AlphaTcl/Cache
     $SUPPORT(USER)/AlphaTcl/Cache
     $PREFS/Cache

The Package Info caches are Tcl files found in the index subfolder of each Cache folder: they contain arrays which are sourced by AlphaTcl when necessary. The current structure is:

 
     --- Cache
        |--- index
            |--- description
            |--- disable
            |--- feature
            |--- flags
            |--- help
            |--- maintainer
            |--- mode
            |--- prefshelp
            |--- preinit
            |--- requirements
            |--- uninstall

In the previous model, only the $PREFS/Cache repository existed and contained all the information. The code of the cache management procs has been modified in cache.tcl in order to take the different possibilities into account. At startup, AlphaTcl looks in the external domains to see if indices should be rebuilt there: it never rebuilds internal indices because they are supposed to be pre-built inside the application bundle. AlphaTcl relies on a count file found in $PREFS/Cache/Index: the name of this file is made of a series of numbers representing the count of the files and folders found at the first level of the usual ''SystemCode, Modes, Menus, Packages'' subfolders of the Tcl folders. A typical count file could be:

 
     count_3424314157683_00011040_005052101_00000000_0

The first four numbers are counts of files and folders in the ''internal, local, user and prefs'' domains respectively. When a folder or a file is added to (or removed from) one of these domains, AlphaTcl knows that the indices must be rebuilt (again the internal domain is ignored at startup unless the Cache folder itself is missing which would be considered a Very Bad Thing). The last digit of the count file is called the hardcoded counter. There is a variable named $hardcodedCounter defined in the file

 
     $HOME/Tcl/SystemCode/Init/alphaVersionInfo.tcl

AlphaTcl compares this variable with the value found in the count file (which is in fact the previous value of the $hardcodedCounter variable, last time the indices were rebuilt). If the new value is greater than the old one, AlphaTcl starts rebuilding all the external indices (as usual, the local indices require write permission: this domain is silently ignored if permissions are insufficient). The hardcoded counter is a mean of forcing a rebuild of the external indices. It should normally be reset to 0 when a new version of Alpha is released.

Precedence

The order in which the domains are visited when the interpreter looks for an unknown procedure is:

1. User Packages
2. User Domain
3. Local Domain
4. Application Bundle

Concerning the packages info, it is read at the appropriate moment by AlphaTcl for all four domains in the exact same order as above. This follows the order established by the $auto_path variable. Here is a simplified list of the folders contained in this variable (the lower level folders have been removed to make it easier to read):

 
 	$HOME/Tcl/SystemCode
 	$HOME/Tcl/Modes
 	$HOME/Tcl/Menus
 	$HOME/Tcl/Completions
 	$HOME/Tcl/Packages
 	$PREFS/User Packages
 	$SUPPORT(user)/AlphaTcl/Tcl/SystemCode
 	$SUPPORT(user)/AlphaTcl/Tcl/Modes
 	$SUPPORT(user)/AlphaTcl/Tcl/Menus
 	$SUPPORT(user)/AlphaTcl/Tcl/Completions
 	$SUPPORT(user)/AlphaTcl/Tcl/Packages
 	$SUPPORT(local)/AlphaTcl/Tcl/SystemCode
 	$SUPPORT(local)/AlphaTcl/Tcl/Modes
 	$SUPPORT(local)/AlphaTcl/Tcl/Menus
 	$SUPPORT(local)/AlphaTcl/Tcl/Completions
 	$SUPPORT(local)/AlphaTcl/Tcl/Packages
 	$APPLICATION/Contents/Resources/Scripts/Tclextensions
 	$APPLICATION/Contents/MacOS/../Frameworks/Tcl.framework/Versions/8.5/ 
 	Resources/Scripts
 	$APPLICATION/Contents/MacOS/../Frameworks/Tcl.framework/Versions/8.5/ 
 	Resources
 	$APPLICATION/Contents/lib
 	$APPLICATION/Contents/Frameworks
 	~/Library/Tcl
 	/Library/Tcl
 	/Network/Library/Tcl
 	/System/Library/Tcl
 	~/Library/Frameworks
 	/Library/Frameworks
 	/Network/Library/Frameworks
 	/System/Library/Frameworks
 	/System/Library/Tcl/tcllib1.6
 	/System/Library/Tcl/tklib0.2
 	$APPLICATION/Contents/Resources/Scripts/Tclextensions/tcllib1.7