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.
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 override 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\${MACHINE}. There is some risk of accidentally overwriting an Express library if the new libraries are added to a pre-existing Express directory. Users 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.
$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 will not automatically notice new autoload files added in the middle of session.
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).
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. At a minimum, all that is need is one beginning line to set the context to the Templates library.
Templates {
<New Definitions>
};
The following is a simple example that adds a module to a pre-existing AVS/Express library (workspace_1). The use of the dyn_libs property is required. When Express attempts to execute the compiled C method MYadd_num it will look for it in a shared library called my_proj.so (most Unix platforms) or my_proj.dll (Windows).
Templates {
WORKSPACE_1 {
module add_num<cxx_name="",dyn_libs="my_proj"> {
float+IPort2+read+req src_1;
float+IPort2+read+req src_2;
float+OPort2+write+nonotify res;
omethod+notify+req+notify_inst update = "MYadd_num";
};
};
};
The following is similar, but a new library is created, instead of using a pre-existing library.
Templates {
flibrary MY_PROJ {
module add_num<cxx_name="",dyn_libs="my_proj"> {
float+IPort2+read+req src_1;
float+IPort2+read+req src_2;
float+OPort2+write+nonotify res;
omethod+notify+req+notify_inst update = "MYadd_num";
};
};
};
The reason why the implementation does not just use the Templates library as a default context is so that the autoloaded file can also make additions to the Network Editor. The following can be added to the previous example to create a new page in the NE.
Libraries {
flibrary MY_PROJ {
NElink MY_PROJ<NEdisplayMode="opened"> => Templates.MY_PROJ;
};
};
For more advanced usage, where there might be many modules to autoload, it is a good idea to separate the V code that creates your new libraries from the V code that adds individual modules. The following shows a sample initialization file that creates new libraries.
Templates {
// Actual project code goes here
flibrary IAC_PROJ<cxx_name="",dyn_libs="iac"> {};
// These hold network editor links
flibrary IAC<user_library=0,compile_subs=0> {
flibrary COMMON<user_library=0,compile_subs=0> {};
flibrary DATA_IO<user_library=0,compile_subs=0> {};
flibrary EXAMPLES<user_library=0,compile_subs=0> {};
};
};
Libraries {
// Create a new Network Editor Page
flibrary IAC<NEdisplayMode="opened"> {
NElink Common<NEdisplayMode="open"> => Templates.IAC.COMMON;
NElink Data_IO<NEdisplayMode="open"> => Templates.IAC.DATA_IO;
NElink Examples<NEdisplayMode="open"> => Templates.IAC.EXAMPLES;
};
};
Combined with the previous initialization file, the following will properly autoload the WriteUCD project, which is contained in wr_ucd.v. wr_ucd.v is unchanged from its original, non-autoloaded form. Note the use of the $autoload V command to guarantee that autoload_init.v is loaded first so that libraries such as IAC and IAC_PROJ are created before they are referenced. If there are multiple autoload files that reference autoload_init.v, the autload facility will ensure that it is loaded only once.
$autoload autoload_init.v
Templates {
IAC_PROJ {
"../iac_proj/wr_ucd/wr_ucd.v" WriteUCD;
};
IAC {
DATA_IO {
IAC_PROJ.WriteUCD.WriteUCDMacs.write_ucd write_ucd;
};
EXAMPLES {
IAC_PROJ.WriteUCD.WriteUCDApps.WriteUCDTest WriteUCDTest;
};
};
};
Constructing the shared library is often fairly straightforward on most Unix platforms. The following is a sample command line for Linux.
% gcc -shared -o iac.so iac_proj/wr_ucd/wr_ucd.o <any other object files...>
At a conceptual level, the process for building shared libraries is similar for the other Unix platforms, although the exact compiler command and compiler flags will vary. Check the file include/${MACHINE}/machinc.mk for the make variables GENERATE_DLLIB_COMMAND and DLFLAGS.
The procedure for generating DLLs is more complex. See Shared Libraries.