INSTALL

         *========================================*
                     |OpenViBE| |INSTALL|
         *========================================*

|Introduction|

This document explains how to build the OpenViBE platform from the sources. 
More up-to-date information may be available at 

http://openvibe.inria.fr/build-instructions/

|Repository.organisation|

Please refer to the README file to have information on the repository
organisation.

|Build.target|

Windows: OpenViBE should compile on x86 / x86_64 architecture running Microsoft 
Windows 2k/XP/Vista/7 with Visual C++ 2008 or 2010 Express Edition (take care 
of having the up-to-date platform SDK from Microsoft installed).

Linux: OpenViBE should compile on x86 / x86_64 architectures running Linux with gcc 4.*

Please consider that trying to compile OpenViBE on other hardware/OS/compiler
is experimental and has not been tested. If you wish to try and get OpenViBE 
to run on other hardware/OS/compilers, your efforts are welcome
but you should not expect to get support on the short term.

|Building.on.Windows|

1. Short story:

For command line -style building using NMake, double-click:

# win32-install_dependencies
# win32-build

For IDE style building using Visual Studio, double-click:

# win32-install_dependencies
# win32-generate-vcproj
# win32-launch-vc

You may have to tweak the last script to find your particular version of Visual Studio.

The built openvibe should now be in "dist\" folder. If it didn't work, read the longer description for hints.

|Detailed.building.instructions.for.Windows|

1. Install dependencies

In order to build the software, you must install several dependencies.
This may be done using the provided installation scripts which will automatically 
set up your environment. Run the following *inside* the scripts/ directory:

<win32-install_dependencies> installs the dependencies under Windows.

The Windows installer uses prebuilt packages and is quite fast.

2. Prepare the environment

The 'scripts' directory contains the necessary files to build the whole platform and plugins.
The <win32-init_env_command> sets the build environment.  You may have to tune this 
and other scripts by hand due to installation specifics such as Visual Studio paths.

3a. Build using NMake

If you want to build all projects without an IDE, you can use the <win32-build> script. 
The script calls <win32-init_env_command>, which must be able to set the development
environment correctly.

3b. Build using Visual Studio

Use <win32-generate-vc-proj> in scripts\ directory to generate a Visual Studio
solution to "local-tmp\visual\". The script calls <win32-init_env_command>, 
which must be able to set up the development environment correctly. 

Script <win32-launch-vc> can then be used to launch Visual Studio 2010 Express 
while taking care that all the environment variables have been set. To use other
version of Visual Studio, change the path on the last line of the script to 
point to your version.

Note the following when using Visual Studio with OpenViBE:

- When launching Visual Studio, the OpenViBE environment variables must have
already been set (as done by <win32-launch-vc>)
- Always compile the INSTALL target to get everything copied under "dist\". This 
is required so that the compiled OpenViBE applications can find the DLL files.
- When debugging an OpenViBE executable in Visual Studio, you may have to set the
correct Properties->Debugging->Working Directory by finding "dist\bin\" with browse.
- All Visual Studio projects are created by CMake, so any changes to the project 
configurations should be made to the CMake scripts.
- If you want to add any files to the build tree, delete "local-tmp\visual\CMakeCache.txt"
and run the <win32-generate-vc-proj> again.

4. If you made it this far, congratulations : you should now have OpenViBE working,
and the freshly built OpenViBE in "dist\".


|Building.on.Linux|

1. Short story

# ./linux-install_dependencies
# ./linux-build

The built OpenViBE should be in "dist/". If not, please read the longer description for hints.

|Detailed.building.instructions.on.Linux|

1. Install dependencies

In order to build the software, you must install several dependencies. This may be 
done using a provided script. Run the following *inside* the scripts/ directory:

<linux-install_dependencies> installs dependencies under Linux.

The Linux installer processes a few source packages and builds them from scratch. Most
of the packages are installed from your Linux distribution. Hence this script requires 
root access. If you don't have one, please ask your IT support to install the OpenViBE 
dependencies for you as listed in the script.

2. Build the platform

To build OpenViBE, you can use the <linux-build> script while in the scripts/ directory. 

Finally, the <linux-test> script will launch the most interesting applications for you.

If you want to build only some specific subtree, first build the whole OpenViBE 
and then change to the appropriate subtree under local-tmp/. There you can call 
"make" and "make install" to build only that component.

3. If you made it this far, congratulations : you should now have OpenViBE freshly 
built to "dist/".

|Elementary Linux packaging|

To build an elementary Debian/Ubuntu/Mint package from the official tarball (>= 0.16.0) 
using debhelper, do the following:

# mv openvibe-X.Y.Z.tar.gz openvibe_X.Y.Z.orig.tar.gz
# tar xzvf openvibe_X.Y.Z.orig.tar.gz
# cd openvibe-X.Y.Z
# debuild -uc -us

|Contribution.rules|

Developers wishing to contribute to OpenViBE should be aware that several coding
rules have been fixed to ensure homogeneous source code. These rules are as follows :

 - namings :
   - English is used for all names (class, function, variable...)
   - Abreviations are not tolerated anywhere in the code. All names must be as explicit as
     possible (makes it a bit longer to write code when automatic completion is not
     available, but in turn it is much easier to read for people who did not write this code!)
   - class names start with C
   - template names start with T
   - interface names start with I (as with pure abstract classes of an API)
   - members start with m_
   - local variables start with l_
   - global variables are prohibited (please contact the dev coordinator if this
     is necessary in your case)
   - function parameter names do not have a specific prefix
   - variable names are prefixed with their type : b for boolean, s for string,
     r for references, o for objects, i16 for signed 16 bits integers, uint64
     for unsigned 64 bits integers or float80 for 80 bits floats...
   - function names do not have a prefix, start with a lowercase character and
     use upper case characters for each new word
   - curly brackets always stand alone on new lines
   - if / else blocks always have curly brackets, even if only one call is
     to be done
 - English is used in all code documentation
 - Code documentation is done with doxygen (http://www.stack.nl/~dimitri/doxygen/)
 - Implementation is documented for complex things with or without doxygen
 - non portable libraries (should it be software or hardware compatibility)
   are isolated in separate modules (such as EBML, XML, FS etc...)
 - every class is constituted by a pair of files : header (definition) and source
   (implementation)
 - redundant includes should be avoided thanks to #ifndef #define #endif directives at the
   begining and end of header files
 - API header files should be stored in a folder named after the module name
 - At least one namespace should be used per module so to avoid symbol name
   collisions
 - 'using namespace' directives must not be used in header files
 - generalized use of basic types provided by modules (float32, uint32 and so on) 
   is strongly encouraged so that type sizes are explicit throughout the code 
   and thus at any time, a developer knows what can be done with the values being manipulated.

This is a sample of OpenViBE-compliant code illustrating these rules :

/**
  * \file SampleFile.h
  * \author me
  * \date today
  * \brief a sample file containing TSample template
  *
  * This sample file contains the definition of the
  * TSample template blah blah more details...
  */
namespace SampleNamespace
{
        /**
         * \class Tsample
         * \author me
         * \date today
         * \brief short-blah
         *
         * Detailed blah blah
         */
        template <class T>
        class TSample : public T
        {
        public:
                /**
                  * \function sampleFunction
                  * \param rInputValue[in] : blah
                  * \param rOutputValue[out] : blah
                  * \return blah blah
                  * \brief short-blah
                  *
                  * Detailed blah blah
                  */
                virtual SampleNamespace::boolean sampleFunction(
                        SampleNamespace::boolean bInputValue,
                        SampleNamespace::boolean& rOutputValue)
                {
                        SampleNamespace::boolean l_bCondition=true;
                        if(l_bCondition)
                        {
                                rOutputValue=bInputValue;
                                return true;
                        }
                        return false;
                }
        };
};

|Contribution.howto|

Contributions integration is done at several different levels.

- First, core developers have full access to the forge. This means they can modify
  any file, including trunc branches (unstable version of the software) and tags.
- A second level includes restricted write access to the forge. People working
  in this configuration work in their own branches. It is up to core developers 
  to decide whether or not a branch is ready for integration to the mainstream version.
- A third and last level concerns people with read-only access to the forge. Such
  users may produce patches and develop custom functionalities "locally", which only developers
  with write access will be able to integrate to the forge. Creating such patches may be done 
  easily by dumping the output of a "svn diff".

|End.of.file|

 vim:tw=78:ts=8:ft=help:norl: