Next: II. User Manual: Basics Up: FlowVR : A Middleware Previous: Contents Contents
Several source of documentation are available:
FlowVR is packaged in a software suite, called FlowVR Suite, containing FlowVR and several extensions like FlowVR-render.
Download the FlowVR Suite archive file (FlowVR-Suite-1.5.tar.gz or a more recent version)
from:
http://flowvr.sf.net/FlowVRDownload.html.
Uncompress the archive file with the following command:
tar -xzf FlowVR-Suite-1.5.tar.gz
To compile and run FlowVR, the following tools are required:
It is strongly advised to install:
The following tools are useful but do not prevent FlowVR and all its associated tools to be compiled, installed and used:
We rely on CMake to configure and compile all components of the FlowVR Suite. In a first step, Cmake probes your machine and define the components that can be safely compiled, then it generates makefiles.
First create a build directory and call ccmake from this directory :
mkdir BUILD cd BUILD ccmake /path/to/SOURCE/dir -DCMAKE_INSTALL_PREFIX:PATH=/path/to/INSTALLATION/dir
CMake launches a editor. From this editor, press 'c' to configure. Cmake displays a list of options that can be customized. The main options directly related to FlowVR all start with the BUILD prefix. For instance the BUILD_FLOWVR_RENDER enables to control if FlowVR Render should be compiled or not. . Press 't' to access the full list of all available options. Once done, press 'c' again and next press 'g' to generate the makefiles.
To compile:
make
Notice that you can customize a cmake variable directly from the command line. For instance to build FlowVR Render:
ccmake /path/to/SOURCE/dir -DCMAKE_INSTALL_PREFIX:PATH=/path/to/INSTALLATION/dir -DBUILD_FLOWVR_RENDER=1
Notice that beside makefiles, CMake can also generate KDevelop 3 project files or XCode project files (see the -G option)
Once FlowVR compiled, test it launching a simple demo:
bin/flowvr-demo-tictac.sh
A common error at this point (the application refuses to launch) is due to the configuration of the OS that does not allow the allocation of a shared memory segment big enough, see SharedMemorySegmentSharedMemorySegment for hints on how to solve this problem.
This example lauches two modules, put and get. Put sends "tic", "tac" messages to get. The following messages should appear on the standard ouput:
... Sent tic (it=0) Received tic(it=0) from /put:text Sent tac (it=1) Received tac(it=1) from /put:text Sent tic (it=2) Received tic(it=2) from /put:text Sent tac (it=3) ....
If GLUT has been installed, a second test application can be launched using:
bin/flowvr-demo-fluid.sh
![[*]](crossref.png)
.
Move the mouse to interact with the fluid. Click to add more density.
Press the 'v' key to switch between density and velocity field views.
To install:
make install
All required environment variables (PATH, LD_LIBRARY_PATH, etc.) are set in the /path/to/INSTALLATION/dir/bin/*-config.sh and /path/to/INSTALLATION/dir/bin/*-config.csh files.
Before using FlowVR, execute one of the following command (depending on your shell) for a temporary working session, or include the adequate command in your environment configuration for a permanent installation directly:
. /path/to/INSTALLATION/bin/flowvr-suite-config.sh
. /path/to/INSTALLATION/bin/flowvr-suite-config.csh
If FlowVR is properly installed the following command should find the flowvrd executable:
which flowvrd
This section presents a simple FlowVR application, its main components and all the steps needed to build and run it.
To design your own application we advise to start from the primes example and not this one.
We will start off with a closer description of the tic-tac example.
This application has two modules.
The first module (put) sends "tic" and "tac" messages on its output port, while the other module (get) receives these messages and prints them, cp. figure .
Data exchange between these modules follows the FIFO model.
We present how to set up, compile and run this application in the following.
All files related to this example (and we advise all FlowVR applications to follow the same organization) are stored in share/flowvr/examples/tictac/.
This directory contains:
Notice that once installed, the examples are stored in PATH/TO/INSTALLATION/DIR/share/flowvr/examples. In the current case this will resolve to http://www-id.imag.fr/FLOWVR/manual/flowvr-suite-src/flowvr/share/flowvr/examples.
An application is a main component that recursively instantiates sub components. The TicTac application defines a TicTac component by inheriting from the Composite class (share/flowvr/examples/tictac/include/tictac/components/tictac.comp.h).
It instanciates three different components in the virtual method execute (share/flowvr/examples/tictac/src/tictac.comp.cpp).
These three components are instanciated and their ports linked to define the application:
Metamodules are specific components that associate a launching command to a set of modules. Both metamodules instanciated by TicTac inherits from the metamodule MetaModuleFlowvrRunSSH class (include/flowvr/app/components/metamoduleflowvr-run-ssh.comp.h). It uses the flowvr-run-ssh launcher, a simple ssh launcher specialized for FlowVR modules.
The MetaModulePut class defines the metamodule for launching the module ModulePut. In particular it sets the executable (CmdLine("put")) to call for starting this module (share/flowvr/examples/tictac/include/tictac/components/metamoduleput.comp.h).
The same is done for MetaModuleGet (share/flowvr/examples/tictac/include/tictac/components/metamoduleget.comp.h).
The last components to define are the put and get modules. They both inherit from the Module class (include/flowvr/app/components/module.comp.h) and define their output and input ports "text" (share/flowvr/examples/tictac/include/tictac/components/moduleput.comp.h and share/flowvr/examples/tictac/include/tictac/components/moduleget.comp.h).
More details about application design are given in the following.
The components ModulePut and ModuleGet are only the interface of the modules that are actually executed. The code of the put and get modules is defined in :
More details about module programming are given in the following.
To compile the modules and the application we rely on Cmake. The TicTac examples comes with a simple utility script that set some variables when calling cmake, executing make and make install. Execute it from the TicTac directory:
./make-app.sh
We first execute the TicTac application on the machine the application is compiled, i.e. all application components run on the same local host.
FlowVR is daemon based. Therefore a daemon must be running on each node involved in FlowVR application, including the node where the application is launched from.
In case of a local execution, only one deamon need to run on the local machine. Execute:
flowvrd -top
When launched, the daemon requests the OS to allocate a shared memory segment. The size of this segment has a default value.
It is common that the maximum shared memory segment the OS allowed is too small to run even the more basic FlowVR examples. See the documentation related to your OS to change this maximum size. For instance on a Linux machine, this max size is set in the /etc/sysctl.conf file with:
# Big SHM for FlowVR kernel.shmmax = 838860800
If the size of the memory segment allocated by the daemon is too small for you application (especially if you have modules requesting large buffer allocations for messages), use the option -s to adjust this size. You should not have to change this default size for the TicTac example. Note that you might have to reboot your machine after adding this line to /etc/sysctl.conf.
See the section dedicated to the daemon for more informations about the daemon.
To launch the TicTac application (we assume you are in the tic-tac example directory) on the local machine, you first have to set the required environment variables executing for a sh/bash shell:
. bin/tictac-config.sh
. bin/tictac-config.csh
The application starts executing:
flowvr -localhost -launch TicTac
To stop the application (not the daemon), enter:
stop
A common error, especially when several instances of FlowVR are installed, is to execute the application using the wrong module binary codes or loading the wrong library file. This happens if the environment variables are not correctly set.
The demo script bin/flowvr-demo-tictac.sh cleans environment variables before to set the correct ones. If TicTac runs with this script and not the instructions given in this section, you probably have a path issue.
If the application does not start or stop correcly, it can results in zombie processes polluting the machine. We provide a script to kill all these processes. To execute it run:
flowvr-kill
See flowvr-kill documentation for more informations about this script.
If you have installed the required software, you can generate an image of the application graph either through flowvr-graph or flowvr-glgraph.
flowvr-glgraph is an interactive network visualizer. To launch it loading the TicTac application:
flowvr-glgraph tictac.net.xml
flowvr-graph can be user to compute a static image. Simply write:
flowvr-graph -Tjpeg -o tictac.jpeg < tictac.net.xml
The two modules of TicTac can easily be executed each one on a different machine.
Two machines are required. Let us call node1 and node2 these two machines (replace with the actual names of your machines). These machines should have:
The goal is to have an instance of the put module running on the remote host node2, and the get module running on the local host node1.
The application does not have to be modified. Only the mapping of the modules on the hosts need to be specified correctly. This mapping is specified in the share/flowvr/examples/tictac/tictac.csv file. This file uses the cvs standard and so can be opened and modified with a spreadsheet editor, or a simple text editor. Each line corespond to a module to be mapped (identified with its fill id), while rows define the hosts where to start these modules. You should only replace the names pc1 and pc2 by your own host names.
Start a FlowVR daemon on both computers using:
flowvrd -t -net
The -net argument tells the daemon to listen to network connections.
Start the application:
flowvr -launch TicTac
