Platform-Independent Make: pimake

The application pimake is used to construct OOMMF end-user executables (and optionally documentation) from the distributed source code. It is similar in operation to the Unix utility program make, but it is written entirely in Tcl so that it will run anywhere Tcl is installed. Like make, pimake controls the building of a target from other files. Just as make is controlled by rules in files named Makefile or makefile, pimake is controlled by rules in files named makerules.tcl. pimake generally operates recursively, starting in the current working directory and continuing downward through all subdirectories. (The chief exception to this is the documentation under oommf/doc; pimake build requests started in the root directory oommf ignore the oommf/doc subdirectory. Building the OOMMF documentation requires a working installation of L^ATEX and either L^ATEX2HTML or L^ATEXML, so OOMMF distributions include pre-built versions of the full OOMMF documentation to relieve the end-user the burden of installing those tools. On the other hand, clean requests, including in particular maintainer-clean, will recurse into oommf/doc.) The OOMMF standard command line option -cwd may be used to change the starting directory.

Launching
The pimake launch command is:

tclsh oommf.tcl pimake [standard options] [-d] [-i] [-k] \
   [-buildgraph] [-color request] [-depgraph] [-dry-run] \
   [-parallel N] [-root] [-v level] [-out file] [-root] [target]

where

-d

Print verbose information about dependencies.

-i

Normally an error halts operation. When -i is specified, ignore errors and try to continue updating all dependencies of target.

-k

Normally an error halts operation. When -k is specified, and an error is encountered, stop processing dependencies which depend on the error, but continue updating other dependencies of target.

-buildgraph

Prints the build graph for the requested target, i.e., all the files that would be rebuilt to make the target up-to-date; does not build the target.

-color request

Request compiler/linker diagnostics in color, where request is one of always, auto, or never. Requires compiler/linker support.

-depgraph

Prints the dependency graph for the requested target; does not build the target.

-dry-run

Prints the build steps without executing them.

-parallel N

Run the build in parallel, with up to N execution streams.

-root

Change to the OOMMF root directory. Command line options are processed from left to right, so if used in conjunction with the standard option -cwd, -root should come first.

-v level

Sets the level of informational messages reported during processing. Default level is 1, with larger values producing more output.

-out file

Write informational output to named file instead of to the standard output.

target

The file to build. May also be (and usually is) a symbolic target name. See below for standard symbolic targets. By default, the first target in makerules.tcl is built.

There are several targets which may be used as arguments to pimake to achieve different tasks. Each target builds in the current directory and all subdirectories. The standard targets are:

upgrade

Used immediately after unpacking a distribution, it removes any files which were part of a previous release, but are not part of the unpacked distribution. WARNING: This target is currently not maintained. DO NO USE.

all

Creates all files created by the configure target (see below). Compiles and links all the executables and libraries. Constructs all index files.

configure

Creates subdirectories with the same name as the platform type. Constructs a ocport.h file which includes C++ header information specific to the platform.

objclean

Removes the intermediate object files created by the compile and link steps. Leaves working executables in place. Leaves OOMMF in the state of its distribution with pre-compiled executables.

clean

Removes the files removed by the objclean target. Also removes the executables and libraries created by the all target. Leaves the files generated by the configure target.

distclean

Removes the files removed by the clean target. Also removes all files and directories generated by configure target. Leaves only the files which are part of the source code distribution.

maintainer-clean

Remove all files which can possibly be generated from other files. If run from the OOMMF root directory then all such files, including OOMMF documentation files, will be deleted. Rebuilding may require specialized developer tools, so use with care. This target is intended primarily for developers, not end-users.

help

Print a summary of the standard targets.

If -parallel N is requested with N>1 then the various pieces of OOMMF are built in parallel, with up to N build streams. If an error occurs in one stream, then no new jobs are started but currently active jobs are allowed to run to completion. Output from the continuing jobs may push error messages off the screen or otherwise make it difficult to discern the cause of error. An immediate relaunch of pimake in serial mode (i.e., no -parallel option) will usually replicate the error without chatter from other build jobs.

The parallel build process takes into account the dependency information recorded in the various makerules.tcl files. However, dependency failures may occur if external applications such as compilers or linkers introduce additional dependencies, for example shared debug symbol tables. If this happens, reset the build with pimake distclean and rerun pimake in sequential mode.

OOMMF Documentation Team
September 27, 2024