findProgram -- load external program

Synopsis

• Usage:

  findProgram(name, cmd)

  findProgram(name, cmds)

• Inputs:
  • name, a string, the name of the program to load. This should match the corresponding key in programPaths.
  • cmd, a string, a command to run that should return 0 if the program is present.
  • cmds, a list, a list of commands to run that should all return 0 if the program is present.
• Optional inputs:
  • RaiseError => a Boolean value, default value true, whether to raise an error if the program is not found.
  • Verbose => a Boolean value, default value false, whether to inform the user of each path that is checked.
  • Prefix => a list, default value {}, a list of sequences containing two strings identifying a prefix that is added to the executable binaries belonging to the program by some distributions. These sequences should be of the form (regex, prefix) where regex is a regular expression that should match all binary executables that need the prefix and prefix is the prefix itself.
  • AdditionalPaths => a list, default value {}, a list of strings containing any paths to check for the program in addition to the default ones.
  • MinimumVersion => a sequence, default value null, containing two strings the form (minVersion, versionCommand), where minVersion is the minimum required version of the program and versionCommand is a shell command to obtain the version number of an installed program.
• Outputs:
  • an instance of the type Program, the program that was loaded. If the program is not found and RaiseError is set to false then null is returned.

Description

This function checks for the existence of an external program by running cmd (or every element of cmds) prepended with various paths in the following order:

• The user-defined path specified by programPaths#name, if it exists.
• The path specified by prefixDirectory | currentLayout#"programs", where the programs shipped with Macaulay2 are installed.
• Each path specified by the AdditionalPaths option.
• Each path specified by the user's PATH environment variable.

For each path, any prefixes specified by the Prefix option are checked.

Once this is successful (i.e., cmd or each element of cmds returns a value of 0), then a Program object is returned. If it is unsuccessful, then either an error is raised or null is returned, depending on the value of RaiseError.

Note that if a program consists of a single executable binary file, then name should coincide with the name of this file.

i1 : programPaths#"gfan" = "/path/to/gfan/"

o1 = /path/to/gfan/

i2 : gfan = findProgram("gfan", "gfan --help", Verbose => true)
checking for gfan in /path/to/gfan/...
    not found
checking for gfan in /usr/libexec/Macaulay2/bin/...
    not found
checking for gfan in /home/m2user/src/M2/M2/usr-build/bin/...
    not found
checking for gfan in /home/m2user/src/M2/M2/usr-build/bin/...
    not found
checking for gfan in /home/m2user/src/M2/M2/usr-build/bin/...
    not found
checking for gfan in /usr/local/Caskroom/miniconda/base/bin/...
    not found
checking for gfan in /home/m2user/bin/...
    not found
checking for gfan in /home/m2user/local/bin/...
    not found
checking for gfan in /usr/local/sbin/...
    not found
checking for gfan in /usr/local/bin/...
    not found
checking for gfan in /usr/sbin/...
    found

o2 = gfan

o2 : Program

One program that is shipped with a variety of prefixes in different distributions and for which the Prefix option is useful is TOPCOM:

i3 : findProgram("topcom", "cube 3", Verbose => true, Prefix => {
         (".*", "topcom-"),
         ("^(cross|cube|cyclic|hypersimplex|lattice)$", "TOPCOM-"),
         ("^cube$", "topcom_")})
checking for topcom in /usr/libexec/Macaulay2/bin/...
  trying prefix "" for executables matching ".*"...
    found

o3 = topcom

o3 : Program

Note that when using the MinimumVersion option, the command used to obtain the current version number must remove everything except the version number itself and any leading or trailing whitespace. Piping with standard UNIX utilities such as sed, head, tail, cut, and tr may be useful.

i4 : findProgram("gfan", "gfan --help", Verbose => true,
       MinimumVersion => ("0.5",
         "gfan _version | head -2 | tail -1 | sed 's/gfan//'"))
checking for gfan in /path/to/gfan/...
    not found
checking for gfan in /usr/libexec/Macaulay2/bin/...
    not found
checking for gfan in /home/m2user/src/M2/M2/usr-build/bin/...
    not found
checking for gfan in /home/m2user/src/M2/M2/usr-build/bin/...
    not found
checking for gfan in /home/m2user/src/M2/M2/usr-build/bin/...
    not found
checking for gfan in /usr/local/Caskroom/miniconda/base/bin/...
    not found
checking for gfan in /home/m2user/bin/...
    not found
checking for gfan in /home/m2user/local/bin/...
    not found
checking for gfan in /usr/local/sbin/...
    not found
checking for gfan in /usr/local/bin/...
    not found
checking for gfan in /usr/sbin/...
    found version 0.6.2 >= 0.5

o4 = gfan

o4 : Program

See also

• Program -- external program object
• programPaths -- user-defined external program paths
• runProgram -- run an external program