Skip to content

Commit e84dec5

Browse files
cboulaycboulay
committed
Docs update
1 parent ae2cb4b commit e84dec5

File tree

5 files changed

+395
-6
lines changed

5 files changed

+395
-6
lines changed

‎docs/dev/LSL_INSTALL_ROOT.rst‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
:orphan:
2+
3+
.. role:: cmd(code)
4+
:language: bash
5+
6+
``LSL_INSTALL_ROOT``
7+
====================
8+
9+
To import the LSL library in a separate CMake build, you need to set the
10+
the **absolute path** to the `‘installed’ LSL
11+
directory <#install-directory-tree>`__ in the ``LSL_INSTALL_ROOT``
12+
variable (e.g. :cmd:`-DLSL_INSTALL_ROOT=C:/LSL/build/install/`) or add the
13+
**absolute path** to the\ ``LSL/cmake`` subfolder of the `‘installed’
14+
LSL directory <#install-directory-tree>`__ to your ``CMAKE_PREFIX_PATH``
15+
(:cmd:`list(APPEND CMAKE_MODULE_PATH "C:/path/to/LSL/build/install/cmake/")`).
16+
17+
CMake looks for the file
18+
``${LSL_INSTALL_ROOT}/LSL/share/LSL/LSLConfig.cmake``, so make sure your
19+
``LSL_INSTALL_ROOT`` has the files listed in `the previous
20+
section <#installed-directory-tree>`__.
21+
22+
By default, apps should look in ``../../LSL/liblsl/build/install`` so if
23+
you have a ``build`` folder in each submodule (``LSL/liblsl/build``,
24+
``Apps/Examples/build`` etc.) and installed ``liblsl`` first, CMake
25+
automatically finds liblsl.

‎docs/dev/build.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
Building LSL
77
============
88

9-
This manual describes the process of building liblsl and applications
9+
This manual describes the process of building liblsl
1010
from source for Windows, Mac OS X, and Linux. Since liblsl is
1111
cross-platform (it is written in standard C++ and uses some boost
1212
libraries), this process should be pretty straightforward. The following

‎docs/dev/build_env.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ Android) systems.
5353

5454
.. _buildenvcmake:
5555

56+
Note: MacOS users are expected to have `homebrew <https://brew.sh/>`__ installed.
57+
5658
`CMake <https://cmake.org/download/>`_
5759
--------------------------------------
5860

@@ -85,7 +87,7 @@ regular expressions).
8587

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

88-
Each apps build instructions should tell you exactly which boost
90+
Each app's build instructions should tell you exactly which boost
8991
libraries you need.
9092

9193
- Windows: install the `precompiled

‎docs/dev/build_full_tree.rst‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
:orphan:
2+
3+
.. role:: cmd(code)
4+
:language: bash
5+
6+
Building LabStreamingLayer Full Tree
7+
====================================
8+
9+
This guide is intended only for advanced developers who intend to work
10+
on multiple projects and/or the core library simultaneously.
11+
12+
Project Structure
13+
-----------------
14+
15+
This main `labstreaminglayer repository <https://github.com/sccn/labstreaminglayer>`__
16+
contains only the general project structure and references (“`git
17+
submodules <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`__”) to
18+
the liblsl C/C++ library
19+
(`LSL/liblsl <https://github.com/labstreaminglayer/liblsl/>`__),
20+
various language bindings (e.g.
21+
`LSL/liblsl-Python <https://github.com/labstreaminglayer/liblsl-Python>`__),
22+
the Apps to stream data from several types of devices
23+
including a template examples, and the
24+
`LabRecorder <https://github.com/labstreaminglayer/App-LabRecorder>`__.:
25+
26+
.. code:: bash
27+
28+
labstreaminglayer
29+
├── Apps
30+
│ ├── AMTI ForcePlate
31+
│ ├── LabRecorder
32+
│ ├── [several other apps]
33+
│ └── Wiimote
34+
└── LSL
35+
├── liblsl
36+
│ ├── include
37+
│ ├── lslboost
38+
│ ├── project
39+
│ ├── src
40+
│ └── testing
41+
├── liblsl-Matlab
42+
├── liblsl-Python
43+
└── liblsl-Java
44+
45+
To get the project source code using Git, see :doc:`full_tree`.
46+
47+
48+
Dependencies (optional)
49+
-----------------------
50+
51+
The core ``liblsl`` does not have any external dependencies.
52+
53+
Different language bindings or apps have their own dependencies so
54+
please consult those projects’ build instructions.
55+
56+
Many apps depend on :ref:`Qt5`, :ref:`boost`, and many use :ref:`CMake` build system.
57+
Follow the instructions to set up your :doc:`build_env`.
58+
59+
Build instructions
60+
------------------
61+
62+
In tree builds (recommended)
63+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64+
65+
1. Create the build directory
66+
67+
- You can use a GUI file manager to do this part or you can do it by
68+
command line as below.
69+
- Open a Terminal/shell/Command Prompt and change to the
70+
labstreaminglayer directory.
71+
72+
- If the build directory is already there then delete it
73+
74+
- Windows: :cmd:`rmdir /S build`; Others: :cmd:`rm -Rf build`
75+
76+
1. Configure the project using :ref:`buildenvcmake`
77+
78+
- Option 1 - Visual Studio 2017 or later
79+
80+
- Open the :file:`CMakeLists.txt` file in Visual Studio
81+
(:guilabel:`File->Open->CMake`)
82+
- Change CMake settings via :guilabel:`CMake->Change CMake Settings`
83+
84+
- See `Common Cmake Settings <#common-cmake-options>`__ below
85+
86+
- Change the selected project from the drop-down menu (:guilabel:`x64-Debug`,
87+
:guilabel:`x64-Release`).
88+
This will trigger a CMake re-configure with the new variables.
89+
90+
- Option 2 - Using commandline.
91+
92+
- Open a Terminal window or, on Windows, a ‘Developer Command Prompt
93+
for VS2017’ (or 2019, as needed)
94+
- Run cmake with appropriate `commandline options <#common-cmake-options>`__.
95+
96+
- Option 3 - Using the GUI
97+
98+
- Open a terminal/shell/command prompt and change to the
99+
labstreaminglayer directory (:cmd:`cmake-gui -S . -B build`)
100+
- Do an initial :guilabel:`Configure`.
101+
Agree to create the directory if asked.
102+
- Select your compiler and click Finish.
103+
- Use the interface to set or add options/paths (:guilabel:`Add Entry`).
104+
105+
- :ref:`Qt5` if the guessed path is not right
106+
- :ref:`Boost` if the default was not correct
107+
- A path where redistributable binaries get copied
108+
(``CMAKE_INSTALL_PREFIX``)
109+
- Build type (``CMAKE_BUILD_TYPE``, either ``Release`` or
110+
``Debug``). You can change this in Visual Studio later.
111+
- Click on :guilabel:`Configure` again to confirm changes.
112+
113+
- Click on :guilabel:`Generate` to create the build files / Visual Studio
114+
Solution file
115+
116+
2. Build the project
117+
- If using command line
118+
119+
- Start the build process
120+
(:cmd:`cmake --build . --config Release --target install`
121+
(see also :ref:`cmakeinstalltarget`)
122+
123+
- If using Visual Studio 2017 built-in CMake utilities
124+
125+
- Use the CMake menu > Install > LabStreamingLayer
126+
127+
This will create a distribution tree in the folder specified by
128+
:ref:`CMAKE_INSTALL_PREFIX <cmakeinstalltarget>` similar to this:
129+
130+
‘installed’ directory tree
131+
~~~~~~~~~~~~~~~~~~~~~~~~~~
132+
133+
.. code:: bash
134+
135+
├── AppX
136+
│ ├── AppX.exe
137+
│ ├── liblsl64.dll
138+
│ ├── Qt5Xml.dll
139+
│ ├── Qt5Gui.dll
140+
│ └── AppX_configuration.ini
141+
├── AppY
142+
│ ├── AppY.exe
143+
│ ├── AppY_conf.exe
144+
│ ├── liblsl64.dll
145+
│ └── example.png
146+
├── examples
147+
│ ├── CppReceive.exe
148+
│ ├── CppSendRand.exe
149+
│ ├── SendDataC.exe
150+
│ ├── liblsl64.dll
151+
└── LSL
152+
├── share
153+
│ ├── LSL
154+
│ │ ├── LSLCMake.cmake
155+
│ │ ├── LSLConfig.cmake
156+
│ │ └── LSLCMake.cmake
157+
├── include
158+
│ ├── lsl_c.h
159+
│ └── lsl_cpp.h
160+
└── lib
161+
├── liblsl64.dll
162+
├── liblsl64.lib
163+
└── lslboost.lib
164+
165+
On Unix systems (Linux+OS X) the executable’s library path is changed to
166+
include :file:`../LSL/lib/` and the executable folder (:file:`./`) so common
167+
libraries (Qt, Boost) can be distributed in a single library directory
168+
or put in the same folder.
169+
On Windows, the library is copied to (and searched in) the executable folder.
170+
171+
The resulting folder :file:`LSL` contains three subfolders:
172+
173+
- :file:`cmake` contains the exported build configuration
174+
(:file:`LSLConfig.cmake`) that can be used to import the library in `out
175+
of tree builds <#out-of-tree-builds>`__.
176+
- :file:`include` contains the include headers for C (:file:`lsl_c.h`) and C++
177+
(:file:`lsl_cpp.h`) programs.
178+
- :file:`lib` contains the library files. To run a program, you need the
179+
:file:`liblslXY.dll` (Windows) or :file:`.so` (Linux) or :file:`.dylib` (MacOS).
180+
181+
.. _cmakeinstalltarget:
182+
183+
Regarding the ``install`` target
184+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
185+
186+
CMake places built binary files as well as build sideproducts in a build
187+
tree that should be separate from the source directory. To copy only the
188+
needed files (and additional library files they depend on) to a folder
189+
you can share with colleagues or onto another PC, you need to ‘install’
190+
them. This doesn’t mean ‘installing’ them in a traditional sense (i.e.,
191+
with Windows installers or package managers on Linux / OS X), but only
192+
copying them to a separate folder and fixing some hardcoded paths in the
193+
binaries.
194+
195+
Common CMake Options
196+
--------------------
197+
198+
The cmake build system has many options. If you are using the CMake GUI
199+
then these options will be presented to you before you generate the
200+
project/makefiles.
201+
202+
If you are using the commandline then default options will generate
203+
makefiles for liblsl only. If you want to use the commandline to
204+
generate a project for an IDE, or to generate a project that builds LSL
205+
Apps, then you will have to provide some optional arguments to the cmake
206+
command.
207+
208+
- `Generator <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#cmake-generators>`__:
209+
``-G <generator name>``.
210+
- Apps: ``-DLSLAPPS_<AppName>=ON``.
211+
212+
- ``-DLSLAPPS_LabRecorder=ON``
213+
- ``-DLSLAPPS_XDFBrowser=ON``
214+
- ``-DLSLAPPS_OpenVR=ON``
215+
- TODO: Each app should have its cmake option easily accessible in
216+
its readme.
217+
- TODO: Each app should have its own additional options specified in
218+
its readme.
219+
220+
- App dependencies (required by some apps). See :ref:`lslbuildenv` for more info.
221+
222+
- ``-DQt5_DIR=<path/to/qt/binaries>/lib/cmake/Qt5``
223+
- ``-DBOOST_ROOT=<path/to/boost>``
224+
225+
- liblsl comes with its own boost used by itself, but it is not
226+
uncommon for apps to require ‘normal’ boost.
227+
228+
- Install root (see :doc:`LSL_INSTALL_ROOT`)
229+
230+
- Not necessary for in-tree builds.
231+
232+
Here are some example cmake commands:
233+
234+
- Chad’s Windows build:
235+
``cmake .. -G "Visual Studio 14 2015 Win64" -DLSL_LSLBOOST_PATH="lslboost" -DQt5_DIR=C:\Qt\5.11.1\msvc2015_64\lib\cmake\Qt5 -DBOOST_ROOT=C:\local\boost_1_67_0 -DLSLAPPS_LabRecorder=ON -DLSLAPPS_XDFBrowser=ON -DLSLAPPS_OpenVR=ON``
236+
- Chad’s Mac build:
237+
``cmake .. -DLSL_LSLBOOST_PATH="lslboost" -DLSLAPPS_Examples=ON -DLSLAPPS_LabRecorder=ON -DLSLAPPS_Benchmarks=ON -DLSLAPPS_XDFBrowser=ON -DQt5_DIR=$(brew --prefix qt)/lib/cmake/Qt5/``
238+
239+
Configure CMake options in VS 2017 / VS 2019
240+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
241+
242+
If you are using Visual Studio 2017’s built-in CMake Tools then the
243+
default options would have been used to configure the project. To set
244+
any variables you have to edit a file. Use the CMake menu > Change CMake
245+
Settings > LabStreamingLayer. This will open a json file. For each
246+
configuration of interest, add a ‘variables’ entry with a list of
247+
key/value pairs. For example, under ``"name": "x64-Release",`` and
248+
immediately after ``"ctestCommandArgs": ""`` add the following:
249+
250+
::
251+
252+
,
253+
"variables": [
254+
{
255+
"name": "Qt5_DIR",
256+
"value": "C:\\Qt\\5.11.1\\msvc2015_64\\lib\\cmake\\Qt5 "
257+
},
258+
{
259+
"name": "BOOST_ROOT",
260+
"value": "C:\\local\\boost_1_67_0"
261+
},
262+
{
263+
"name": "LSLAPPS_Examples",
264+
"value": "ON"
265+
},
266+
{
267+
"name": "LSLAPPS_LabRecorder",
268+
"value": "ON"
269+
},
270+
{
271+
"name": "LSLAPPS_Benchmarks",
272+
"value": "ON"
273+
},
274+
{
275+
"name": "LSLAPPS_XDFBrowser",
276+
"value": "ON"
277+
}
278+
]

0 commit comments

Comments
 (0)