Skip to content

Commit

Permalink
Docs: update build documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@tstenner
tstenner committed Nov 20, 2019
1 parent b6d8d30 commit f3166f3
Show file tree
Hide file tree
Showing 2 changed files with 98 additions and 135 deletions.
99 changes: 42 additions & 57 deletions docs/dev/build.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,11 @@ and the
labstreaminglayer
├── Apps
│ ├── AMTI ForcePlate
│ ├── Examples
│ ├── LabRecorder
│ ├── [several other apps]
│ └── Wiimote
└── LSL
├── liblsl
│ ├── external
│ ├── include
│ ├── lslboost
│ ├── project
Expand Down Expand Up @@ -67,7 +65,7 @@ building.
- Mac - Use `homebrew <https://brew.sh/>`__ (``brew install cmake qt``)

- Ubuntu (/Debian):
``sudo apt-get install build-essential cmake qt5-default``
:command:`sudo apt-get install build-essential cmake qt5-default`

A few apps also depend on :ref:`Boost`.

Expand Down Expand Up @@ -101,76 +99,61 @@ In tree builds (recommended)

- If the build directory is already there then delete it

- Windows: ``rmdir /S build``; Others: ``rm -Rf build``
- Windows: :command:`rmdir /S build`; Others: :command:`rm -Rf build`

- (Create the ‘build’ dir: ``mkdir build``)
1. Configure the project using :ref:`buildenvcmake`

1. Configure the project using ``cmake``
- Option 1 - Visual Studio 2017 or later

- Option 1 - Using the GUI
- Open the :file:`CMakeLists.txt` file in Visual Studio
(:guilabel:`File->Open->CMake`)
- Change CMake settings via :guilabel:`CMake->Change CMake Settings`

- Open a terminal/shell/command prompt and change to the
labstreaminglayer directory.
- See `Common Cmake Settings <#common-cmake-options>`__ below

- ``cmake-gui -S . -B build`` (GUI) or ``ccmake -S . -B build``
(terminal) on other platforms.
- Change the selected project from the drop-down menu (:guilabel:`x64-Debug`,
:guilabel:`x64-Release`).
This will trigger a CMake re-configure with the new variables.

- Option 2 - Using commandline.

- Do an initial ``Configure``. Agree to create the directory if
asked.
- Open a Terminal window or, on Windows, a ‘Developer Command Prompt
for VS2017’ (or 2019, as needed)
- Run cmake with appropriate `commandline options <#common-cmake-options>`__.

- Option 3 - Using the GUI

- Open a terminal/shell/command prompt and change to the
labstreaminglayer directory (:command:`cmake-gui -S . -B build`)
- Do an initial :guilabel:`Configure`.
Agree to create the directory if asked.
- Select your compiler and click Finish.
- Use the interface to enable building of the Apps you want to use.
- If necessary, change options or add options/paths (``Add Entry``).
- Use the interface to set or add options/paths (:guilabel:`Add Entry`).

- :ref:`Qt5` if the guessed path is not right
- :ref:`Boost` if the default was not correct
- A path where redistributable binaries get copied
(``CMAKE_INSTALL_PREFIX``)
- Build type (``CMAKE_BUILD_TYPE``, either ``Release`` or
``Debug``). You can change this in Visual Studio later.
- Click on ``Configure`` again to confirm changes.
- Click on :guilabel:`Configure` again to confirm changes.

- Click on ``Generate`` to create the build files / Visual Studio
- Click on :guilabel:`Generate` to create the build files / Visual Studio
Solution file

- Option 2 - Using commandline.

- Open a Terminal window or, on Windows, a ‘Developer Command Prompt
for VS2017’ (or 2019, as needed)
- Run cmake with appropriate `commandline options <#common-cmake-options>`__.

- Option 3 - Visual Studio 2017 or later

- Open the ``CMakeLists.txt`` file in Visual Studio
(``File``->``Open``->``CMake``)
- Change CMake settings via ``CMake``->``Change CMake Settings``

- See `Common Cmake Settings <#common-cmake-options>`__ below

- Change the selected project from the drop-down menu (x64-Debug,
x64-Release). This will trigger a CMake re-configure with the new
variables.

1. Build the project

- If in MSVC using cmake to generate project files

- Still in cmake-gui, Click ``Open Project``, or if not still in
cmake-gui, double click on the created build/LabStreamingLayer.sln
- Change the target to Release.
- In the solution explorer, right click on INSTALL and click build.

2. Build the project
- If using command line

- Start the build process
(``cmake --build . --config Release --target install``\ `\* <#regarding-the-install-target>`__)
(:command:`cmake --build . --config Release --target install`
(see also :ref:`cmakeinstalltarget`)

- If using Visual Studio 2017 built-in CMake utilities

- Use the CMake menu > Install > LabStreamingLayer

This will create a distribution tree in the folder specified by
``CMAKE_INSTALL_PREFIX``\ `\* <#regarding-the-install-target>`__ similar
to this:
:ref:`CMAKE_INSTALL_PREFIX <cmakeinstalltarget>` similar to this:

‘installed’ directory tree
~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -208,20 +191,22 @@ to this:
└── lslboost.lib
On Unix systems (Linux+OS X) the executable’s library path is changed to
include ``../LSL/lib/`` and the executable folder (``./``) so common
include :file:`../LSL/lib/` and the executable folder (:file:`./`) so common
libraries (Qt, Boost) can be distributed in a single library directory
or put in the same folder. On Windows, the library is copied to (and
searched in) the executable folder.
or put in the same folder.
On Windows, the library is copied to (and searched in) the executable folder.

The resulting folder ``LSL`` contains three subfolders:
The resulting folder :file:`LSL` contains three subfolders:

- ``cmake`` contains the exported build configuration
(``LSLConfig.cmake``) that can be used to import the library in `out
- :file:`cmake` contains the exported build configuration
(:file:`LSLConfig.cmake`) that can be used to import the library in `out
of tree builds <#out-of-tree-builds>`__.
- ``include`` contains the include headers for C (``lsl_c.h``) and C++
(``lsl_cpp.h``) programs.
- ``lib`` contains the library files. To run a program, you need the
``liblslXY.dll`` (Windows) or ``.so`` (Linux) or ``.dylib`` (MacOS).
- :file:`include` contains the include headers for C (:file:`lsl_c.h`) and C++
(:file:`lsl_cpp.h`) programs.
- :file:`lib` contains the library files. To run a program, you need the
:file:`liblslXY.dll` (Windows) or :file:`.so` (Linux) or :file:`.dylib` (MacOS).

.. _cmakeinstalltarget:

Regarding the ``install`` target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
134 changes: 56 additions & 78 deletions docs/dev/build_env.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,32 +3,37 @@
LSL build environment
=====================

liblsl and most apps use `CMake <#CMake>`__ and C++.
liblsl and most apps use :ref:`buildenvcmake` and C++.

Recommended compiler toolchain
------------------------------

Download a toolchain.
The following platforms are the primary test targets for liblsl:

- Ubuntu Linux 16.04, 18.04

- Clang 3.5
- GCC 6.2

- MacOS Sierra, High Sierra

- XCode 9.3

- Windows 7

- Visual Studio 2008

- Windows 7, Windows 10

- `Visual Studio 2019 <https://visualstudio.com/downloads>`_.
To get a minimal installation, copy this block into a file and use “Import
configuration” in the installer:
Download the newest toolchain you can get.

The following platforms are the supported targets for liblsl.
Most apps require newer compilers.

========================= ====== ===========
OS / Compiler Supported Versions
------------------------- ------------------
Name Min Max
========================= ====== ===========
Windows XP 10 (1909)
Visual C++ 2008 2019 (16.3)
OS X 10.9 10.14 ?
XCode 9.3 ?
Ubuntu 16.04 19.10
CentOS 5 ?
Clang 3.5 9.0.0
g++ 6.2 9.0
Alpine Linux <3.6 3.10
:ref:`buildenvcmake` 3.12 3.15
========================= ====== ===========

To get a minimal Visual Studio installation, copy this block into a file and
use “Import configuration” in the
`Visual Studio 2019 <https://visualstudio.com/downloads>`_
installer:

::

Expand All @@ -42,21 +47,20 @@ The following platforms are the primary test targets for liblsl:

Some apps may have higher requirements while liblsl works on very old
(e.g. Windows XP) and tiny (e.g. Raspberry Pi, some microcontrollers,
Android) systems. See the respective build documentation for more
information.
Android) systems.

.. _buildenv_cmake:
.. _buildenvcmake:

`CMake <https://cmake.org/download/>`_
--------------------------------------

The oldest supported version is CMake 3.12.

- *Windows*: choose the installer (.msi extension).
- *Windows*: either let Visual Studio install CMake or
download the installer (.msi extension).
During installation, check the box to add it to the path (for all users).
- Debian / Ubuntu: ``apt install cmake`` or ``python -m pip install cmake``
- Fedora: ``yum install cmake``
- OS X: ``brew install cmake``
- Debian / Ubuntu: :command:`apt install cmake` or
:command:`python -m pip install cmake`
- Fedora: :command:`yum install cmake`
- OS X: :command:`brew install cmake`

.. _Boost:

Expand All @@ -67,12 +71,17 @@ The oldest supported version is CMake 3.12.
includes Boost, so you only need it to build some apps.

Boost libraries come in two flavors: header-only and compiled libraries.
For the header-only libraries you can download the source archive and
point CMake to it (``-DBOOST_ROOT=path/to/boost``).

For the header-only libraries you can download the source archive unpack it to
your local disk.

For compiled libraries, you either have to compile it yourself (not recommended)
or download precompiled binaries *that have to match your compiler version
and processor architecture!*
For newer apps, you should use the C++11 standard library (e.g. for threads and
regular expressions).

Afterwards, point CMake to it (:samp:`-D{BOOST_ROOT}=path/to/boost`).

Each apps build instructions should tell you exactly which boost
libraries you need.
Expand All @@ -88,43 +97,14 @@ libraries you need.
- Debian / Ubuntu Linux: install the ``libboost-all-dev`` package
- OS X: install Boost via `Homebrew <https://brew.sh/>`__

If your Boost version is so new that cmake can’t find it.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

CMake has built in instructions on how to find modules and their
dependencies within the boost library. These instructions are tied to
specific versions of boost. If a new version of boost is released, then
older cmake will not have instructions on how to load its modules. The
easiest way to fix this is to use the last version of boost that is
compatible with the most recent version of cmake. At the time of this
writing, CMake 3.10 supported up to Boost 1.65.1

MacOS
^^^^^

If you are using MacOS and homebrew, then install an old version of
boost with (e.g.) ``brew install boost@1.60``. Then the cmake argment
will be ``-DBOOST_ROOT=$(brew --prefix boost@1.60)``. Try
``brew search boost`` to see which older versions of boost are
available.

Using the latest version of boost anyway
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you absolutely need the latest version of boost then the next easiest
way to fix this for this project and other projects, is to edit the file
that tells cmake about boost versions:
``C:\Program Files\CMake\share\cmake-3.10\Modules\FindBoost.cmake``.
Scroll down to the section that checks boost versions (search for
``if(NOT Boost_VERSION VERSION_LESS``). In the last version check check
in this section, the one with ``set(_Boost_IMPORTED_TARGETS FALSE)``,
modify the ``if(NOT Boost_VERSION VERSION_LESS <value>)`` to be
something greater than your boost version. e.g., If your boost version
is 1.66 then make it ``106700``.

NOTE: This has worked for me in the past but IS NOT working for Boost
1.66. Something must have changed.

boost with (e.g.) :command:`brew install boost@1.60`.
Then the cmake argument will be
:samp:`-D{BOOST_ROOT}=$(brew --prefix boost@1.60)`.
Try :command:`brew search boost` to see which older versions of boost are available.

.. _Qt5:

Expand All @@ -134,18 +114,16 @@ NOTE: This has worked for me in the past but IS NOT working for Boost
For compatibility with Ubuntu 16.04, Qt5.5 is the oldest supported
version.

Qt5 is the recommended toolkit to create graphical user interfaces. To
build apps using Qt, install it and tell CMake where to find it, either
by adding the compiler specific base path to the PATH
(``set PATH=C:\Qt\<version>\<compiler_arch>;%PATH%`` on the same command
line you call cmake from) or add the path to the Qt5 CMake configuration
to the cmake parameters
(``-DQt5_DIR=C:/path_to/Qt/<version>/<compiler_arch>/lib/cmake/Qt5/``)
Qt5 is the recommended toolkit to create graphical user interfaces.
To build apps using Qt, install it and if CMake doesn't find it automatically
tell it where to find it, either by adding the compiler specific base path to
the :envvar:`PATH`
(:samp:`set {PATH}=C:\Qt\<version>\<compiler_arch>;%PATH%`
on the same command line you call cmake from) or add the path to the Qt5 CMake
configuration to the cmake parameters
(:samp:`-D{Qt5_DIR}=C:/path_to/Qt/<version>/<compiler_arch>/lib/cmake/Qt5/`).

- Windows: use the
`installer <http://download.qt.io/official_releases/online_installers/qt-unified-windows-x86-online.exe>`__
- Debian / Ubuntu Linux: ``apt install qt5-default``
- OS X: ``brew install qt``

- it may be necessary to run the following from the project root:
``sudo bash ./fix_mac.sh``
- Debian / Ubuntu Linux: :command:`apt install qt5-default`
- OS X: :command:`brew install qt`

0 comments on commit f3166f3

Please sign in to comment.