Macaulay2 » Documentation
Packages » Macaulay2Doc :: findProgram
next | previous | forward | backward | up | index | toc

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:

  • 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.
  • The path to M2-binary.

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/local/libexec/Macaulay2/bin/gfan does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/gfan does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/gfan does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/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":
This program writes out version information of the Gfan installation.
 -- return value: 0

o2 = gfan

o2 : Program
i3 : findProgram "normaliz"

o3 = normaliz

o3 : Program

If cmd is not provided, then cmd is run with the common --version command line option.

i4 : findProgram("topcom", "cube 3", Verbose => true, Prefix => {
       (".*", "topcom-"),
       ("^(cross|cube|cyclic|hypersimplex|lattice)$", "TOPCOM-"),
       ("^cube$", "topcom_")})
 -- /usr/local/libexec/Macaulay2/bin/cube does not exist
 -- /usr/local/libexec/Macaulay2/bin/topcom-cube does not exist
 -- /usr/local/libexec/Macaulay2/bin/TOPCOM-cube does not exist
 -- /usr/local/libexec/Macaulay2/bin/topcom_cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/topcom-cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/TOPCOM-cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/topcom_cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/topcom-cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/TOPCOM-cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/topcom_cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/topcom-cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/TOPCOM-cube does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/topcom_cube does not exist
 -- /home/m2user/.local/bin/cube does not exist
 -- /home/m2user/.local/bin/topcom-cube does not exist
 -- /home/m2user/.local/bin/TOPCOM-cube does not exist
 -- /home/m2user/.local/bin/topcom_cube does not exist
 -- /usr/local/sbin/cube does not exist
 -- /usr/local/sbin/topcom-cube does not exist
 -- /usr/local/sbin/TOPCOM-cube does not exist
 -- /usr/local/sbin/topcom_cube does not exist
 -- /usr/local/bin/cube does not exist
 -- /usr/local/bin/topcom-cube does not exist
 -- /usr/local/bin/TOPCOM-cube does not exist
 -- /usr/local/bin/topcom_cube does not exist
 -- /usr/sbin/cube does not exist
 -- /usr/sbin/topcom-cube does not exist
 -- /usr/sbin/TOPCOM-cube does not exist
 -- /usr/sbin/topcom_cube does not exist
 -- /usr/bin/cube does not exist
 -- /usr/bin/topcom-cube exists and is executable
 -- running "/usr/bin/topcom-cube 3":
[[0,0,0,1],[1,0,0,1],[0,1,0,1],[1,1,0,1],[0,0,1,1],[1,0,1,1],[0,1,1,1],[1,1,1,1]]
[[7,6,5,4,3,2,1,0],[6,7,4,5,2,3,0,1],[4,6,5,7,0,2,1,3],[0,4,2,6,1,5,3,7]]
 -- return value: 0

o4 = topcom

o4 : Program

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

i5 : 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/local/libexec/Macaulay2/bin/gfan does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/gfan does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/bin/gfan does not exist
 -- /home/m2user/src/macaulay2/M2/M2/BUILD/doug/../../usr-build/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":
This program writes out version information of the Gfan installation.
 -- return value: 0
 -- found version 0.6.2 >= 0.5

o5 = gfan

o5 : 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.

i6 : 

See also

Ways to use findProgram:

For the programmer

The object findProgram is a method function with options.