Repository Management - Maple Help

Home : Support : Online Help : System : Libraries and Packages : Repository Management

Managing Maple Repositories

Introduction

 A Maple repository is a file in which Maple expressions are stored between Maple sessions for later retrieval. It is the recommended way for storing Maple procedures and packages. For an introduction, see repository.
 A repository can be a single file named with a .mla extension (eg. MyLib.mla), or a collection of two files named with .lib and .ind extensions (for example, MyLib.lib and MyLib.ind).
 The Maple system is distributed with a set of repositories. The first repository in the search path is usually maple.mla, called the Main Library. The Main Library contains the majority of the mathematical algorithms, encoded as procedures and packages. Updates or dot-releases of Maple may have an update library, update.mla, which overrides functionality in the Main Library. The other repositories are package libraries because each of them contains a single large package. These repositories include (but are not limited to):
 • CodeGeneration Library (CodeGeneration.mla) - a collection of functions and subpackages that enable the translation of Maple code to other languages.
 • ContextMenu Library (ContextMenu.mla) - a collection of functions and subpackages that define the contents of the menus that appear in the Context Panel for an expression in the Standard Interface.
 • Maplets Library (maplets.mla) -  provides routines to create windows, dialogs and other visual interfaces that interact with user to provide the power of Maple.
 • MmaTranslator Library (MmaTranslator.mla) -  provides translation tools from Mathematica to Maple.
 • Optimization Library (Optimization.mla) - a collection of routines for numerically solving optimization problems.
 • ScientificConstants and ScientificErrorAnalysis Library (scandsea.mla) -  give access to the values of various constant physical quantities and their associated uncertainty.
 • Units Library (units.mla) - provides routines for unit conversion.
 Important: Do not modify the Main Library and the distributed package libraries. It is recommended that you write-protect your Main Library and distributed package libraries after installing Maple. All the examples that follow expect that you cannot write to your Main Library.
 Note: The libraries listed here are not necessarily the only libraries shipped and are subject to change between releases. They are mentioned here for demonstration purposes only.
 Maple repositories were known, historically, as archives because they used to be simple archival collections of logically disjoint data. This is no longer the case (since Maple 6) and repositories have more complicated semantics than the simpler archives used in earlier Maple releases. In general, individual storage units in a repository are not usable without other parts of the repository also present in a consistent state.

Creating a Repository

 A repository is automatically created when you save expressions via the LibraryTools[Save] command.
 Alternately, you can use lower-level march commands. The following example creates a directory and an empty repository in the directory "/home/user/mylib".
 > mkdir("/home/user/mylib");
 > march('create',"/home/user/mylib/MyLib.mla");
 The above example uses UNIX paths. On Windows, you might use a path as follows.  Note the double backslash used for the directory separator. Forward-slashes as in the above example can also be used.
 > mkdir("c:\\mylib");
 > march('create',"c:\\mylib\\MyLib.mla");

How Maple Locates Repositories

 Maple finds the repositories that it uses by means of the value of the global variable libname. This must be assigned a sequence of one or more strings naming directories in which Maple repositories can be found or the full path of the .mla or .lib file of one repository. (It is also used to locate help databases.) When Maple needs to evaluate a symbol for the first time, it searches the repositories that it finds in libname, in order, until an entry in one of the repositories is found under the name. If a string in libname is a directory, all the repositories in that directory are searched in the order specified by LibraryTools[Priority] (a repository with higher priority is searched first). If the repositories have the same priority, they are searched in alphabetical order. If a string in libname is a full path of the .mla or .lib file of a repository, only that repository is searched. (If no entry is found in any accessible repositories, the symbol has no assigned value.)
 For most purposes, the Main Library is one of the components of libname. Typically, this is the first component, and third party applications, and any locally installed Maple software should be stored in other repositories that occur later in libname.  It is not generally recommended for toolboxes and third party libraries to override functionality in the main repository.
 Adjustments to the value of libname are typically made in the Maple initialization file by using an assignment to libname of the following form.
 > libname := libname, , , ...:
 The default libname will include the main repository directory as described above, plus all toolboxes installed in $MAPLE/toolbox/$VERSION/$TOOLBOX/lib, and$HOME/maple/toolbox/$VERSION/$TOOLBOX/lib, where $MAPLE is the path to your Maple installation,$HOME is your home directory, $VERSION is the major version number of the copy of Maple you are running, and$TOOLBOX is the name of any toolbox found in the given paths. For backwards compatibility with previous versions of Maple, the toolbox directory without a \$VERSION subdirectory is also searched.
 Some third party packages can be provided with a help database, which is stored in an .help file. This should be placed in the same directory as the corresponding repository .mla or .lib files.
 You can remove Maple's access to a particular repository by re-assigning libname a value that does not include the directory in which it is stored as one of its components.
 Maple uses the value of libname the first time it encounters a symbol in its input. The first time Maple evaluates any symbol, it searches the repositories that it finds in the directories named in libname, in order, for a stored definition of the symbol. The first one found, if any, is used as the assigned value of the symbol. If no definition is found, the symbol is considered not to have been given an assigned value. Thus, the correct way to test whether a symbol is stored in any accessible repository is to use the assigned command. All read access to repositories is done automatically. It is never necessary to use the deprecated readlib command.

Saving Expressions to a Repository

 When you have written Maple software, save it to a repository, so that it is read automatically whenever it is needed. All that is necessary to do is to save the code (procedures, packages, or other data) in a personal repository and ensure that the repository is included in your libname setting, as described in the preceding section.
 To prevent accidentally overwriting a personal repository you can use LibraryTools[WriteMode] with the READONLY option.  Conversely, before you can save anything to a repository, you must ensure that the WriteMode is set to WRITABLE. Never modify libraries shipped with Maple.  Create your own instead.
 Use the LibraryTools[Save] command to save variables, procedures, packages, or other Maple expressions to your repository.
 LibraryTools[Save] relies on a lower-level mechanism for saving objects depending on the special global variable savelibname, and the command savelib. savelibname is assigned a single string, that names your private Maple repository.
 > savelibname := "/home/user/mylib/MyLib.mla":
 To effect a saving operation to the repository in MyLib.mla, issue a call to the procedure savelib. It takes as arguments the names to which the expression you wish saved are assigned. Any number of expressions can be saved in a single call to savelib. Ordinarily, the names passed to savelib are quoted using unevaluation quotes (right single quotes) since it is the names themselves that are required for saving. To be saved, a name must have an assigned value or at least one attribute.
 Suppose, for example, that you have defined the following two procedures.
 > MyCutoff := 2:
 > MyFactorial := ( n::nonnegint ) -> if( n < MyCutoff, 1, n * procname( n - 1 ) ):
 > MyFibonacci := ( n::nonnegint ) -> if( n < MyCutoff, 1, procname( n - 1 ) + procname( n- 2 ) ):
 To save these to the repository in MyLib.mla, call savelib with the names MyFactorial and MyFibonacci as arguments.
 > savelibname := "C:\\mylib\\MyLib.mla":
 > savelib( 'MyCutoff', 'MyFactorial', 'MyFibonacci' ):
 The syntax for LibraryTools[Save] is identical, except that savelibname is taken as a parameter.
 > LibraryTools[Save]( 'MyCutoff', 'MyFactorial', 'MyFibonacci', "C:\\mylib\\MyLib.mla" ):
 Since the value of MyCutoff is needed in these procedures, it too must be saved along with them. In this case, because MyCutoff is assigned a value that does not have last name evaluation rules (see last_name_eval), the uneval quotes on the name are essential. (Last name evaluation rules allow you to omit them for expressions like procedures, tables, and modules, which are the most common expression types saved.) If MyCutoff were passed without the quotes, then savelib would receive its assigned value $2$ as an argument, rather than the name MyCutoff, resulting in an error.
 It is not necessary to save everything in a single call to savelib. The preceding example can be coded as:
 > savelibname := "C:\\mylib\\MyLib.mla":
 > savelib( 'MyCutoff' ):
 > savelib( 'MyFactorial' ):
 > savelib( 'MyFibonacci' ):
 or with the arguments grouped in any other convenient manner.
 Typically, large bodies of code are saved to a repository. Small collections of Maple code or statements can also be stored in Maple language source files or in worksheets. If you are using a worksheet to develop your code, it is a good idea to include a commented call to savelib so that others who use your worksheet can install the code in their own repositories after first editing, and then uncommenting, the call. When you store your Maple code in a Maple language source file, you can do something similar. For example, if you store the definitions in the example above in a Maple source file "MyStuff.mpl", you can include at the end of the file a commented line such as

#savelibname := cat( getenv( "HOME" ), "/lib/MyLib.lib" ):

#savelib( 'MyCutoff', 'MyFactorial', 'MyFibonacci' ):

 The loading of the file into your personal repository can be automated somewhat by using a tool such as the UNIX sed utility (or another, comparable tool provided by your operation system) to remove the comment, and then feed the results to a Maple batch session. Under UNIX, a command line like

sed 's/#savelib/savelib/' MyStuff.mpl | maple -s -q

 might be used as part of a script or makefile rule for loading your Maple code. (See, for example, the script mload.sh in the samples/ProgrammingGuide directory of your Maple installation.)

Listing a Repository

 The LibraryTools[ShowContents] command, or LibraryTools[Browse] command can be used to list the contents of a repository.
 The output of LibraryTools[ShowContents] is a list of lists describing the contents of the repository in the directory specified in the call. See LibraryTools[ShowContents] for details on the format of this output.
 A repository listing via the march('list') command contains entries with strange looking names that have the form :-N.m, where N is a positive integer. These are generated when closures are saved to a repository, and are used to maintain the repository in an internally consistent state.
 To see an example of this, generate a small module, and save it in the repository.
 > m := module() export e; e := 2; end module:
 > LibraryTools[Save]('m',"/home/user/mylib/MyLib.lib");
 > march( 'list', "/home/user/mylib/MyLib.lib" );
 $\left[\left[{":-1.m"}{,}\left[{2006}{,}{4}{,}{18}{,}{12}{,}{49}{,}{23}\right]{,}{1095}{,}{34}\right]{,}\left[{"m.m"}{,}\left[{2006}{,}{4}{,}{18}{,}{12}{,}{49}{,}{23}\right]{,}{1024}{,}{71}\right]\right]$ (1)
 In this case, an entry whose name is :-1.m is created, in addition to the expected entry m.m for the module itself. This entry (as well as the module entry m.m) is useless by itself, and cannot be used separately from the entire repository.
 Although the march command allows you to extract individual repository entries, they are not, in general, usable when separate from the repository in which they reside. Manipulating repository entries outside an intact repository is not supported, and does not generally yield useful results. This functionality of march is maintained primarily for backwards-compatibility.
 You can count the number of entries in a repository by counting the number of list elements returned by the list command of march using nops. For example, the following command counts the number of repository entries in the Maple Main Library when the help topic was produced.
 > nops( march( 'list', "/u/maple/repository/main/lib/maple.lib" ) );
 ${25410}$ (2)

Optimizing the Repository

 When you have created a complete repository to which you no longer wish to make additions or modifications, you can optimize the space used for the index, and garbage collect unused entries by using the pack, gc, and reindex commands for march.
 > map( march, [ 'gc', 'reindex', 'pack' ], "/home/user/mylib/MyLib.mla" );
 $\left[{0}{,}{0}{,}{0}{,}{0}{,}{320}{,}{192}{,}{0}{..}{0}\right]$ (3)

 Finally, set your repository to "READONLY" using the LibraryTools[WriteMode] command. This prevents your library from being accidentally damaged.