$autoload

Synopsis

When Express starts up, it will scan a list of predefined autoload directories for V files. The list of autoload directories is constructed by taking the elements of $XP_PATH and appending "/autoload" to each element. Essentially, every place where you have a 'v' directory, you can have a parallel autoload directory. This includes looking for an autoload directory in Express' install directory. Experienced users are encouraged to create a new empty project directory to hold autoloaded files, but new users can get started more quickly by installing an autoloaded project into the Express install directory.

Description

File ordering issues are handled via the new $autoload command. If file B depends on file A, then file B can ensure that file A is loaded first by having '$autoload A.v' as the first line of file B. The $autoload in the command raises the possibility that a common initialization file will be loaded multiple times. The autoload facility guards against this by maintaining an internal database of V files that have been autoloaded. A file will only be loaded if it is new and has not been autoloaded before, or if its modification time is later than the modification time that stored in the database. When checking for duplicate files, the pathname prefix that is taken from $XP_PATH is not taken into consideration. The net effect is that one autoloaded file can override another with the same name, thus users need to be careful about having different autoloaded files with the same name in different project directories. This is consistent with the rules for loading regular V files; for example, a custom version of ne.v in a project directory will overrride the version of ne.v in the install directory.

The automatic loading of files in the autoload directories only happens once at startup. The new VCP commands documented below give the user the ability to rescan for new files added in the middle of the Express session and the ability to do a fresh reload of all the autoloaded files.

If the project to be autoloaded contains compiled C/C++/Fortran modules, then the project also must have a shared library (Unix) or DLL (Windows) that contains the compiled code. These libraries need to be placed where the system's dynamic loader can find them. The simplest thing to do is to place the new libraries in the same directory as all the Express shared libraries. On Unix this will be <install_dir>/lib/${MACHINE} , while on Windows it would be <install_dir>\runtime\bin\pc . There is some risk of accidentally overwriting an Express library if the new libraries are added to a pre-existing Express directory. User's can place the new libraries anywhere on their system as long as the environment variables LD_LIBRARY_PATH(most Unix platforms) or PATH (Windows) are updated to point at the directory or directories that contain the new libraries.

V commands

$autoload <v_file>

Reads in the specified V file into the root object. If the V file has already been read in and the V file has not changed since it was last read in, then the reading of the V file will be skipped. The v_file argument can be a full or relative path name.

Generally, this command is not issued "by hand" in the VCP (although it can be). Rather, it is used much as the $include command is used, in order for one V file to autoload another.

$autoload_clear_checks

Clears out the internal database that the autoload facility uses to avoid duplicate file loads. The next $autoload command will always load in the specified file, even if the file has been loaded before.

$autoload_scan

Scans all of the possible autoload directories for V files and loads the files that pass the duplicate file checks. The net effect will be to load all new or newly modified V files. If the command $autoload_clear_checks is issued first, all V files found in the autoload directories will be loaded.

AVS/Express performs this scan once at startup, but AVS/Express will not automatically notice new autoload files added in the middle of session.

Functionality from the Project Developer's Perspective

As with any Express project, an autoloaded project is made up of V code and (usually) compiled C/C++/Fortran module code. In an ordinary Express project, the module developer supplies the C/C++/Fortran source code and the module user compiles the new project. In an autoloaded project, the compiled code will be in the form of a shared library (Unix) or a DLL (Windows).

Format of autoloaded V files.

For the most part, the V code used to define an autoloaded project's modules, groups, and macros, can be exactly the same as with a regular (non-autoload) project. The difference lies in how the new V definitions are tied into the master Templates library that holds Express' templates and the Libraries library that controls the appearance of the Network Editor. In a regular project additions are made, directly or indirectly, to templ.v and libs.v which are loaded into the correct context (the Templates object or the Libraries object). When a V file is autoloaded, its object context is the Root object, so the autoloaded V file needs to explicitly establish the correct context.