next | previous | forward | backward | up | top | index | toc | Macaulay2 website
Macaulay2Doc :: findProgram

findProgram -- load external program

Synopsis

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:

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 _version --help", Verbose => true)
 -- /path/to/gfan/gfan does not exist
 -- /usr/libexec/Macaulay2/bin/gfan does not exist
 -- /home/m2user/src/M2/M2.git/M2/usr-build/bin/gfan does not exist
 -- /home/m2user/src/M2/M2.git/M2/usr-build/bin/gfan does not exist
 -- /home/m2user/src/M2/M2.git/M2/usr-build/bin/gfan does not exist
 -- /home/m2user/bin/gfan does not exist
 -- /home/m2user/local/bin/gfan does not exist
 -- /usr/local/sbin/gfan does not exist
 -- /usr/local/bin/gfan does not exist
 -- /usr/sbin/gfan does not exist
 -- /usr/bin/gfan exists and is executable
 -- running "/usr/bin/gfan _version --help":
 -- return value: 0

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_")})
 -- /usr/libexec/Macaulay2/bin/cube exists and is executable
 -- running "/usr/libexec/Macaulay2/bin/cube 3":
 -- return value: 0

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 _version --help", Verbose => true,
       MinimumVersion => ("0.5",
         "gfan _version | head -2 | tail -1 | sed 's/gfan//'"))
 -- /path/to/gfan/gfan does not exist
 -- /usr/libexec/Macaulay2/bin/gfan does not exist
 -- /home/m2user/src/M2/M2.git/M2/usr-build/bin/gfan does not exist
 -- /home/m2user/src/M2/M2.git/M2/usr-build/bin/gfan does not exist
 -- /home/m2user/src/M2/M2.git/M2/usr-build/bin/gfan does not exist
 -- /home/m2user/bin/gfan does not exist
 -- /home/m2user/local/bin/gfan does not exist
 -- /usr/local/sbin/gfan does not exist
 -- /usr/local/bin/gfan does not exist
 -- /usr/sbin/gfan does not exist
 -- /usr/bin/gfan exists and is executable
 -- running "/usr/bin/gfan _version --help":
 -- return value: 0
 -- found version 0.6.2 >= 0.5

o4 = gfan

o4 : Program

See also

Ways to use findProgram :

For the programmer

The object findProgram is a method function with options.