Oxs Package Management: oxspkg

The oxspkg command is used to manage optional Oxs extension packages. Each package is stored in a separate directory under oommf/app/oxs/contrib/. These packages can be “installed” and “uninstalled” to and from the oommf/app/oxs/local/ directory by the oxspkg command. The install is a simple copy that does not automatically build the package or link it into the Oxs executable—a separate invocation of pimake is needed for that.

Launching
The oxspkg launch command is:

tclsh oommf.tcl oxspkg list

or

tclsh oommf.tcl oxspkg listfiles pkg [pkg ...]

or

tclsh oommf.tcl oxspkg readme pkg [pkg ...]

or

tclsh oommf.tcl oxspkg requires pkg [pkg ...]

or

tclsh oommf.tcl oxspkg install [-v] [-nopatch] pkg [pkg ...]

or

tclsh oommf.tcl oxspkg uninstall [-f] pkg [pkg ...]

or

tclsh oommf.tcl oxspkg copyout pkg [pkg ...] destination

Glob-style wildcards (*, ?) or the keyword all are accepted in package specifications. (If your command shell expands wildcards, as is common on Unix systems, then you may need to escape or quote the wildcards so that they are passed unadulterated to the oxspkg program.) The first argument following the oxspkg keyword is one of the sub-commands list, listfiles, readme, requires, install, uninstall, or copyout:

list

Lists all the packges available under oommf/app/oxs/contrib/, how many (installable) files are in each package, and the package install status.

listfiles pkg [pkg ...]

Lists each of the “installable” files for the selected package. (There may be additional files for the package, e.g. README or files with versioning information, included in the oommf/app/oxs/contrib/<pkg>/ directory. However, those files are ignored by the oxspkg install command.)

readme pkg [pkg ...]

Prints to stdout the contents of the README file (if any) for each package.

requires pkg [pkg ...]

Lists external libraries required for each package, as declared by any *.rules files contained in the package. The user should ensure these libraries are installed on the system and included on the compiler and linker search paths before installing the Oxs extension package. In particular, check the

$config SetValue program_compiler_extra_include_dirs ...
$config SetValue program_linker_extra_lib_dirs ...

settings in the platform configuration file. There may be additional installation information in the package README file.

install [-v] [-nopatch] pkg [pkg ...]

Installs (copies) files for the selected package(s) from oommf/app/oxs/contrib/ to oommf/app/oxs/local/. This command does not compile the files or link them into the Oxs executable. The user is responsible for making a separate call to pimake to build and link the package. If the user is running OOMMF distributed with pre-built binaries, then the user should first cd to the OOMMF root directory and run tclsh oommf.tcl pimake distclean to delete the distributed binaries before running tclsh oommf.tcl pimake to create a new build of OOMMF. This ensures new extension binaries are compatible with the rest of the OOMMF install.

For third-party packages included in OOMMF distributions, the contents of the directory oommf/app/oxs/contrib/<pkg>/ will mirror some release of the package from the official source of the package. If those files don't build properly with the OOMMF distribution, then a patch file will be included in the parent oommf/app/oxs/contrib/ directory. Normally that patch file (if any) is automatically applied as part of the installation procedure. The -nopatch option skips the patch step. If there are no patches for a particular package, then the message No patches found will be reported during the install process.

The -v option requests more verbose output.

uninstall [-f] pkg [pkg ...]

Deletes all files in oommf/app/oxs/local/ associated with the selected package. Here “associated” means a file name match with a file in the package directory oommf/app/oxs/contrib/<pkg>/. There is no checking of contents or timestamps between the files. The install directory oommf/app/oxs/local/<pkg>/ will also be removed if it is empty after deleting the package files or if the -f (force) option is specified.

copyout pkg [pkg ...] destination

Selects files in the same manner as the uninstall command, but rather than deleting the files instead copies the files of each package from oommf/app/oxs/local/<pkg>/ to destination/<pkg>/. The directory destination will be created if it does not exist. This command is a development aid for creating patches for packages: Edit the package files in oommf/app/oxs/local/<pkg>/ as necessary and use oxspkg copyout to copy the package files to destination. Then, from the oommf/app/oxs/contrib/ directory, run

diff -ru  <pkg>/  destination/<pkg>/  >  <pkg>-<date>.patch

for each package to create an updated patch. Here diff is the unix-compatible file comparison utility. If the destination directory is in oommf/app/oxs/contrib/, then name it either tmp, new, or newcontrib to prevent oxspkg from treating it as a new package directory.

Most of the optional packages controlled by oxspkg are from third-party contributors. Some may originate with the OOMMF core development team, but are made optional because they require third-party libraries or are considered too experimental to be included among the standard Oxs extension classes. The various oommf/app/oxs/contrib/<pkg>/ directories may contain README files with additional details.

OOMMF Documentation Team
September 27, 2024