System requirements

The toolset is available for Linux (Debian family) PC's.
The executables need java 1.4 (or above), or eclipse 3.1 (or above), and gcc 3.x

The bip parser may works on command line with a java 1.4 or upper, or under eclipse version 3.1 or upper.

Structure of the installation

The archive obtained in the download page on extraction gives the following structure under folder BIP:

• BIP/bin, containing 'bipc', the parser cum code-generator executable in text mode.
• BIP/plugins, containing the java libraries for the parser, code-generator and other imported libraries.
• BIP/importedplugins, containing imported eclipse library.
• BIP/include, containing BIP specific header files.**
• BIP/lib, containing the BIP engine libraries.**
• BIP/util, containing a Makefile (to build the BIP-application) and a link to the code generator.
• BIP/examples, an example area, containing a simple bip example (producer-consumer).
  
  (**  single threaded and multi threaded)

Setting up the environment

To use the tools, it is mandatory to define the environment variable $BIP_HOME, and add $BIP_HOME/bin in the path.

Installing eclipse environment

To use the BIP editor integrated in eclipse, it is necessary to install eclipse, and the needed plugins:

• install eclipse from the eclipse download site
• install EMF plugins from the EMF download site. Be careful, the EMF version must be in accordance with the installed eclipse version
• install ANTLR by copying the $BIP_HOME/importedplugins/org.antlr_2.7.6 in the eclipse/plugins directory
• install BIP plugins by copying the $BIP_HOME/plugins contents in the eclipse/plugins directory
• set the BIP_HOME eclipse variable in the “Bip Preferences” onglet of preference windows (eclipse command “window”/”preferences...”)

The next eclipse run will have BipMenu commands and buttons “compile”, “generate” and “make” in the toolbar. The BIP editor will be active on files with “bip” or “eBip” extensions.

The Code-Generator options

Under eclipse, open the bip source file, and use the BIP commands "compile" then "generate".
From the command line, the code generator executable named "bipc" generates  C++ code, either from an input bip description, or a model.

The command line options are as follows:

$ bipc -f input.bip --genC-top top_component_name $ bipc -m input.model --genC-top top_component_name

where "input.bip"/"input.model" are the input bip description/model of the system, and "top_component_name" is the top level component in the system.  If there is a unique top level component (a component never instanciated) the code generator will automatically choose this one by default.

The complete list of  options can be obtained by

$ bipc --help

Options are:

• -f filename : specify the bip source file name
• -m modelname : specify the model file name
• -I includeDir  ; add the directory includeDir to the list of directories to be searched for include files
  
• --genC-top topname : generate C code and specify the top component name
• --genC-execute : generate C code for execution
• --genC-multi : generate C code for multithreaded execution. In this case, you have to use the engine=multi_th option to the make command
  
• --genC-explore : generate C code for exploration or execution

If none --genC option is specified, the command will only generate the model.

The Engine run-time options

The BIP engine reads the run-time options from the file '.bipsrc' which should be present in the run directory.

• Running an execution trace

To run a simulation trace, use  -execute  in '.bipsrc'.

• Running a Single-step execution (helpful for debugging)

In order to perform a step-by-step execution, use the option -interactive. This allows the user to select one interaction from a list of feasible interactions, to be executed by the engine. An example trace is shown below:

List of legal connectors are : [1] [consWork] consumer:dowork [2] [prodWork] producer:dowork Enter connector number (Hit 0 to exit) :

• Running in quiet mode

By default, during execution the engine displays the sequence of interactions it executes. This can be supressed using the -quiet option. This can be useful if some graphical output is produced. (eg,  the  billiards example).

• State-Exploration mode

To run an exploration, you have to generate C++ code with the option –genC-explore. Then you can either run it in execution mode, or in exploration mode using the option -explore in tht .bipsrc file. With this option you can specify the exploration mode with the options -bfs, -dfs, and the output files names with th option -o <file name>. In this case the      output files will be <file name>.aut and <file name>.state.

• Termination of execution

An application can execute infinitely, stop on a deadlock, or stop after a specified number of steps (interactions), or can be terminated  by a keyboard interrupt like Ctrl-C from the user. The number of steps can be specified in the ".bipsrc" file by the option -limit, followed by an integer value.

Running the first example

Lets try the first example, a producer-consumer application, already present in the 'examples' folder.  The model consists of a producer and a consumer component which can work independently and communicate through strong synchronization. We modeled the behavior of the producer and consumer as a single component named "Worker". It has two ports, namely "communicate" which is an incomplete port and "dowork" which is a complete port.  The behavior is expressed as a transition system with two states, WORK and COMM and associated transitions trigered by 'communicate' and 'dowork'. The top level component name is "Team", which instantiates a 'producer' and a 'consumer' from the 'Worker' component. A connector named 'prodCons' is created between the "communicate" ports of the producer and consumer.
To run this example, we generate the C++ code using the BIP to C++ code generator.

$ bipc -f prodcons.bip --genC-top Team

This will generate the application source files, namely prodcons.bip.h and prodcons.bip.C. In order to compile this application and generate the binary named prodcons.bip.x,

$ make -f $BIP_HOME/util/Makefile prodcons.bip.x

or under eclipse user the Bip command make.

To execute a trace, run the binary

$ prodcons.bip.x

Output displayed by the engine

In the default mode of execution, the sequence of interactions executed by the BIP engine is displayed.

scheduler : [prodCons] consumer:communicate|producer:communicate scheduler : [prodWork] producer:dowork ...

The displayed format is :: scheduler : [connector_name] interaction
interaction :: component_name : port_name (| component_name : port_name)*