Anatomy of makerules.tcl files

As may be deduced from the file extension, makerules.tcl files are Tcl scripts and so can make use of the usual Tcl commands. However, makerules.tcl files are run inside a Tcl interpreter that has been augmented by pimake with a number of additional commands. We discuss both types of commands here, beginning with some of the standard Tcl commands commonly found in makerules.tcl files:

list, llength, lappend, lsort, lindex, lsearch, concat

Tcl list formation and access commands.

file

Provides platform independent access to the file system, including subcommands to split and join file names by path component.

glob

Returns a list of filenames matching a wildcard pattern.

format, subst

Construct strings with variable substitutions.

Refer to the Tcl documentation for full details.

Notice that all the Tcl command names are lowercase. In contrast, commands added by pimake have mixed-case names. The most common OOMMF commands you'll find in makerules.tcl files are

MakeRule

Defines dependency rules, which is the principle goal of makerules.tcl files. This command is documented in detail below.

Platform

Platform independent methods for common operations, with these subcommands:

Name

Identifier for current platform, e.g., windows-x86_64, linux-x86_64, darwin.

Executables

Given a file stem returns the name for the corresponding executable on the current platform by prepending the platform directory and appending an execution suffix, if any. For example, Platform Executables varinfo would return windows-x86_64/varinfo.exe on Windows, and linux-x86_64/varinfo on Linux.

Objects

Similar to Platform Executables, but returns object file names; the object file suffix is .obj on Windows and .o on Linux and macOS.

Compile

Uses the compiler specified in the config/platform/<platform>.tcl to compile the specified source code file (-src option) into the named object file (-out option).

Link

Uses the linker specified in config/platform/<platform>.tcl to link together the specified object files (-obj option) into the named executable (-out option).

CSourceFile New

Creates an instance of the CSourceFile class. The -inc option to New specifies directories to add to the search path for header files. CSourceFile instances support these subcommands:

Dependencies

Dependency list for specified C++ source file consisting of the source file itself, header files included by #include statements in the source code files, and also any header files found by a recursive tracing of #include statements. The header file search excludes system header files requested using angle-brackets, e.g., #include <stdio.h>. A source code file can speed the tracing process by placing a /* End includes */ comment following the last #include statement, as in this example from oommf/app/mmdisp/mmdispsh.cc:

  /* FILE: mmdispsh.cc                 -*-Mode: c++-*-
   *
   * A shell program which includes Tcl commands needed to support a
   * vector display application.
   *
   */

  #include "oc.h"
  #include "vf.h"
  #include "mmdispcmds.h"

  /* End includes */
  ...

The /* End includes */ statement terminates the search for further #include statements in that file.

DepPath

List of directories containing files on which the specified C++ source file depends.

Recursive

Given a target, loads the makerules.tcl file in each child directory of the current directory and executes the rule found there for the target. Primarily used with the default targets all, configure, clean, mostlyclean, objclean, maintainer-clean, distclean, and upgrade. The default targets have an implicit rule to do nothing except recurse the action into the new child directories. If a makerules.tcl file found in this manner has an explicit rule defined for the given target, then that rule is invoked instead of the implicit rule, and, unless the explicit rule makes a Recursive call itself, the recursion on that directory branch will stop. As an example, the makerules.tcl file in the OOMMF root directory has the rule

  MakeRule Define {
    -targets   all
    -script    {Recursive all}
  }

All of makerules.tcl files one level below oommf/pkg and oommf/app have ``all'' targets that compile and link their corresponding libraries or executables. So

  tclsh oommf.tcl pimake all

run in the root OOMMF directory will build all of those libraries and applications. In contrast, makerules.tcl files under oommf/doc do not have explicit all targets, so the tclsh oommf.tcl pimake all call has no effect in the oommf/doc/ subtree.

On the other hand, the makerules.tcl in directories under oommf/pkg/, oommf/app/, and oommf/doc/ do have explicit rules for the various clean targets, so

  tclsh oommf.tcl pimake maintainer-clean

run from the OOMMF root directory will be active throughout all three subtrees. The maintainer-clean rules delete all files that can be regenerated from source, meaning object files, libraries, executables, and notably all the documentation files under oommf/doc/. Building the OOMMF documentation requires a working installation of L^ATEX and either L^ATEX2HTML or , so don't run the maintainer-clean target unless you are prepared to rebuild the OOMMF documentation!

The Tcl source defining the MakeRule, Platform, CSourceFile, and Recursive commands can be found in the oommf/app/pimake/ directory. Example use of these commands can be found in the following section.

OOMMF Documentation Team
September 30, 2022