...
- Allows tech leads to create Master Profiles (default system configurations) and users to create personalized profiles that reflect often used launch scenarios
- Shows visual overview of run-time module status, using VHMSG ping protocol; green lines means module is up and running; orange means module is unresponsive; grey means the module is offline.
- Launch work-in-progress SVN version of a component with a build version of other components or the full system, aiding developers in testing their work against a known working build before committing changes
- Launch / Kill components locally or remotely
- Run / Kill full system or individual components
- Send VHMSG messages
Quick facts:
- Shared location: https://svn.ict.usc.edu/svn_vh/trunkProject locations: /bin/launcher & /bin/launch-scripts (binary, used by default), /tools/launcher Project locations: & /tools/launcher, /tools/launcher-scripts, /run-launcher.bat
...
Users
...
Users
...
Projects should have a run-launcher.bat file in the root of the project; this starts the Launcher with the correct Master Profile (the profile with all the default options).
...
Understanding Menu Items
Profile Menu
...
"Save Profile"
This option saves the current values of the arguments in all launch tools to the selected profile. This option is not available for the "[Default]" profile or any of the preloaded system profiles.
"Save As New Profile..."
Similar to the "Save Profile", this option saves the current values of the arguments in all launch tools, but instead of saving to an already created profile, it saves to a new one and prompts for a new name.
All of the loaded profiles appear below the separator. Click on the desired profile.
Master Profile Menu
...
"Edit Launch Tools"
This menu contains many sub-menus for editing and/or launching tools. See the Creating/Editing Launch Tools section. This option is only available when the "[Default]" profile is selected.
"Change Ordering of Tabs & Groups..."
...
This is for selecting the Master Profile. "Save Master Profile..." saves any changes to the Master Profile. This option is only available when the "[Default]" profile is selected.
"Advanced" Menu
...
"Show Information..."
Brings up a window that displays miscellaneous information such as how many programs are running, which profiles are loaded, etc.
...
Creating/Editing Launch Tools
Name: The name of the program to display on the Launcher.
Elvin Name: The name that the program uses for elvin messages.
Tab: The name of the tab that contains the launch tool will be in, you can . To create a new tab, type in a new tab name and it will be created.
Group: The group that the launch tool will be in, you can is in. To create a new group, type in a new group name and it will be created.
Selected Machine: The machine that will be the default selected machine to launch it on.
Type: there are 6 types.
- normal = A : The normal launch tool, most programs will use this one.
- agent = : Use this one if you are when launching an agent.
- runall = This one indicates that you are : Use this when creating a launch tool that will run runs the checked launch tools (see Launching Multiple Programs at Once).
- first_wait = When : Use this when launching with a runall type , it will launch this program first and will wait however many seconds that you specify before continuing to launch the rest of the checked programs. to delay time before the next checked program launches. This is useful for programs like such as the UT Server that take takes time to start up. There could be multiple Multiple first_wait programs . They will all be launched one after another and then wait the maximum time specified in all.
- wait = When launching with a runall type, it wait however many seconds that you specify after launching this program.
- logger = This is a special logging can be used with each subsequent program launching after the time specified.
- logger = This is a special logging tool that is started automatically when the tool is launched.
- wait_component = This makes the component wait on the specified component (who whose value (elvin-name) is specified in the Wait Component). You can also specify It's also possible to specify the time in 'seconds after the wait component is launched'.
Checked: If selected, the check-box will be defaulted to be selected.
...
File: The file that should be launched to run the program. It will likely typically be an exe or a bat file. If you use Use the "Browse..." button and it will automatically format it correctly for youput it in the correct format.
Parameters: These are the parameters that will be shown on the launcher. You can also specify some pre Pre-set values for themare customizable. The "+", "-", and "Edit" buttons are self-explanatory.
Click the "Cancel" button to cancel without keeping your any changes.
Click the "Delete" button (only when editing) to delete the launch tool.
Click the "Accept" button (only when editing) to commit your all changes.
Click the "Create" button (only when creating) to create the launch tool.
Be sure to save your a new Master Profile if you want to keep your all changes.
Clicking on a Launch Tool
Left clicking click on a launch tool's name label will display to display a small dialogdialogue-like window that contains information about the launch tool such as its elvin name (vhmsg name), its arguments, etc. Right click will
Right click to display the following menu items:
- "Edit <tool name>"
...
- : Opens the Editing
...
- dialogue for the launch tool.
- "Clone <tool name>"
...
- : Opens the Creating
...
- dialogue, but the new tool will be pre-populated with the data from this launch tool.
- "Switch to Build Mode"
...
- : Makes this launch tool use the 'build' version of its program.
- "Switch to SVN Mode"
...
- : Makes this launch tool use the 'svn' version of its program.
- "Set as not Launched"
...
- : Sets this launch tool as not being launched
...
Launching a program locally
...
- .
Launching a program locally
To launch a specific program locally, find the program on the Launcher and click on its pull-down list after "Machine:" to choose either "localhost" or the name of the local computer. Click the "Launch" or "Kill" button to either launch or close the program locally. If the program conforms to VHMsg messaging, its row on the Launcher will highlight in green when it is running. Note: If there is a VHMSG_SERVER environment variable, it must be set to "localhost" or the name of the local computer.
Launching a program remotely
This is done just like the same as launching a program locally, except that you should select the name of the remote computer in from the "Machine-Name" argument. The :" pull-down list. The remote computer must be running the RemoteApplicationLauncher on the same VHMSG_SERVER and VHMSG_SCOPE as the Launcher. See See the readme file for the RemoteApplicationLauncher for more details. Make Make sure that the machine which runs the remote launcher has the environment variable VHMSG_SERVER, which should be set to the machine which is running the Launcher. If not using remote launchers, you do this variable does not need to be set this variable.
...
Launching and quitting multiple programs
...
To launch multiple programs, check the boxes next to the programs to be launched and click the top "Run Checked" green "launch" button.
To quit multiple programs, check the boxes next to the programs to be quit and click the top "Run Checked" red "quit" button.
To quit all running programs, click the top "Run Checked" red "quit all" button. Note: This will quit all running programs whether or not their box is checked.
In addition, a Master Profile can be created to run other launch tools. This will launch any program with a checked check-box. If this is a first_wait type of program, it will honor the delay (see above about Creating/Editing Launch Tools). Additionally, it will launch the programs on the machine that is selected in the machine argument of each launch tool.
Launching programs that do not conform to VHMSG messaging
If the program you are launching a launched/running program does not support VHMSG VHMsg messages, it its row will highlight in orange not highlight green on the launcher while it is running (it will be orange instead). It . It will not respond to the "Kill" button so you will have to close it yourself "quit" or "quit all" buttons. This program needs to be closed manually instead of from the launcher. If If the program is an exe (or possibly other types) you can use the ElvinAppWrapper program. ElvinAppWrapper lets you "wrap" a program that does , use the ElvinAppWrapper program which enable programs that do not support elvin messages to respond to the messages required by the launcher. You can find more info in Launcher. For more details, go to the ElvinAppWrapper readme file.
...
VHMsg message protocol to work with the Launcher
It should The application needs to have an "elvin-name" (now called the "vhmsg-name) that it will use for all messages. On start up it should say "vrComponent <vhmsg-name>". When it receives a "vrAllCall" message it should say "vrComponent <vhmsg-name>". When it receives a "vrKillComponent <vhmsg-name>" message it should say "vrProcEnd <vhmsg-name>" and then exit. If it is an agent, then it should listen for "vrKillAgent <vhmsg-name>" instead of "vrKillComponent <vhmsg-name>". If a program only does some of the above, then it ") that it must use for sending and receiving messages. Note that the application's "elvin-name" needs to match the Master Profile's "elvin-name" tag for that application’s launch tool. An application will only partially work with the Java Launcher, if it does not send and receive the proper messages. For more details about the messages go to the VHMsg page.
Things to know
- If a launch tool is the normal gray color of the Launcher window, it is not running.
- If a launch tool is green, then it is running and sending the appropriate VHMSG messages.
- If a launch tool is orange, then it is running but there is possibly a problem. Either the program is not responding (i.e. it crashed) or it does not respond correctly to the vrAllCall message. The launcher can sometimes show a component as unresponsive in error, so it is advisable to check the status of the component manually if problems persist.
- You can Click on a group name to expand/collapse a group by clicking on its name. You can it.
- To send a VHMSG message by typing it , type the message into the text box at the bottom of the window and clicking click the "Send" button. It It has been tested with launching .bat files, .jar files, and .class files, and any . Any properly formatted VHMSG should work.
For more information,contact the vh-support@ict.usc.edu.
Developers
...
Setting up the Launcher for a new project
- Try to keep Be consistent with the naming conventions below. This results in consistency Consistency between projects and ensures the makes it easier for users and developers can easier to get acquainted with a new project.
- Create a master profile, \tools\launch-scripts\profiles\master-config.xml, based on the provided example: tools\launcher\VirtualHumansLauncher\example-master-profile.xml.
- In \tools\launcher-scripts, create a batch file with the name 'run-<project_name>-launcher.bat. The content should be something like this:
@pushd ..\..\tools\launcher\VirtualHumansLauncher call run.bat ..\..\launch-scripts\profiles\master-config.xml @popd
- In your the project root (usually the directory that contains the 'core', 'data', and 'lib' directories), create a 'run-launcher.bat' file. All projects should use this name, so everyone knows instinctively how to launch an unfamiliar project. The contents of the batch file should be something like:
pushd tools\launch-scripts call run-<project_name>-launcher.bat @popd
Compiling the Launcher
You can compile Compile with either NetBeans or with ant.
...
- Go to \lib\vhmsg\vhmsg-java\ and check if look for je4util.jar exists there.
If it does not exist, then you have to compile it by navigating to that folder in a command prompt window and typing 'ant' (no quotes). If that doesn't work, then you will need to install ant: http://ant.apache.org. - Go to \lib\java\ and check if it contains nblibraries.properties, win-process\winp-1.9.jar, win-process\winp-1.9-javadoc.jar, and swing-layout\swing-layout-1.0.3.jar.
If it does not exist, then you cannot compile the project cannot be compiled. - Make sure that the environmental variable JAVA_HOME is set to your JDK folder before continuing.
You can check Check the value of JAVA_HOME by running the check-environmental-variables.bat file. If it is not defined, see the Pre-Running section for instructions on how to set it.
...
- The folder that this file is in (\VirtualHumansLauncher), is a NetBeans project folder. You can get NetBeans from Go to http://www.netbeans.org if it NetBeans is not already installed.
- Run NetBeans and go to File->Open Project and select the folder.
- Click the button with the hammer picture on it (or Build->Build Main Project or F11).
...
See Main FAQ for frequently asked questions regarding the installer. Please use the Google Groups emailing list for unlisted questions.