Invoking tools with invoke scripts
Overview
Invoke scripts are small programs, usually written in sh or bash, used to setup the application container environment so the tool can run properly. More specifically, invoke scripts are responsible for:
- Locating tool.xml for Rappture applications
- Setting up the PATH and other optional environment variables
- Starting the window manager
- Starting optional subprograms, like filexfer
- Starting the application
For most applications, the invoke script is a single command that calls the default HUBzero invoke script, named invoke_app, with a few options set. In some rare situations, the tool needs the application container setup in a manner that invoke_app cannot handle. In these cases, the tool developer can modify the tool's invoke script to appropriately setup the application container.
The sections below list out details regarding the options of invoke_app, how to launch Rappture tools using an invoke script that calls invoke_app, and how to launch non-Rappture tools using an invoke script that calls invoke_app.
invoke_app and its options
HUBZero's default tool invocation script is called invoke_app. It is a bash script, usually located in /usr/bin. When called with no options, the script tries to automatically find the needed information to start the applications. There are a number of options that can be provided to alter the script's behavior.
invoke_app accepts the following options:
-A tool arguments
-c execute command in background
-C command to execute for starting the tool
-e environment variable (${VERSION} substituted with $TOOL_VERSION)
-f No FULLSCREEN
-p add to path (${VERSION} substituted with $TOOL_VERSION)
-r rappture version
-t tool name
-T tool root directory
-u use envionment packages
-v visualization server version
-w specify alternate window manager
Here is a detailed description of the options:
| -A |
pass the provided enquoted arguments onto the tool.
Example usage: -A "-q blah1 -w blah2"The options -q and -w are not parsed by invoke, but are passed on to the tool |
| -c |
Commands to run in the background before the tool launches.
Exmple usage: -c "echo hi" -c "filexfer"This prints "hi" to stdout and starts filexfer |
| -C |
Command to execute for starting tool. Tool's command line arguments
can be included in this option, or can be placed in the -A option.
Example usage: Call a program, named myprog, located in the tool's bin directory: -C @tool/bin/myprog Call a program, named myprog, located in the tool's bin directory, with program arguments "-e val1" and "-b val2": -C "@tool/bin/myprog -e val1 -b val2" Call a program, named myprog, located in the tool's bin directory with arguments -e val1 and -b val2, used in conjunction with invoke_app's -A option: -C @tool/bin/myprog -A "-e val1 -b val2" Call a program, named myprog, located in the tool's bin directory. We can omit the path of the program if it is an executable and located in the tool's bin directory because the tool's bin directory is added to the PATH environment variable. This would not work for calling a Perl script in a fashion similar to perl myscript.pl because in this case, perl is executable and myscript.pl is the argument.: -C myprog Call simsim with no arguments: -C /apps/rappture/bin/simsim Call simsim with the options -tool and -values, to be parsed by simsim: -C "/apps/rappture/bin/simsim -tool driver.xml -values random" Call simsim with the options -tool and -values, to be parsed by simsim: -C /apps/rappture/bin/simsim -A "-tool driver.xml -values random" |
| -e |
Set an environment variable.
Example usage: -e LD_LIBRARY_PATH=@tool/../${VERSION}/lib:${LD_LIBRARY_PATH}
Within the value part of this option's argument, the text ${VERSION}
is automatically substituted with the value of the variable
${TOOL_VERSION}. Similarly, the text @tool is substituted with
the value of ${TOOLDIR}. By setting the environment variable,
you are overwritting its previous value.
|
| -f | no full screen - disable FULLSCREEN environment variable, used by Rappture, to expand the window to the full available size of the screen. |
| -p |
Prepend to the PATH environment variable.
Example usage: -p @tool/../${VERSION}/bin
Within the value part of this option's argument, the text ${VERSION} is automatically substituted with the value of the variable ${TOOL_VERSION}. Similarly, the text @tool is substituted with the value of ${TOOLDIR}. By setting this option the PATH environment variable is adjusted, but not overwritten. |
| -r |
sets RAPPTURE_VERSION which dictates which version of rappture is used
and may manipulate the version of the tool that is run. If left blank,
the version will be determined by looking at $SESSIONDIR/resources file.
Accpetable values include "test", "current", "dev". When RAPPTURE_VERSION is "test", RAPPTURE_VERSION is reset to current and TOOL_VERSION is set to dev. The current version of rappture is used and the dev version of the tool is used when launching the program. When RAPPTURE_VERSION is "current", TOOL_VERSION is set to "current". The current version of rappture is used and the current version of the tool is used when launching the program. When RAPPTURE_VERSION is "dev", TOOL_VERSION is set to "dev". The dev version of rappture is used and the dev version of the tool is used when launching the tool. |
| -t | sets ${toolname} which is used while setting up tool paths for TOOLDIR and TOOLXML. ${toolname} is the short name (or project name) of the tool. It is the same as the name used in the source code repository. With respect to the tool contribution process, it is the "toolname" in the path /apps/toolname/version/rappture/tool.xml. Setting this option will change the paths searched while trying to locate tool.xml and the bin directory. |
| -T |
Tool root directory. This is the directory holding a checked out version
of the code from the source code repository. It typically has the src,
bin, middleware, rappture, docs, data, and examples directories
underneath it. With respect to the tool contribution process, it is the
"/apps/toolname/version" in the path
/apps/toolname/version/rappture/tool.xml. Setting this option will
change the paths searched while trying to locate tool.xml and the bin
directory. Typically when testing this option is used to specify
where the tool directory is. In this case, its the present working
directory: -T $PWD |
| -u |
Set use scripts to invoke before running the tool.
Example usage: -u octave-3.2.4 -u petsc-3.1-real-gnuThese would setup octave-3.2.4 and petsc-3.1 in the environment that your tool would launch in. |
| -v |
Visualization server version. This option changes which visualization
servers are setup in the file $SESSIONDIR/resouces. Currently, the
only recognized option is dev. If left blank this option defaults to
the "current" visualization servers. This option essentially decides
whether to run the script update_vis or update_viz_dev.
Example: -v devThis option irrelevant if no visualization server is available. |
| -w |
set the window manager. The default value is to use the ratpoison window
manager if it exists. If ratpoison is not installed on the system, look
for the icewm captive window manager setup. Use this flag to choose an
alternative window manager. Valid values for this option include:
"ratpoison" and "captive"
Examples: Use the icewm captive window manager. -w captive Use the ratpoison window manager. -w ratpoison |
invoke_app is called from within a tool's invoke script. The invoke script is stored in the middleware directory of the tool's source code repository.
Using invoke_app with Rappture tools
Invoke scripts should be placed in the middleware directory of the tool's source code repository. A typical invoke script for a Rappture application looks similar to this:
#!/bin/sh
/usr/bin/invoke_app "$@" \\
-t calc
In the invoke script above, invoke_app, located in the directory /usr/bin, is called with "$@" and "-t calc". "$@" represents all options that the invoke script itself received. "-t calc" tells invoke_app that the toolname is "calc". This information is used by invoke_app to figure out which tool it is supposed to be launching and where that tool is installed.
For most Rappture applications, the invoke script is very simple. The above is enough for invoke_app to start looking for a tool.xml file. invoke_app looks for the file named tool.xml. It uses the TOOLDIR variable to help decide where to look. If the tool.xml file is not found in the ${TOOLDIR}/rappture directory, invoke_app will exit explaining that it could not find the tool.xml file. The TOOLDIR variable can be set from the command line using the -T flag:
/usr/bin/invoke_app "$@" -t calc -T ${PWD}
Actually, it is more common to see the -T flag provided to a tool's invoke script, and the option is forwarded to invoke_app by "$@":
./middleware/invoke -T ${PWD}
In the above example, the TOOLDIR variable is set to the present working directory, which is stored in the variable PWD. Specifying the -T option is usually not needed, but can help when invoke_app is confused on what it is supposed to be launching.
Using invoke_app with non-Rappture tools
Invoke scripts should be placed in the middleware directory of the tool's source code repository. A typical invoke script for a non-Rappture application looks similar to this:
#!/bin/sh
/usr/bin/invoke_app "$@" \\
-t calc \\
-C calc \\
-c filexfer \\
-w captive
In the invoke script above, invoke_app, located in the directory /usr/bin, is called with "$@", "-t calc", "-C calc", "-c filexfer", "-w captive". "$@" represents all options that the invoke script itself received. "-t calc" tells invoke_app that the toolname is "calc". This information is used by invoke_app to figure out which tool it is supposed to be launching and where that tool is installed. "-C calc" tells invoke_app that the command to run to start the tool is "calc". "-c filexfer" tells invoke_app to start up the filexfer program before starting the tool's graphical user interface. "-w captive" tells invoke_app to use the icewm captive window manager. For non-rappture applications the icewm captive window manager may be preferred over the ratpoison window manager if there are multiple graphical user interface windows that could popup.
The invoke script above could be made more svelte if the we did not want to start filexfer and we wanted to use the ratpoison window manager. After all, not all applications require files from the user, so they don't need the filexfer program. Here's an example of the tool named calc (the "-t calc" option), that is started by the executable named calc (the "-T calc" option), and uses the default window manager which is ratpoison.
#!/bin/sh
/usr/bin/invoke_app "$@" \\
-t calc \\
-C calc
Other invoke script examples
Here are a few common invoke scripts examples that demonstrate using invoke_app options.
Use the -u option to setup Octave-3.2.4 in the path before starting the tool's graphical user interface. The -u option sources a "use" script (octave-3.2.4 in this example) from the /apps/environ directory.
#!/bin/sh
/usr/bin/invoke_app "$@" \\
-t calc \\
-C calc \\
-u octave-3.2.4
Use the -A option to send additional arguments to the command to be executed:
#!/bin/sh
/usr/bin/invoke_app "$@" \\
-t calc \\
-C calc \\
-A "-value 13 -value 5 -op add"
Or:
#!/bin/sh
/usr/bin/invoke_app "$@" \\
-t calc \\
-C "calc -value 13 -value 5 -op add"
Launching a Matlab tool (named app-fermi) with a Rappture graphical user interface:
#!/bin/sh
/usr/bin/invoke_app "$@" \\
-t app-fermi
Launching a Python tool (named app-fermi) with a Rappture graphical user interface:
#!/bin/sh
/usr/bin/invoke_app "$@" \\
-t app-fermi
Launching a Java tool (named app-fermi) with a Rappture graphical user interface:
#!/bin/sh
/usr/bin/invoke_app "$@" \\
-t app-fermi