INSTALL

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

|Introduction|

This document explains how to build the platform from sources.

|Repository.organisation|

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

|Build.target|

OpenViBE should compile on x86 / x86_64 architecture running Microsoft Windows 2k/XP/Vista/7
with Visual C++ 2008 express edition (take care of having the SP1 platform SDK
installed).

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.

|Prerequesite.dependencies|

In order to build the software, one must install several dependencies.
This may be done using the provided installation scripts which will
automatically set up your environment.
<win32-install_dependencies> installs dependencies under Windows and
<linux-install_dependencies> installs them under Linux.

The Windows installer processes prebuilt packages and therefore is quite fast.

The Linux installer processes a few source packages and builds them from scratch.
One should be able to install each dependency in a local directory without requiring
root access and without using any package manager such as apt-get or yum. 
However, it is safer to use native packages.

|Preparing.environment|

The build process uses many environment variables. The 'script' directory
contains the necessary files to build the whole platform and plugins.
However, the script initializing the environment variables is missing because
it must be tuned according to each local installation and usage. However, the
<linux-init_env_command-skeleton> and <win32-init_env_command-skeleton> files
may be used as a basis to create such scripts. Most Linux users will simply
want to copy the <linux-init_env_command-skeleton> to <linux-init_env_command>. 
Under Windows, copying the windows skeleton to <win32-init_env_command> may not 
be enough because of installation specifics such as Visual Studio paths and so on... 
Script tweaking is required here ;)

|Building.the.platform|

If you want to build all projects at once, you can use the <linux-build> or
<win32-build> scripts. Both scripts call the appropriate
<init_env_command>, which must have been properly configured. 

Since each project will compile in its own directory, the <linux-collect_build> and
<win32-collect_build> scripts should be used to get all built files and copy them to 
the <dist> directory.

The <linux-test> and <win32-test> scripts will collect the build and then launch 
the most interesting softwares for you.

If you made it this far, congratulations : you should now have OpenViBE working!

|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: