|
150
|
1 Building
|
|
|
2 ========
|
|
|
3
|
|
|
4 .. contents::
|
|
|
5 :local:
|
|
|
6
|
|
|
7 Getting the Sources
|
|
|
8 -------------------
|
|
|
9
|
|
|
10 Please refer to the `LLVM Getting Started Guide
|
|
|
11 <https://llvm.org/docs/GettingStarted.html#getting-started-with-llvm>`_ for
|
|
|
12 general instructions on how to check out the LLVM monorepo, which contains the
|
|
|
13 LLDB sources.
|
|
|
14
|
|
221
|
15 Git browser: https://github.com/llvm/llvm-project/tree/main/lldb
|
|
150
|
16
|
|
|
17 Preliminaries
|
|
|
18 -------------
|
|
|
19
|
|
|
20 LLDB relies on many of the technologies developed by the larger LLVM project.
|
|
|
21 In particular, it requires both Clang and LLVM itself in order to build. Due to
|
|
|
22 this tight integration the Getting Started guides for both of these projects
|
|
|
23 come as prerequisite reading:
|
|
|
24
|
|
|
25 * `LLVM <https://llvm.org/docs/GettingStarted.html>`_
|
|
|
26 * `Clang <http://clang.llvm.org/get_started.html>`_
|
|
|
27
|
|
|
28 The following requirements are shared on all platforms.
|
|
|
29
|
|
|
30 * `CMake <https://cmake.org>`_
|
|
|
31 * `Ninja <https://ninja-build.org>`_ (strongly recommended)
|
|
|
32
|
|
|
33 If you want to run the test suite, you'll need to build LLDB with Python
|
|
|
34 scripting support.
|
|
|
35
|
|
|
36 * `Python <http://www.python.org/>`_
|
|
221
|
37 * `SWIG <http://swig.org/>`_ 3 or later.
|
|
150
|
38
|
|
|
39 Optional Dependencies
|
|
|
40 *********************
|
|
|
41
|
|
|
42 Although the following dependencies are optional, they have a big impact on
|
|
|
43 LLDB's functionality. It is strongly encouraged to build LLDB with these
|
|
|
44 dependencies enabled.
|
|
|
45
|
|
|
46 By default they are auto-detected: if CMake can find the dependency it will be
|
|
|
47 used. It is possible to override this behavior by setting the corresponding
|
|
|
48 CMake flag to ``On`` or ``Off`` to force the dependency to be enabled or
|
|
|
49 disabled. When a dependency is set to ``On`` and can't be found it will cause a
|
|
|
50 CMake configuration error.
|
|
|
51
|
|
|
52 +-------------------+------------------------------------------------------+--------------------------+
|
|
|
53 | Feature | Description | CMake Flag |
|
|
|
54 +===================+======================================================+==========================+
|
|
|
55 | Editline | Generic line editing, history, Emacs and Vi bindings | ``LLDB_ENABLE_LIBEDIT`` |
|
|
|
56 +-------------------+------------------------------------------------------+--------------------------+
|
|
|
57 | Curses | Text user interface | ``LLDB_ENABLE_CURSES`` |
|
|
|
58 +-------------------+------------------------------------------------------+--------------------------+
|
|
|
59 | LZMA | Lossless data compression | ``LLDB_ENABLE_LZMA`` |
|
|
|
60 +-------------------+------------------------------------------------------+--------------------------+
|
|
|
61 | Libxml2 | XML | ``LLDB_ENABLE_LIBXML2`` |
|
|
|
62 +-------------------+------------------------------------------------------+--------------------------+
|
|
|
63 | Python | Python scripting | ``LLDB_ENABLE_PYTHON`` |
|
|
|
64 +-------------------+------------------------------------------------------+--------------------------+
|
|
|
65 | Lua | Lua scripting | ``LLDB_ENABLE_LUA`` |
|
|
|
66 +-------------------+------------------------------------------------------+--------------------------+
|
|
|
67
|
|
|
68 Depending on your platform and package manager, one might run any of the
|
|
|
69 commands below.
|
|
|
70
|
|
|
71 ::
|
|
|
72
|
|
|
73 > yum install libedit-devel libxml2-devel ncurses-devel python-devel swig
|
|
221
|
74 > sudo apt-get install build-essential subversion swig python3-dev libedit-dev libncurses5-dev
|
|
150
|
75 > pkg install swig python
|
|
221
|
76 > pkgin install swig python36 cmake ninja-build
|
|
150
|
77 > brew install swig cmake ninja
|
|
|
78
|
|
221
|
79 Note that there's an `incompatibility
|
|
|
80 <https://github.com/swig/swig/issues/1321>`_ between Python version 3.7 and later
|
|
|
81 and swig versions older than 4.0.0 which makes builds of LLDB using debug
|
|
|
82 versions of python unusable. This primarily affects Windows, as debug builds of
|
|
|
83 LLDB must use debug python as well.
|
|
|
84
|
|
150
|
85 Windows
|
|
|
86 *******
|
|
|
87
|
|
173
|
88 * Visual Studio 2017.
|
|
|
89 * The latest Windows SDK.
|
|
|
90 * The Active Template Library (ATL).
|
|
|
91 * `GnuWin32 <http://gnuwin32.sourceforge.net/>`_ for CoreUtils and Make.
|
|
221
|
92 * `Python 3 <https://www.python.org/downloads/windows/>`_. Make sure to (1) get
|
|
|
93 the x64 variant if that's what you're targetting and (2) install the debug
|
|
|
94 library if you want to build a debug lldb.
|
|
150
|
95 * `Python Tools for Visual Studio
|
|
|
96 <https://github.com/Microsoft/PTVS/releases>`_. If you plan to debug test
|
|
|
97 failures or even write new tests at all, PTVS is an indispensable debugging
|
|
|
98 extension to VS that enables full editing and debugging support for Python
|
|
173
|
99 (including mixed native/managed debugging).
|
|
150
|
100
|
|
|
101 The steps outlined here describes how to set up your system and install the
|
|
|
102 required dependencies such that they can be found when needed during the build
|
|
|
103 process. They only need to be performed once.
|
|
|
104
|
|
173
|
105 #. Install Visual Studio with the Windows SDK and ATL components.
|
|
150
|
106 #. Install GnuWin32, making sure ``<GnuWin32 install dir>\bin`` is added to
|
|
173
|
107 your PATH environment variable. Verify that utilities like ``dirname`` and
|
|
|
108 ``make`` are available from your terminal.
|
|
150
|
109 #. Install SWIG for Windows, making sure ``<SWIG install dir>`` is added to
|
|
173
|
110 your PATH environment variable. Verify that ``swig`` is available from your
|
|
|
111 terminal.
|
|
|
112 #. Register the Debug Interface Access DLLs with the Registry from a privileged
|
|
|
113 terminal.
|
|
|
114
|
|
|
115 ::
|
|
|
116
|
|
|
117 > regsvr32 "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\DIA SDK\bin\msdia140.dll"
|
|
|
118 > regsvr32 "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\DIA SDK\bin\amd64\msdia140.dll"
|
|
150
|
119
|
|
|
120 Any command prompt from which you build LLDB should have a valid Visual Studio
|
|
|
121 environment setup. This means you should run ``vcvarsall.bat`` or open an
|
|
|
122 appropriate Visual Studio Command Prompt corresponding to the version you wish
|
|
|
123 to use.
|
|
|
124
|
|
|
125 macOS
|
|
|
126 *****
|
|
|
127
|
|
|
128 * To use the in-tree debug server on macOS, lldb needs to be code signed. For
|
|
|
129 more information see :ref:`CodeSigning` below.
|
|
|
130 * If you are building both Clang and LLDB together, be sure to also check out
|
|
|
131 libc++, which is a required for testing on macOS.
|
|
|
132
|
|
|
133 Building LLDB with CMake
|
|
|
134 ------------------------
|
|
|
135
|
|
221
|
136 The LLVM project is migrating to a single monolithic repository for LLVM and
|
|
150
|
137 its subprojects. This is the recommended way to build LLDB. Check out the
|
|
|
138 source-tree with git:
|
|
|
139
|
|
|
140 ::
|
|
|
141
|
|
|
142 > git clone https://github.com/llvm/llvm-project.git
|
|
|
143
|
|
|
144 CMake is a cross-platform build-generator tool. CMake does not build the
|
|
|
145 project, it generates the files needed by your build tool. The recommended
|
|
|
146 build tool for LLVM is Ninja, but other generators like Xcode or Visual Studio
|
|
|
147 may be used as well. Please also read `Building LLVM with CMake
|
|
|
148 <https://llvm.org/docs/CMake.html>`_.
|
|
|
149
|
|
|
150 Regular in-tree builds
|
|
|
151 **********************
|
|
|
152
|
|
|
153 Create a new directory for your build-tree. From there run CMake and point it
|
|
|
154 to the ``llvm`` directory in the source-tree:
|
|
|
155
|
|
|
156 ::
|
|
|
157
|
|
|
158 > cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;lldb" [<cmake options>] path/to/llvm-project/llvm
|
|
|
159
|
|
|
160 We used the ``LLVM_ENABLE_PROJECTS`` option here to tell the build-system which
|
|
|
161 subprojects to build in addition to LLVM (for more options see
|
|
|
162 :ref:`CommonCMakeOptions` and :ref:`CMakeCaches`). Parts of the LLDB test suite
|
|
|
163 require ``lld``. Add it to the list in order to run all tests. Once CMake is done,
|
|
|
164 run ninja to perform the actual build. We pass ``lldb`` here as the target, so
|
|
|
165 it only builds what is necessary to run the lldb driver:
|
|
|
166
|
|
|
167 ::
|
|
|
168
|
|
|
169 > ninja lldb
|
|
|
170
|
|
|
171 Standalone builds
|
|
|
172 *****************
|
|
|
173
|
|
|
174 This is another way to build LLDB. We can use the same source-tree as we
|
|
|
175 checked out above, but now we will have multiple build-trees:
|
|
|
176
|
|
|
177 * the main build-tree for LLDB in ``/path/to/lldb-build``
|
|
|
178 * one or more provided build-trees for LLVM and Clang; for simplicity we use a
|
|
|
179 single one in ``/path/to/llvm-build``
|
|
|
180
|
|
|
181 Run CMake with ``-B`` pointing to a new directory for the provided
|
|
|
182 build-tree\ :sup:`1` and the positional argument pointing to the ``llvm``
|
|
|
183 directory in the source-tree. Note that we leave out LLDB here and only include
|
|
|
184 Clang. Then we build the ``ALL`` target with ninja:
|
|
|
185
|
|
|
186 ::
|
|
|
187
|
|
|
188 > cmake -B /path/to/llvm-build -G Ninja \
|
|
|
189 -DLLVM_ENABLE_PROJECTS=clang \
|
|
|
190 [<more cmake options>] /path/to/llvm-project/llvm
|
|
|
191 > ninja
|
|
|
192
|
|
|
193 Now run CMake a second time with ``-B`` pointing to a new directory for the
|
|
|
194 main build-tree and the positional argument pointing to the ``lldb`` directory
|
|
|
195 in the source-tree. In order to find the provided build-tree, the build system
|
|
|
196 looks for the path to its CMake modules in ``LLVM_DIR``. If you use a separate
|
|
|
197 build directory for Clang, remember to pass its module path via ``Clang_DIR``
|
|
|
198 (CMake variables are case-sensitive!):
|
|
|
199
|
|
|
200 ::
|
|
|
201
|
|
|
202 > cmake -B /path/to/lldb-build -G Ninja \
|
|
|
203 -DLLVM_DIR=/path/to/llvm-build/lib/cmake/llvm \
|
|
|
204 [<more cmake options>] /path/to/llvm-project/lldb
|
|
|
205 > ninja lldb
|
|
|
206
|
|
|
207 .. note::
|
|
|
208
|
|
|
209 #. The ``-B`` argument was undocumented for a while and is only officially
|
|
|
210 supported since `CMake version 3.14
|
|
|
211 <https://cmake.org/cmake/help/v3.14/release/3.14.html#command-line>`_
|
|
|
212
|
|
|
213 .. _CommonCMakeOptions:
|
|
|
214
|
|
|
215 Common CMake options
|
|
|
216 ********************
|
|
|
217
|
|
|
218 Following is a description of some of the most important CMake variables which
|
|
|
219 you are likely to encounter. A variable FOO is set by adding ``-DFOO=value`` to
|
|
|
220 the CMake command line.
|
|
|
221
|
|
|
222 If you want to debug the lldb that you're building -- that is, build it with
|
|
|
223 debug info enabled -- pass two additional arguments to cmake before running
|
|
|
224 ninja:
|
|
|
225
|
|
|
226 ::
|
|
|
227
|
|
|
228 > cmake -G Ninja \
|
|
|
229 -DLLDB_EXPORT_ALL_SYMBOLS=1 \
|
|
|
230 -DCMAKE_BUILD_TYPE=Debug
|
|
|
231 <path to root of llvm source tree>
|
|
|
232
|
|
|
233 If you want to run the test suite, you will need a compiler to build the test
|
|
|
234 programs. If you have Clang checked out, that will be used by default.
|
|
|
235 Alternatively, you can specify a C and C++ compiler to be used by the test
|
|
|
236 suite.
|
|
|
237
|
|
|
238 ::
|
|
|
239
|
|
|
240 > cmake -G Ninja \
|
|
|
241 -DLLDB_TEST_COMPILER=<path to C compiler> \
|
|
|
242 <path to root of llvm source tree>
|
|
|
243
|
|
|
244 It is strongly recommend to use a release build for the compiler to speed up
|
|
|
245 test execution.
|
|
|
246
|
|
|
247 Windows
|
|
|
248 ^^^^^^^
|
|
|
249
|
|
|
250 On Windows the LLDB test suite requires lld. Either add ``lld`` to
|
|
|
251 ``LLVM_ENABLE_PROJECTS`` or disable the test suite with
|
|
221
|
252 ``LLDB_INCLUDE_TESTS=OFF``.
|
|
150
|
253
|
|
|
254 Although the following CMake variables are by no means Windows specific, they
|
|
|
255 are commonly used on Windows.
|
|
|
256
|
|
|
257 * ``LLDB_TEST_DEBUG_TEST_CRASHES`` (Default=0): If set to 1, will cause Windows
|
|
|
258 to generate a crash dialog whenever lldb.exe or the python extension module
|
|
|
259 crashes while running the test suite. If set to 0, LLDB will silently crash.
|
|
|
260 Setting to 1 allows a developer to attach a JIT debugger at the time of a
|
|
|
261 crash, rather than having to reproduce a failure or use a crash dump.
|
|
|
262 * ``PYTHON_HOME`` (Required): Path to the folder where the Python distribution
|
|
|
263 is installed. For example, ``C:\Python35``.
|
|
|
264 * ``LLDB_RELOCATABLE_PYTHON`` (Default=0): When this is 0, LLDB will bind
|
|
|
265 statically to the location specified in the ``PYTHON_HOME`` CMake variable,
|
|
|
266 ignoring any value of ``PYTHONHOME`` set in the environment. This is most
|
|
|
267 useful for developers who simply want to run LLDB after they build it. If you
|
|
|
268 wish to move a build of LLDB to a different machine where Python will be in a
|
|
|
269 different location, setting ``LLDB_RELOCATABLE_PYTHON`` to 1 will cause
|
|
|
270 Python to use its default mechanism for finding the python installation at
|
|
|
271 runtime (looking for installed Pythons, or using the ``PYTHONHOME``
|
|
|
272 environment variable if it is specified).
|
|
|
273
|
|
|
274 Sample command line:
|
|
|
275
|
|
|
276 ::
|
|
|
277
|
|
|
278 > cmake -G Ninja^
|
|
|
279 -DLLDB_TEST_DEBUG_TEST_CRASHES=1^
|
|
|
280 -DPYTHON_HOME=C:\Python35^
|
|
|
281 -DLLDB_TEST_COMPILER=d:\src\llvmbuild\ninja_release\bin\clang.exe^
|
|
|
282 <path to root of llvm source tree>
|
|
|
283
|
|
|
284
|
|
|
285 Building with ninja is both faster and simpler than building with Visual Studio,
|
|
|
286 but chances are you still want to debug LLDB with an IDE. One solution is to run
|
|
|
287 cmake twice and generate the output into two different folders. One for
|
|
|
288 compiling (the ninja folder), and one for editing, browsing and debugging.
|
|
|
289
|
|
|
290 Follow the previous instructions in one directory, and generate a Visual Studio
|
|
|
291 project in another directory.
|
|
|
292
|
|
|
293 ::
|
|
|
294
|
|
|
295 > cmake -G "Visual Studio 15 2017 Win64" -Thost=x64 <cmake variables> <path to root of llvm source tree>
|
|
|
296
|
|
|
297 Then you can open the .sln file in Visual Studio, set lldb as the startup
|
|
|
298 project, and use F5 to run it. You need only edit the project settings to set
|
|
|
299 the executable and the working directory to point to binaries inside of the
|
|
|
300 ninja tree.
|
|
|
301
|
|
|
302
|
|
|
303 macOS
|
|
|
304 ^^^^^
|
|
|
305
|
|
|
306 On macOS the LLDB test suite requires libc++. Either add ``libcxx`` to
|
|
|
307 ``LLVM_ENABLE_PROJECTS`` or disable the test suite with
|
|
221
|
308 ``LLDB_INCLUDE_TESTS=OFF``. Further useful options:
|
|
150
|
309
|
|
|
310 * ``LLDB_BUILD_FRAMEWORK:BOOL``: Builds the LLDB.framework.
|
|
|
311 * ``LLDB_CODESIGN_IDENTITY:STRING``: Set the identity to use for code-signing
|
|
|
312 all executables. If not explicitly specified, only ``debugserver`` will be
|
|
|
313 code-signed with identity ``lldb_codesign`` (see :ref:`CodeSigning`).
|
|
|
314 * ``LLDB_USE_SYSTEM_DEBUGSERVER:BOOL``: Use the system's debugserver, so lldb is
|
|
|
315 functional without setting up code-signing.
|
|
|
316
|
|
|
317
|
|
|
318 .. _CMakeCaches:
|
|
|
319
|
|
|
320 CMake caches
|
|
|
321 ************
|
|
|
322
|
|
|
323 CMake caches allow to store common sets of configuration options in the form of
|
|
|
324 CMake scripts and can be useful to reproduce builds for particular use-cases
|
|
|
325 (see by analogy `usage in LLVM and Clang <https://llvm.org/docs/AdvancedBuilds.html>`_).
|
|
|
326 A cache is passed to CMake with the ``-C`` flag, following the absolute path to
|
|
|
327 the file on disk. Subsequent ``-D`` options are still allowed. Please find the
|
|
|
328 currently available caches in the `lldb/cmake/caches/
|
|
221
|
329 <https://github.com/llvm/llvm-project/tree/main/lldb/cmake/caches>`_
|
|
150
|
330 directory.
|
|
|
331
|
|
|
332 Common configurations on macOS
|
|
|
333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
334
|
|
|
335 Build, test and install a distribution of LLDB from the `monorepo
|
|
|
336 <https://github.com/llvm/llvm-project>`_ (see also `Building a Distribution of
|
|
|
337 LLVM <https://llvm.org/docs/BuildingADistribution.html>`_):
|
|
|
338
|
|
|
339 ::
|
|
|
340
|
|
|
341 > git clone https://github.com/llvm/llvm-project
|
|
|
342
|
|
|
343 > cmake -B /path/to/lldb-build -G Ninja \
|
|
|
344 -C /path/to/llvm-project/lldb/cmake/caches/Apple-lldb-macOS.cmake \
|
|
|
345 -DLLVM_ENABLE_PROJECTS="clang;libcxx;lldb" \
|
|
|
346 llvm-project/llvm
|
|
|
347
|
|
|
348 > DESTDIR=/path/to/lldb-install ninja -C /path/to/lldb-build check-lldb install-distribution
|
|
|
349
|
|
|
350 .. _CMakeGeneratedXcodeProject:
|
|
|
351
|
|
|
352 Build LLDB standalone for development with Xcode:
|
|
|
353
|
|
|
354 ::
|
|
|
355
|
|
|
356 > git clone https://github.com/llvm/llvm-project
|
|
|
357
|
|
|
358 > cmake -B /path/to/llvm-build -G Ninja \
|
|
|
359 -C /path/to/llvm-project/lldb/cmake/caches/Apple-lldb-base.cmake \
|
|
|
360 -DLLVM_ENABLE_PROJECTS="clang;libcxx" \
|
|
|
361 llvm-project/llvm
|
|
|
362 > ninja -C /path/to/llvm-build
|
|
|
363
|
|
|
364 > cmake -B /path/to/lldb-build \
|
|
|
365 -C /path/to/llvm-project/lldb/cmake/caches/Apple-lldb-Xcode.cmake \
|
|
|
366 -DLLVM_DIR=/path/to/llvm-build/lib/cmake/llvm \
|
|
|
367 llvm-project/lldb
|
|
|
368 > open lldb.xcodeproj
|
|
|
369 > cmake --build /path/to/lldb-build --target check-lldb
|
|
|
370
|
|
|
371 .. note::
|
|
|
372
|
|
|
373 The ``-B`` argument was undocumented for a while and is only officially
|
|
|
374 supported since `CMake version 3.14
|
|
|
375 <https://cmake.org/cmake/help/v3.14/release/3.14.html#command-line>`_
|
|
|
376
|
|
|
377
|
|
|
378 Building the Documentation
|
|
|
379 --------------------------
|
|
|
380
|
|
|
381 If you wish to build the optional (reference) documentation, additional
|
|
|
382 dependencies are required:
|
|
|
383
|
|
|
384 * Sphinx (for the website)
|
|
|
385 * Graphviz (for the 'dot' tool)
|
|
|
386 * doxygen (if you wish to build the C++ API reference)
|
|
|
387 * epydoc (if you wish to build the Python API reference)
|
|
|
388
|
|
|
389 To install the prerequisites for building the documentation (on Debian/Ubuntu)
|
|
|
390 do:
|
|
|
391
|
|
|
392 ::
|
|
|
393
|
|
|
394 > sudo apt-get install doxygen graphviz python3-sphinx
|
|
|
395 > sudo pip install epydoc
|
|
|
396
|
|
|
397 To build the documentation, configure with ``LLVM_ENABLE_SPHINX=ON`` and build the desired target(s).
|
|
|
398
|
|
|
399 ::
|
|
|
400
|
|
|
401 > ninja docs-lldb-html
|
|
|
402 > ninja docs-lldb-man
|
|
|
403 > ninja lldb-cpp-doc
|
|
|
404 > ninja lldb-python-doc
|
|
|
405
|
|
|
406 Cross-compiling LLDB
|
|
|
407 --------------------
|
|
|
408
|
|
|
409 In order to debug remote targets running different architectures than your
|
|
|
410 host, you will need to compile LLDB (or at least the server component) for the
|
|
|
411 target. While the easiest solution is to just compile it locally on the target,
|
|
|
412 this is often not feasible, and in these cases you will need to cross-compile
|
|
|
413 LLDB on your host.
|
|
|
414
|
|
|
415 Cross-compilation is often a daunting task and has a lot of quirks which depend
|
|
|
416 on the exact host and target architectures, so it is not possible to give a
|
|
|
417 universal guide which will work on all platforms. However, here we try to
|
|
|
418 provide an overview of the cross-compilation process along with the main things
|
|
|
419 you should look out for.
|
|
|
420
|
|
|
421 First, you will need a working toolchain which is capable of producing binaries
|
|
|
422 for the target architecture. Since you already have a checkout of clang and
|
|
|
423 lldb, you can compile a host version of clang in a separate folder and use
|
|
|
424 that. Alternatively you can use system clang or even cross-gcc if your
|
|
|
425 distribution provides such packages (e.g., ``g++-aarch64-linux-gnu`` on
|
|
|
426 Ubuntu).
|
|
|
427
|
|
|
428 Next, you will need a copy of the required target headers and libraries on your
|
|
|
429 host. The libraries can be usually obtained by copying from the target machine,
|
|
|
430 however the headers are often not found there, especially in case of embedded
|
|
|
431 platforms. In this case, you will need to obtain them from another source,
|
|
|
432 either a cross-package if one is available, or cross-compiling the respective
|
|
|
433 library from source. Fortunately the list of LLDB dependencies is not big and
|
|
|
434 if you are only interested in the server component, you can reduce this even
|
|
|
435 further by passing the appropriate cmake options, such as:
|
|
|
436
|
|
|
437 ::
|
|
|
438
|
|
|
439 -DLLDB_ENABLE_PYTHON=0
|
|
|
440 -DLLDB_ENABLE_LIBEDIT=0
|
|
|
441 -DLLDB_ENABLE_CURSES=0
|
|
|
442 -DLLVM_ENABLE_TERMINFO=0
|
|
|
443
|
|
|
444 In this case you, will often not need anything other than the standard C and
|
|
|
445 C++ libraries.
|
|
|
446
|
|
|
447 Once all of the dependencies are in place, it's just a matter of configuring
|
|
|
448 the build system with the locations and arguments of all the necessary tools.
|
|
|
449 The most important cmake options here are:
|
|
|
450
|
|
|
451 * ``CMAKE_CROSSCOMPILING`` : Set to 1 to enable cross-compilation.
|
|
|
452 * ``CMAKE_LIBRARY_ARCHITECTURE`` : Affects the cmake search path when looking
|
|
|
453 for libraries. You may need to set this to your architecture triple if you do
|
|
|
454 not specify all your include and library paths explicitly.
|
|
|
455 * ``CMAKE_C_COMPILER``, ``CMAKE_CXX_COMPILER`` : C and C++ compilers for the
|
|
|
456 target architecture
|
|
|
457 * ``CMAKE_C_FLAGS``, ``CMAKE_CXX_FLAGS`` : The flags for the C and C++ target
|
|
|
458 compilers. You may need to specify the exact target cpu and abi besides the
|
|
|
459 include paths for the target headers.
|
|
|
460 * ``CMAKE_EXE_LINKER_FLAGS`` : The flags to be passed to the linker. Usually
|
|
|
461 just a list of library search paths referencing the target libraries.
|
|
|
462 * ``LLVM_TABLEGEN``, ``CLANG_TABLEGEN`` : Paths to llvm-tblgen and clang-tblgen
|
|
|
463 for the host architecture. If you already have built clang for the host, you
|
|
|
464 can point these variables to the executables in your build directory. If not,
|
|
|
465 you will need to build the llvm-tblgen and clang-tblgen host targets at
|
|
|
466 least.
|
|
|
467 * ``LLVM_HOST_TRIPLE`` : The triple of the system that lldb (or lldb-server)
|
|
|
468 will run on. Not setting this (or setting it incorrectly) can cause a lot of
|
|
|
469 issues with remote debugging as a lot of the choices lldb makes depend on the
|
|
|
470 triple reported by the remote platform.
|
|
|
471
|
|
|
472 You can of course also specify the usual cmake options like
|
|
|
473 ``CMAKE_BUILD_TYPE``, etc.
|
|
|
474
|
|
|
475 Example 1: Cross-compiling for linux arm64 on Ubuntu host
|
|
|
476 *********************************************************
|
|
|
477
|
|
|
478 Ubuntu already provides the packages necessary to cross-compile LLDB for arm64.
|
|
|
479 It is sufficient to install packages ``gcc-aarch64-linux-gnu``,
|
|
|
480 ``g++-aarch64-linux-gnu``, ``binutils-aarch64-linux-gnu``. Then it is possible
|
|
|
481 to prepare the cmake build with the following parameters:
|
|
|
482
|
|
|
483 ::
|
|
|
484
|
|
|
485 -DCMAKE_CROSSCOMPILING=1 \
|
|
|
486 -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
|
|
|
487 -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++ \
|
|
|
488 -DLLVM_HOST_TRIPLE=aarch64-unknown-linux-gnu \
|
|
|
489 -DLLVM_TABLEGEN=<path-to-host>/bin/llvm-tblgen \
|
|
|
490 -DCLANG_TABLEGEN=<path-to-host>/bin/clang-tblgen \
|
|
|
491 -DLLDB_ENABLE_PYTHON=0 \
|
|
|
492 -DLLDB_ENABLE_LIBEDIT=0 \
|
|
|
493 -DLLDB_ENABLE_CURSES=0
|
|
|
494
|
|
|
495 An alternative (and recommended) way to compile LLDB is with clang.
|
|
|
496 Unfortunately, clang is not able to find all the include paths necessary for a
|
|
|
497 successful cross-compile, so we need to help it with a couple of CFLAGS
|
|
|
498 options. In my case it was sufficient to add the following arguments to
|
|
|
499 ``CMAKE_C_FLAGS`` and ``CMAKE_CXX_FLAGS`` (in addition to changing
|
|
|
500 ``CMAKE_C(XX)_COMPILER`` to point to clang compilers):
|
|
|
501
|
|
|
502 ::
|
|
|
503
|
|
|
504 -target aarch64-linux-gnu \
|
|
|
505 -I /usr/aarch64-linux-gnu/include/c++/4.8.2/aarch64-linux-gnu \
|
|
|
506 -I /usr/aarch64-linux-gnu/include
|
|
|
507
|
|
|
508 If you wanted to build a full version of LLDB and avoid passing
|
|
|
509 ``-DLLDB_ENABLE_PYTHON=0`` and other options, you would need to obtain the
|
|
|
510 target versions of the respective libraries. The easiest way to achieve this is
|
|
|
511 to use the qemu-debootstrap utility, which can prepare a system image using
|
|
|
512 qemu and chroot to simulate the target environment. Then you can install the
|
|
|
513 necessary packages in this environment (python-dev, libedit-dev, etc.) and
|
|
|
514 point your compiler to use them using the correct -I and -L arguments.
|
|
|
515
|
|
|
516 Example 2: Cross-compiling for Android on Linux
|
|
|
517 ***********************************************
|
|
|
518
|
|
|
519 In the case of Android, the toolchain and all required headers and libraries
|
|
|
520 are available in the Android NDK.
|
|
|
521
|
|
|
522 The NDK also contains a cmake toolchain file, which makes configuring the build
|
|
|
523 much simpler. The compiler, include and library paths will be configured by the
|
|
|
524 toolchain file and all you need to do is to select the architecture
|
|
|
525 (ANDROID_ABI) and platform level (``ANDROID_PLATFORM``, should be at least 21).
|
|
|
526 You will also need to set ``ANDROID_ALLOW_UNDEFINED_SYMBOLS=On``, as the
|
|
|
527 toolchain file defaults to "no undefined symbols in shared libraries", which is
|
|
|
528 not compatible with some llvm libraries. The first version of NDK which
|
|
|
529 supports this approach is r14.
|
|
|
530
|
|
|
531 For example, the following arguments are sufficient to configure an android
|
|
|
532 arm64 build:
|
|
|
533
|
|
|
534 ::
|
|
|
535
|
|
|
536 -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
|
|
|
537 -DANDROID_ABI=arm64-v8a \
|
|
|
538 -DANDROID_PLATFORM=android-21 \
|
|
|
539 -DANDROID_ALLOW_UNDEFINED_SYMBOLS=On \
|
|
|
540 -DLLVM_HOST_TRIPLE=aarch64-unknown-linux-android \
|
|
|
541 -DCROSS_TOOLCHAIN_FLAGS_NATIVE='-DCMAKE_C_COMPILER=cc;-DCMAKE_CXX_COMPILER=c++'
|
|
|
542
|
|
|
543 Note that currently only lldb-server is functional on android. The lldb client
|
|
|
544 is not supported and unlikely to work.
|
|
|
545
|
|
|
546 Verifying Python Support
|
|
|
547 ------------------------
|
|
|
548
|
|
|
549 LLDB has a Python scripting capability and supplies its own Python module named
|
|
|
550 lldb. If a script is run inside the command line lldb application, the Python
|
|
|
551 module is made available automatically. However, if a script is to be run by a
|
|
|
552 Python interpreter outside the command line application, the ``PYTHONPATH``
|
|
|
553 environment variable can be used to let the Python interpreter find the lldb
|
|
|
554 module.
|
|
|
555
|
|
|
556 The correct path can be obtained by invoking the command line lldb tool with
|
|
|
557 the -P flag:
|
|
|
558
|
|
|
559 ::
|
|
|
560
|
|
|
561 > export PYTHONPATH=`$llvm/build/Debug+Asserts/bin/lldb -P`
|
|
|
562
|
|
|
563 If you used a different build directory or made a release build, you may need
|
|
|
564 to adjust the above to suit your needs. To test that the lldb Python module is
|
|
|
565 built correctly and is available to the default Python interpreter, run:
|
|
|
566
|
|
|
567 ::
|
|
|
568
|
|
|
569 > python -c 'import lldb'
|
|
|
570
|
|
|
571
|
|
|
572 Make sure you're using the Python interpreter that matches the Python library
|
|
|
573 you linked against. For more details please refer to the :ref:`caveats
|
|
|
574 <python_caveat>`.
|
|
|
575
|
|
|
576 .. _CodeSigning:
|
|
|
577
|
|
|
578 Code Signing on macOS
|
|
|
579 ---------------------
|
|
|
580
|
|
|
581 To use the in-tree debug server on macOS, lldb needs to be code signed. The
|
|
|
582 Debug, DebugClang and Release builds are set to code sign using a code signing
|
|
221
|
583 certificate named ``lldb_codesign``.
|
|
|
584
|
|
|
585 Automatic setup, run:
|
|
|
586
|
|
|
587 * ``scripts/macos-setup-codesign.sh``
|
|
150
|
588
|
|
|
589 Note that it's possible to build and use lldb on macOS without setting up code
|
|
|
590 signing by using the system's debug server. To configure lldb in this way with
|
|
|
591 cmake, specify ``-DLLDB_USE_SYSTEM_DEBUGSERVER=ON``.
|
|
|
592
|
|
|
593 If you have re-installed a new OS, please delete all old ``lldb_codesign`` items
|
|
|
594 from your keychain. There will be a code signing certification and a public
|
|
|
595 and private key. Reboot after deleting them. You will also need to delete and
|
|
|
596 build folders that contained old signed items. The darwin kernel will cache
|
|
|
597 code signing using the executable's file system node, so you will need to
|
|
|
598 delete the file so the kernel clears its cache.
|
|
|
599
|
|
|
600 When you build your LLDB for the first time, the Xcode GUI will prompt you for
|
|
|
601 permission to use the ``lldb_codesign`` keychain. Be sure to click "Always
|
|
|
602 Allow" on your first build. From here on out, the ``lldb_codesign`` will be
|
|
|
603 trusted and you can build from the command line without having to authorize.
|
|
|
604 Also the first time you debug using a LLDB that was built with this code
|
|
|
605 signing certificate, you will need to authenticate once.
|
