=======
General
=======

This manual describes the process of building liblsl from source for Windows, Mac OS X, and Linux. Since liblsl is cross-platform (it is written in standard C++ and uses some boost libraries), this process should be pretty straightforward. The following paragraphs provide a step-by-step instruction of the build process on all three platforms. 

To get an overview of the project structure, the following tree lists the directory hierarchy of the source after you've unpacked the compressed source archive:

  labstreaminglayer
  ├── Apps
  │   ├── AMTI ForcePlate
  │   ├── AudioCaptureWin
  │   ├── BAlert
  │   ├── BioSemi
  │   ├── Cogionics
  │   ├── EGIAmpServer
  │   ├── Embarcadero XE
  │   ├── Enobio
  │   ├── EyeLink
  │   ├── GameController
  │   ├── Keyboard
  │   ├── KinectMocap
  │   ├── LabRecorder
  │   ├── MATLAB Importer
  │   ├── MATLAB Viewer
  │   ├── MINDO
  │   ├── Mouse
  │   ├── Neuroscan
  │   ├── OptiTrack
  │   ├── PhaseSpace
  │   ├── SMI iViewX
  │   ├── Tobii
  │   └── Wiimote
  └── LSL
      ├── liblsl [*]
      │   ├── bin
      │   ├── docs
      │   ├── examples
      │   ├── external
      │   │   ├── lslboost
      │   │   └── src
      │   ├── include
      │   ├── project
      │   ├── src
      │   │   ├── portable_archive
      │   │   └── pugixml
      │   └── testing
      ├── liblsl-Matlab
      ├── liblsl-Python
	  └── liblsl-Java
	  
To build liblsl, we are primarily interested in the directory labstreaminglayer/LSL/liblsl (marked with [*] in the tree above). Therefore, we will denote this directory as $LIBLSL_ROOT in this manual.


=======
Windows
=======

Tested platforms:
* Windows 7 (32bit,64bit)

Prerequisites:
* Visual Studio Express 2008, 2010, or 2012
* cmake

Build process:
* Unpack the source archive (or check out the latest development version via Mercurial)
* Create a folder named "build" inside $LIBLSL_ROOT
* Start CMake (cmake-gui)
* In "Where is the source code", enter $LIBLSL_ROOT
* In "Where to build the binaries", enter $LIBLSL_ROOT/build
* Click "Configure"
* Choose "Visual Studio 11" and "Use default native compilers" and click "Finish"
* Click "Generate" -- this will create (among other things) a Visual Studio solution file in $LIBLSL_ROOT/build
* Open $LIBLSL_ROOT/build/liblsl.sln with Visual Studio (double-clicking should just work)
* In the "Solution Configuration" drop-down list, select either "Release" or "Debug", depending on what you want to build
* Hit F7 (or click "Build Solution")
* The resulting library (lsl.dll) will be located in $LIBLSL_ROOT/build/src/Release or $LIBLSL_ROOT/build/src/Debug
  Note that some older applications might expect this library to be called liblsl32.dll or liblsl64.dll.

Alternative using hand-made project files:
* Tested with Visual Studio 2008 Professional on Win32/64.
* Note that use of these project files will be deprecated in the future in favor of a unified cross-platform CMake build.
* Open the solution $LIBLSL_ROOT/project/vs2008/vs2008.sln and go to Build/Batch Build...
* Ensure that everything is checked that you like to rebuild, and then start the build.
* Binaries in the bin/ folder will be overwritten

========
Mac OS X
========

Tested platforms:
* Mac OS X 10.8 (Mountain Lion)

Prerequisites:
* Xcode
* cmake (either from the official cmake website or via MacPorts)

Build process:
* See the Linux section below

Alternative using hand-made project files:
* Tested with XCode 4.2 on Mac OS X 10.7.
* Note that use of these project files will be deprecated in the future in favor of a unified cross-platform CMake build.
* Open the XCode workspace $LIBLSL_ROOT/project/Xcode/Xcode.xcodeproj
* Click Run (which will trigger the build process)
* Binaries in the bin/ folder will be overwritten

=====
Linux
=====

Tested platforms:
* Arch Linux (64bit)

Prerequisites:
* GNU toolchain (make, gcc, binutils)
* cmake

Build process:
* Open a terminal
* Unpack the source archive (or check out the latest development version via Mercurial)
* Change into $LIBLSL_ROOT
  $ cd $LIBLSL_ROOT
* Create a build folder
  $ mkdir build
  $ cd build
* Execute cmake
  * If you want to compile and use the included boost libraries:
    $ cmake ..
  * If you want to use your system boost libraries:
    $ cmake .. -DUSE_SYSTEM_BOOST=ON
* Build the library
  $ make
* Once the build finishes, the library (liblsl.so) can be found in $LIBLSL_ROOT/build/src

Alternative using hand-made project files:
* Tested with Code::Blocks 10.05 on Ubuntu (64bit)
* Note that use of these project files will be deprecated in the future in favor of a unified cross-platform CMake build.
* Open the Code::Blocks workspace $LIBLSL_ROOT/project/code.blocks
* Click Build
* Binaries in the bin/ folder will be overwritten


================================
Other Platforms or Build Systems
================================

LSL has no external dependencies and can be compiled with any standards-compliant C++ compiler on a POSIX platform. To build liblsl from scratch with an unsupported build system, ensure that you have the following (all paths below are relative to LSL/liblsl):
Sources Files = src/*.cpp, src/pugixml/*.cpp, external/src/chrono/src/*.cpp, 
                external/src/filesystem/src/*.cpp, external/src/serialization/src/*.cpp, external/src/system/src/*.cpp, external/src/thread/src/*.cpp,
                external/src/thread/src/pthread/*.cpp (note: use external/src/thread/src/win32/*.cpp instead on Windows)

Include Directories = include, external

Linked Libraries = libpthread, librt (if present -- not necessary on Mac, for example)

Preprocessor Definitions = Optionally (if on Windows and building a library), define LIBLSL_EXPORTS, BOOST_ALL_NO_LIB, and BOOST_THREAD_BUILD_LIB 

Compiler Options = Those that are necessary to build a shared library with your compiler, e.g. for gcc: -shared -fPIC -o liblsl.so)

Example gcc command line for building liblsl.so:
gcc src/*.cpp src/pugixml/*.cpp external/src/chrono/src/*.cpp external/src/filesystem/src/*.cpp external/src/serialization/src/*.cpp external/src/system/src/*.cpp external/src/thread/src/*.cpp external/src/thread/src/pthread/*.cpp -shared -o liblsl.so -lrt -lpthread -fPIC -Iinclude -Iexternal -Os

