Skip to content

Commit 0697d59

Browse files
cboulaycboulay
committed
docs: Added generic app_build instructions.
1 parent 5dffac8 commit 0697d59

File tree

2 files changed

+199
-0
lines changed

2 files changed

+199
-0
lines changed

‎docs/dev/app_build.rst‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
:orphan:
2+
3+
.. role:: cmd(code)
4+
:language: bash
5+
6+
Building LSL Apps
7+
=================
8+
9+
Advanced developers may wish to use :doc:`build_full_tree`.
10+
11+
The instructions below are recommended for most users.
12+
Most LabStreamingLayer applications have a similar structure
13+
and use similar build tools. These instructions are general
14+
and should work for most applications. Always be sure to read
15+
the specific application build instructions first.
16+
17+
1. Make sure you have a working :doc:`build_env`.
18+
19+
2. Get the source code for your application.
20+
- If you are creating a new C++ application to add support for a device,
21+
generate a project from the `AppTemplate_cpp_qt <https://github.com/labstreaminglayer/AppTemplate_cpp_qt/generate>`__
22+
- git clone the application.
23+
24+
3. Create the build directory
25+
26+
- You can use a GUI file manager to do this part or you can do it by
27+
command line as below.
28+
- Open a terminal/shell/command prompt and change to the
29+
repository directory.
30+
31+
- If the build directory is already there then delete it
32+
33+
- Windows: :cmd:`rmdir /S build`; Others: :cmd:`rm -Rf build`
34+
35+
4. Configure the project using :ref:`buildenvcmake`
36+
37+
- Option 1 - Visual Studio 2017 or later
38+
39+
- Open the :file:`CMakeLists.txt` file in Visual Studio
40+
(:guilabel:`File->Open->CMake`)
41+
- Change CMake settings via :guilabel:`CMake->Change CMake Settings`
42+
43+
- See `Common CMake Settings <#common-cmake-options>`__ below
44+
45+
- Change the selected project from the drop-down menu (:guilabel:`x64-Debug`,
46+
:guilabel:`x64-Release`).
47+
This will trigger a CMake re-configure with the new variables.
48+
49+
- Option 2 - Using commandline.
50+
51+
- Open a Terminal window or, on Windows, a ``x64 Native Tools Command Prompt
52+
for VS2017`` (or VS2019, as needed).
53+
- Run cmake with appropriate `commandline options <#common-cmake-options>`__.
54+
55+
- Option 3 - Using the GUI
56+
57+
- Open a terminal/shell/command prompt and change to the
58+
repository directory (:cmd:`cmake-gui -S . -B build`)
59+
- Do an initial :guilabel:`Configure`.
60+
Agree to create the directory if asked.
61+
- Select your compiler and click Finish.
62+
- Use the interface to set or add options/paths (:guilabel:`Add Entry`).
63+
64+
- :ref:`Qt5` if the guessed path is not right
65+
- :ref:`Boost` if the default was not correct
66+
- A path where redistributable binaries get copied
67+
(``CMAKE_INSTALL_PREFIX``)
68+
- Build type (``CMAKE_BUILD_TYPE``, either ``Release`` or
69+
``Debug``). You can change this in Visual Studio later.
70+
- Click on :guilabel:`Configure` again to confirm changes.
71+
72+
- Click on :guilabel:`Generate` to create the build files / Visual Studio
73+
Solution file
74+
75+
5. Build the project
76+
- If using command line
77+
78+
- Start the build process
79+
(:cmd:`cmake --build . --config Release --target install`
80+
(see also :ref:`cmakeinstalltarget`)
81+
82+
- If using Visual Studio >=2017 built-in CMake utilities
83+
84+
- Use the CMake menu > Install > ApplicationName
85+
86+
This will create a distribution tree in the folder specified by
87+
:ref:`CMAKE_INSTALL_PREFIX <cmakeinstalltarget>` similar to this:
88+
89+
‘installed’ directory tree
90+
~~~~~~~~~~~~~~~~~~~~~~~~~~
91+
92+
.. code:: bash
93+
94+
├── AppX
95+
│ ├── AppX.exe
96+
│ ├── liblsl64.dll
97+
│ ├── Qt5Xml.dll
98+
│ ├── Qt5Gui.dll
99+
│ ├── VendorDevice.dll
100+
│ └── AppX_configuration.ini
101+
└── LSL
102+
├── share
103+
│ ├── LSL
104+
│ │ ├── LSLCMake.cmake
105+
│ │ ├── LSLConfig.cmake
106+
│ │ └── LSLCMake.cmake
107+
├── include
108+
│ ├── lsl_c.h
109+
│ └── lsl_cpp.h
110+
└── lib
111+
├── liblsl64.dll
112+
├── liblsl64.lib
113+
└── lslboost.lib
114+
115+
On Unix systems (Linux+OS X) the executable’s library path is changed to
116+
include :file:`../LSL/lib/` and the executable folder (:file:`./`) so common
117+
libraries (Qt, Boost) can be distributed in a single library directory
118+
or put in the same folder.
119+
On Windows, the library is copied to (and searched in) the executable folder.
120+
121+
122+
.. _cmakeinstalltarget:
123+
124+
Regarding the ``install`` target
125+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126+
127+
CMake places built binary files as well as build sideproducts in a build
128+
tree that should be separate from the source directory. To copy only the
129+
needed files (and additional library files they depend on) to a folder
130+
you can share with colleagues or onto another PC, you need to ‘install’
131+
them. This doesn’t mean ‘installing’ them in a traditional sense (i.e.,
132+
with Windows installers or package managers on Linux / OS X), but only
133+
copying them to a separate folder and fixing some hardcoded paths in the
134+
binaries.
135+
136+
137+
Common CMake Options
138+
--------------------
139+
140+
The cmake build system has many options. If you are using the CMake GUI
141+
then these options will be presented to you before you generate the
142+
project/makefiles.
143+
144+
If you are using the commandline then default options will generate
145+
makefiles for liblsl only. If you want to use the commandline to
146+
generate a project for an IDE, or to generate a project that builds LSL
147+
Apps, then you will have to provide some optional arguments to the cmake
148+
command.
149+
150+
- `Generator <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#cmake-generators>`__:
151+
``-G <generator name>``.
152+
153+
- App dependencies (required by some apps). See :ref:`lslbuildenv` for more info.
154+
155+
- ``-DVendor_ROOT=<path/to/vendor/sdk>``
156+
- ``-DQt5_DIR=<path/to/qt/binaries>/lib/cmake/Qt5``
157+
- ``-DBOOST_ROOT=<path/to/boost>``
158+
159+
- Location of liblsl (see :doc:`LSL_INSTALL_ROOT`)
160+
161+
- Please check the application's README and/or BUILD document for more options.
162+
163+
164+
Configure CMake options in VS 2017 / VS 2019
165+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166+
167+
If you are using Visual Studio 2017’s built-in CMake Tools then the
168+
default options would have been used to configure the project. To set
169+
any variables you have to edit a file. Use the CMake menu > Change CMake
170+
Settings > ApplicationName. This will open a json file. For each
171+
configuration, add a ‘variables’ entry with a list of
172+
key/value pairs. For example, under ``"name": "x64-Release",`` and
173+
immediately after ``"ctestCommandArgs": ""`` add the following:
174+
175+
::
176+
177+
,
178+
"variables": [
179+
{
180+
"name": "Qt5_DIR",
181+
"value": "C:\\Qt\\5.11.1\\msvc2015_64\\lib\\cmake\\Qt5 "
182+
},
183+
{
184+
"name": "BOOST_ROOT",
185+
"value": "C:\\local\\boost_1_67_0"
186+
},
187+
{
188+
"name": "Vendor_ROOT",
189+
"value": "C:\\path\\to\\vendor\\sdk"
190+
},
191+
{
192+
"name": "LSL_INSTALL_ROOT",
193+
"value": "C:\\path\\to\\liblsl\\install"
194+
}
195+
]

‎docs/dev/app_dev.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ Read the annotated CMakeLists.txt file and the annotated source files for an ove
2424

2525
And of course many of the applications in the `labstreaminglayer submodules <https://github.com/sccn/labstreaminglayer/tree/master/Apps>`_ are good examples of C++ applications, most of which use Qt.
2626

27+
You will also need to build your C++ application. Most LabStreamingLayer applications
28+
will follow similar :doc:`app_build` instructions. Please be sure to read the application's
29+
README (and optionally BUILD) before building.
30+
2731
Python apps
2832
-----------
2933
Python is another great language for app development, as long as your target audience has Python and the required libraries installed.

0 commit comments

Comments
 (0)