Installing and Running Command-Line breve on Mac OS X, Linux and Windows
<< previous | Chapter 2. Introduction to breve | next >>

## Installing and Running Command-Line breve on Mac OS X, Linux and Windows

The command-line version of breve allows you to run breve simulations from the command-line either with or without graphical display. The command-line version of breve is available for Mac OS X, Linux and Windows.

The command-line version of breve can be used to develop and run breve simulations just like the OS X breve Application or the breveIDE for Linux and Windows, but it is also especially useful for running breve simulations from shell scripts or from other programs. In this way, a breve simulation can be integrated into another program or scripting environment in order to perform some sort of simulation, and return the results.

When the command-line breve starts up in graphical mode, the simulation is paused: press the space-bar to begin the simulation. This behavior can be modified using the "-u" flag described later in this section.

### For Windows and Linux Users

In order to run the command-line breve on Windows or Linux, you'll need to have OpenGL and GLUT libraries installed on your system. If you encounter problems running breve, you may need to install these libraries. They are freely available from the internet.

### Setting Up Your Environment

Before running breve, you'll need to set up the environment variable `BREVE_CLASS_PATH`. This variable must contain the location of the "lib/classes" directory included in the distribution. Setting this environment is done differently for different shells and platforms. Some examples are shown below. `path to breve` is the location of the breve distribution folder that you downloaded.

    # tcsh users (Linux & OSX):
            setenv BREVE_CLASS_PATH /<path to breve>/lib/classes

    # bash users (Linux & OSX):
            export BREVE_CLASS_PATH=/<path to breve>/lib/classes

    # Windows console users:
            SET BREVE_CLASS_PATH=C:\<path to breve>\LIB\CLASSES

You may freely move around the files in the breve distribution (to install them in `/usr/local` on a UNIX system, for example), but be sure to set your `BREVE_CLASS_PATH` accordingly.

### Running the Demo Simulations

Once your `BREVE_CLASS_PATH` environment variable is configured, you can get started by running breve with one of the included simulation files. Assuming that you are in the breve distribution directory, you can try out the "ArrowSwarm" demo by typing:

    # Linux
            % ./bin/breve.sh ./demos/Swarm/ArrowSwarm.tz

    # OSX
            % ./bin/breve ./demos/Swarm/ArrowSwarm.tz

    # Windows
            > bin\breve.exe demos\Swarm\ArrowSwarm.tz

This command will open a graphical display window containing the simulation, which is initially paused. To unpause the simulation, hit the space bar. When the simulation is running, the following controls can be useful:

- Space bar: pause/unpause the simulation

- F1: run simulation forward one iteration step

- Left mouse: rotate simulation and select objects (described below)

- Right mouse click: display the simulation menu (described below)

- Right mouse click (when an object is selected): display a contextual menu for the object (described below)

- Control (or F2) + left mouse: zoom in and out of the simulation

- Alt (or F3) + left mouse: move the camera

- Shift (or F4) + left mouse: select and drag objects in the simulation

- Escape: to quit the simulation, or access the breve command prompt

The keys F2, F3 and F4 can be used instead of control, alt and shift, respectively, to allow for easier use on platforms which emulate middle and right mouse buttons using the control, alt or shift keys.

The breve command prompt (which can be accessed using the escape key) can be used to execute commands in running simulations. "steve" commands are typed in at this prompt, and will be executed in the simulation's controller object. The steve language (and the controller object) are described in the next chapter (the section called “Writing breve Simulations With "steve"”).

### The Simulation Menu and Object Contextual Menus

Users can also interact with a running simulation via the simulation menu and through the contextual menus associated with specific objects, both accessed via the right mouse button. To access the simulation menu, be certain that no object in the simulation is selected, and click the right mouse button. To access a contextual menu for an object in the simulation, use the right mouse button while an object is selected.

By default, the simulation menu and contextual menus are mostly empty. As you begin to customize simulations and construct your own, however, you will be able to add your own custom options to the simulation and contextual menus.

### Viewing the Simulation Code

Simulations written in breve use the suffix ".tz" and are regular text files. You can open up the file in your favorite editor to see how it works:

    % pico ./demos/Swarm/ArrowSwarm.tz

If this is your first time running breve, it is recommended that you take the time to explore the demos and their code. By exploring the demos, you'll see how a number of breve's features are used and gain a basic understanding of how simulations are written.

### Command-Line breve Without Graphical Display

If you wish to run a simulation without graphical display, you can use the command `breve -x`. Follow the same setup directions described above (the section called “Setting Up Your Environment”) in order to setup your environment, and then run the simulation:

    % ./bin/breve -x ./demos/Push/PushRegression.tz

Textual output will be printed as usual, but no graphical window is shown. This feature is most useful for collecting data when user interaction and observation is unimportant.

<< previous | Up | next >>
Installing and Running the breve Application on Mac OS X | Table of Contents | Installing and Running breveIDE on Linux and Windows