1This directory contains some examples of dynamically loaded modules 2that may be loaded via the `import' intrinsic function: 3 4 import ("NAME"); 5 6This intrinsic function is available to applications that enable it 7via a call to the `SLang_init_import' function. Of course, the OS 8must provide support for dynamic linking. 9 10When a slang script contains a line such as 11 12 import ("NAME"); 13 14or 15 16 import ("NAME", "NAMESPACE"); 17 18the interpreter will request that the operating system dynamically 19link to a shared object called NAME-module.so. In order for such 20linking to take place, the OS must be able to find the module. The 21search for the module takes place as follows: 22 23 First a search takes place along the set of paths returned by the 24 `get_import_module_path' function. If not found, a search is 25 performed along the paths given by the `SLANG_MODULE_PATH' 26 environment variable. Then the search will take place in the path 27 defined by the slang/src/Makefile MODULE_INSTALL_DIR variable. If 28 the module has not been found along any of these paths, a system 29 dependent search will be performed (e.g., using the `LD_LIBRARY_PATH' 30 environment variable). 31 32Hence, if you are writing a module that will work with all slang 33applications, then module should be installed in the path specified by 34the Makefile variable MODULE_INSTALL_DIR, which by default is 35 36 $(exec_prefix)/lib/slang/v2/modules 37 38for this version of the library. 39 40If the module was sucessfully loaded, the slang library will call the 41function `init_NAME_ns' that NAME-module.so must define. This 42function must have the prototype: 43 44 int init_NAME_module_ns (char *namespace); 45 46and shall return 0 upon success, or -1 if an error occurred. The 47namespace argument corresponds to the second (optional) parameter of 48the import intrinsic indicating that the module should be imported 49into the specified namespace. To this end, the module must call one 50of the SLns_* functions to load intrinsics into the namespace. 51 52****NOTE**** 53 54 In order to support the inclusion of the module into more than one 55 namespace, this function may be called multiple times. Hence, the 56 function should be coded in such a way that initialization code 57 that should execute no more than once does so only once. See, e.g., 58 the "register_pcre_type" function in pcre-module.c for an explicit 59 example. 60 61 Module writers are encouraged to supply a script called NAME.sl that 62 looks like: 63 64 import ("NAME"); 65 % Optional code... 66 provide ("NAME"); 67 68 Then a user would be able to load the module by using, e.g., 69 70 require ("NAME"); 71 72************* 73 74Optionally, the module may define a function called `deinit_NAME_module' that 75will be called by the interpreter to deinitialize the module. This 76function must have the prototype: 77 78 void deinit_NAME_module (void); 79 80To ensure the correct prototypes for these functions, the module 81should include the line: 82 83 SLANG_MODULE(name); 84 85SLANG_MODULE is a macro that expands into function prototypes. 86 87See the examples in this directory for more information. 88 89To run these modules, use the slsh program in ../slsh/. 90slsh.c is a program that embeds the interpreter and may be used to 91test slang scripts. In fact, it may be used to create unix executable 92scripts via, e.g., 93 94#! /usr/bin/env slsh 95 96as the first line of the script. See ../slsh/scripts subdirectory for 97examples of this approach. 98 99