Stop reading if you just want to…
- stream data from one of the Supported Devices and Tools or record data with the LabRecorder. You can download pre-built releases for the apps and LabRecorder from each repositories release page.
- create or use a program to stream or receive data via the LabStreamingLayer. You can download a precompiled liblsl binary from the liblsl release page
Follow this guide if you are…
- want to add / modify core liblsl
- Please create a GitHub issue first to ask for advice and to get pre-approval if you would like your modification to be included in the official library.
- build liblsl for a device / OS with no official release (e.g. an embedded Linux device)
Before attempting to build liblsl, please make sure you have configured your LSL build environment.
This part of the guide 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.
Getting the source¶
Open a Terminal / Developer Command Prompt and cd to a convenient location to download and build the library.
git clone --depth=1 https://github.com/sccn/liblsl.git
The resulting folder structure is as follows.
(working directory) └── liblsl ├── include ├── lslboost ├── project ├── src └── testing
Configuring the liblsl project¶
Visual Studio and QtCreator users can use the integrated CMake, just open
the folder containing
CMakeLists.txt and select the appropriate
Please see the documentation (TODO) comparing normal CMake to Visual Studio’s integrated CMake.
If you wish to use the integrated cmake, then you do not need to follow the
terminal commands below.
cd liblsl cmake -S . -B build -G <generator name> <other options>
cmake -G without a generator name to get a list of available
cmake -S . -B build -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX="build/install"
If you used a generator, you can now open the IDE project file. Then build the install target.
Alternatively, you can build directly from command line:
cmake --build build -j --config Release --target install
Build options for liblsl¶
There are several liblsl-specific build options.
All of them can be set either in the GUI (cmake-gui or Visual Studio) or on the
command line (
This is not an LSL-provided option, but it’s a common and important option when building the install target. See the official documentation. This argument is often necessary on Windows because otherwise it will attempt to install into C:Program Files which will fail without administrative rights. A good value to pass is “build/install”.
Enable (lots of) additional debug messages. Defaults to OFF.
The liblsl distributions includes several example programs. Enabling this option builds them alongside liblsl.
By default, a shared library (.so on Unix, .dylib on OS X and .dll on Windows) is built. This also exports a static library.
Once upon a time there was a C++-ABI, but it only worked under very specific circumstances and created hard to debug errors otherwise. Don’t enable this unless you know exactly what you are doing.
By default, CMake decides what to name the library (see Binaries). On Windows this is
lsl.<extension>and for Unix (Linux/Mac) it is
liblsl.<extension>. Enabling this option will force the library to be named
liblsl<ptrsize>.<extension>on all platforms.
liblsl includes two types of unittests: internal tests, that check that various internal components work as intended, and external tests that test the API as programs would.
Macs, Unix / Android systems and distributions like Anaconda have a specific directory layout (binaries in
prefix/bin, includes in
prefix/includeand so on), whereas Windows users prefer everything in a single folder. If enabled, the LSL_INSTALL_ROOT folder will have a layout as it should be on Unix systems.
Change the minimum targeted Windows version, defaults to 0x0601 for Windows 7.
Enable some more compiler optimizations. Defaults to ON.
Use the bundled pugixml by default. Defaults to ON.
Building liblsl language bindings¶
Full Tree Dev¶
For advanced users (mostly core developers), it might be useful to simultaneously develop multiple apps and/or libraries. For this, please see the Working With The LabStreamingLayer Repository documentation to setup the lib and app tree, then follow the build instructions in Building LabStreamingLayer Full Tree.
Maintaining package manager ports¶
Ports of liblsl are available via a number of third-party package managers. When new releases of liblsl are published, these ports can be updated using the following steps:
vcpkg ports are managed in the microsoft/vcpkg repository on GitHub and changes or additions are submitted in the form of pull requests. For a general overview of vcpkg, see https://github.com/microsoft/vcpkg/tree/master/docs.
The liblsl port is maintained at https://github.com/microsoft/vcpkg/tree/master/ports/liblsl.
- For new liblsl releases where no changes have been made in the CMake build scripts, it should be enough to update the library versions in vcpkg.json and in portfile.cmake.
- If there have been changes in the CMake build scripts, portfile.cmake may need to be adapted accordingly. If any dependencies have changed (e.g. the version of Boost), the dependency information in vcpkg.json needs to be updated, as well.
Conan packages are managed in the conan-io/conan-center-index repository on GitHub and changes or additions are submitted in the form of pull requests. For a general overview of the Conan package maintenance process, see Adding Packages to ConanCenter.
The liblsl port is maintained at https://github.com/conan-io/conan-center-index/tree/master/recipes/liblsl.
- For new liblsl releases where no changes have been made in the CMake build scripts, it should be enough to add the new library version to config.yml and to conandata.yml.
- If there have been changes in the CMake build scripts, conanfile.py may need to be adapted accordingly. If any dependencies have changed (e.g. the version of Boost), the dependency information in conanfile.py needs to be updated, as well.