forked from OSchip/llvm-project
[Docs] Unify build instructions
The current build instructions are structured according the host platform. Instead of having instructions on how to build with CMake repeated for every platform, I unified them, using subsections if things are different for between platforms. I also added the code signing instructions, which were hidden in a text file in the repository. llvm-svn: 365081
This commit is contained in:
Jonas Devlieghere
parent
7afe9ea96f
commit
a767b05cf7
|
|
@ -4,35 +4,55 @@ Build
|
|||
.. contents::
|
||||
:local:
|
||||
|
||||
Building LLDB on Windows
|
||||
------------------------
|
||||
Preliminaries
|
||||
-------------
|
||||
|
||||
**Required Dependencies**
|
||||
LLDB relies on many of the technologies developed by the larger LLVM project.
|
||||
In particular, it requires both Clang and LLVM itself in order to build. Due to
|
||||
this tight integration the Getting Started guides for both of these projects
|
||||
come as prerequisite reading:
|
||||
|
||||
* `LLVM <http://llvm.org/docs/GettingStarted.html>`_
|
||||
* `Clang <http://clang.llvm.org/get_started.html>`_
|
||||
|
||||
The following requirements are shared on all platforms.
|
||||
|
||||
* `CMake <https://cmake.org>`_
|
||||
* `Ninja <https://ninja-build.org>`_ (strongly recommended)
|
||||
* `Python <http://www.python.org/>`_
|
||||
* `SWIG <http://swig.org/>`_
|
||||
|
||||
Depending on your platform and package manager, one might run any of the
|
||||
commands below.
|
||||
|
||||
::
|
||||
|
||||
> yum install libedit-devel libxml2-devel ncurses-devel python-devel swig
|
||||
> sudo apt-get install build-essential subversion swig python2.7-dev libedit-dev libncurses5-dev
|
||||
> pkg install swig python
|
||||
> pkgin install swig python27 cmake ninja-build
|
||||
> brew install swig cmake ninja
|
||||
|
||||
Windows
|
||||
*******
|
||||
|
||||
* Visual Studio 2015 or greater
|
||||
* Windows SDK 8.0 or higher. In general it is best to use the latest available version.
|
||||
* Windows SDK 8.0 or higher. In general it is best to use the latest available
|
||||
version.
|
||||
* `GnuWin32 <http://gnuwin32.sourceforge.net/>`_
|
||||
* `Python 3.5 or higher <https://www.python.org/downloads/windows/>`_ or
|
||||
higher. Earlier versions of Python can be made to work by compiling your own
|
||||
distribution from source, but this workflow is unsupported and you are own
|
||||
your own.
|
||||
* `Ninja build tool <https://ninja-build.org/>`_ (strongly recommended)
|
||||
* `GnuWin32 <http://gnuwin32.sourceforge.net/>`_
|
||||
* `SWIG for Windows <http://www.swig.org/download.html>`_ (version 3+)
|
||||
|
||||
|
||||
**Optional Dependencies**
|
||||
|
||||
* `Python Tools for Visual Studio
|
||||
<https://github.com/Microsoft/PTVS/releases>`_. If you plan to debug test
|
||||
failures or even write new tests at all, PTVS is an indispensable debugging
|
||||
extension to VS that enables full editing and debugging support for Python
|
||||
(including mixed native/managed debugging)
|
||||
|
||||
**Preliminaries**
|
||||
|
||||
This section describes how to set up your system and install the required
|
||||
dependencies such that they can be found when needed during the build process.
|
||||
The steps outlined here only need to be performed once.
|
||||
The steps outlined here describes how to set up your system and install the
|
||||
required dependencies such that they can be found when needed during the build
|
||||
process. They only need to be performed once.
|
||||
|
||||
#. Install Visual Studio and the Windows SDK.
|
||||
#. Install GnuWin32, making sure ``<GnuWin32 install dir>\bin`` is added to
|
||||
|
|
@ -40,30 +60,79 @@ The steps outlined here only need to be performed once.
|
|||
#. Install SWIG for Windows, making sure ``<SWIG install dir>`` is added to
|
||||
your PATH environment variable.
|
||||
|
||||
**Building LLDB**
|
||||
|
||||
Any command prompt from which you build LLDB should have a valid Visual Studio
|
||||
environment setup. This means you should run ``vcvarsall.bat`` or open an
|
||||
appropriate Visual Studio Command Prompt corresponding to the version you wish
|
||||
to use.
|
||||
|
||||
Linux
|
||||
*****
|
||||
|
||||
Finally, when you are ready to build LLDB, generate CMake with the following
|
||||
command line:
|
||||
* `libedit <http://www.thrysoee.dk/editline>`_
|
||||
|
||||
macOS
|
||||
*****
|
||||
|
||||
* To use the in-tree debug server on macOS, lldb needs to be code signed. For
|
||||
more information see :ref:`CodeSigning` below.
|
||||
* If you are building both Clang and LLDB together, be sure to also check out
|
||||
libc++, which is a required for testing on macOS.
|
||||
|
||||
Building LLDB with CMake & Ninja
|
||||
--------------------------------
|
||||
|
||||
CMake is a cross-platform build-generator tool. CMake does not build the
|
||||
project, it generates the files needed by your build tool. Assuming you're
|
||||
using Ninja, the invocation looks like this:
|
||||
|
||||
::
|
||||
|
||||
cmake -G Ninja <cmake variables> <path to root of llvm src tree>
|
||||
> cmake -G Ninja <cmake variables> <path to root of llvm source tree>
|
||||
|
||||
Once CMake has configured your build, you can run ``ninja`` to build LLDB.
|
||||
|
||||
and run ``ninja`` to build LLDB. Information about running the LLDB test suite
|
||||
can be found on the test page.
|
||||
::
|
||||
|
||||
> ninja lldb
|
||||
|
||||
Following is a description of some of the most important CMake variables which
|
||||
you are likely to encounter. A variable FOO is set by adding ``-DFOO=value`` to
|
||||
the CMake command line.
|
||||
|
||||
If you want to debug the lldb that you're building -- that is, build it with
|
||||
debug info enabled -- pass two additional arguments to cmake before running
|
||||
ninja:
|
||||
|
||||
::
|
||||
|
||||
> cmake -G Ninja \
|
||||
-DLLDB_EXPORT_ALL_SYMBOLS=1 \
|
||||
-DCMAKE_BUILD_TYPE=Debug
|
||||
<path to root of llvm source tree>
|
||||
|
||||
If you want to run the test suite, you will need a compiler to build the test
|
||||
programs. If you have Clang checked out, that will be used by default.
|
||||
Alternatively, you can specify a C and C++ compiler to be used by the test
|
||||
suite.
|
||||
|
||||
::
|
||||
|
||||
> cmake -G Ninja \
|
||||
-DLLDB_TEST_USE_CUSTOM_C_COMPILER=On \
|
||||
-DLLDB_TEST_USE_CUSTOM_CXX_COMPILER=On \
|
||||
-DLLDB_TEST_C_COMPILER=<path to C compiler> \
|
||||
-DLLDB_TEST_CXX_COMPILER=<path to C++ compiler> \
|
||||
<path to root of llvm source tree>
|
||||
|
||||
It is strongly recommend to use a release build for the compiler to speed up
|
||||
test execution.
|
||||
|
||||
Windows
|
||||
*******
|
||||
|
||||
Although the following CMake variables are by no means Windows specific, they
|
||||
are commonly used on Windows.
|
||||
|
||||
* ``LLDB_TEST_DEBUG_TEST_CRASHES`` (Default=0): If set to 1, will cause Windows
|
||||
to generate a crash dialog whenever lldb.exe or the python extension module
|
||||
crashes while running the test suite. If set to 0, LLDB will silently crash.
|
||||
|
|
@ -80,248 +149,100 @@ the CMake command line.
|
|||
Python to use its default mechanism for finding the python installation at
|
||||
runtime (looking for installed Pythons, or using the ``PYTHONHOME``
|
||||
environment variable if it is specified).
|
||||
* ``LLDB_TEST_C_COMPILER`` or ``LLDB_TEST_CXX_COMPILER``: The test suite needs
|
||||
to be able to find a copy of clang.exe that it can use to compile inferior
|
||||
programs. Note that MSVC is not supported here, it must be a path to a clang
|
||||
executable. Note that using a release clang.exe is strongly recommended here,
|
||||
as it will make the test suite run much faster. This can be a path to any
|
||||
recent clang.exe, including one you built yourself. These variables are
|
||||
ignored unless the respective ``LLDB_TEST_USE_CUSTOM_C_COMPILER`` and
|
||||
``LLDB_TEST_USE_CUSTOM_CXX_COMPILER`` are set to ON.
|
||||
|
||||
Sample command line:
|
||||
|
||||
::
|
||||
|
||||
cmake -G Ninja -DLLDB_TEST_DEBUG_TEST_CRASHES=1 -DPYTHON_HOME=C:\Python35 -DLLDB_TEST_USE_CUSTOM_C_COMPILER=ON -DLLDB_TEST_C_COMPILER=d:\src\llvmbuild\ninja_release\bin\clang.exe ..\..\llvm
|
||||
|
||||
|
||||
**Working with both Ninja and MSVC**
|
||||
|
||||
Compiling with ninja is both faster and simpler than compiling with MSVC, but
|
||||
chances are you still want to debug LLDB with MSVC (at least until we can debug
|
||||
LLDB on Windows with LLDB!). One solution to this is to run cmake twice and
|
||||
generate the output into two different folders. One for compiling (the ninja
|
||||
folder), and one for editing / browsing / debugging (the MSVC folder).
|
||||
|
||||
To do this, simply run ``cmake -G Ninja <arguments>`` from one folder, and
|
||||
``cmake -G "Visual Studio 14 2015" <arguments>`` in another folder. Then you
|
||||
can open the .sln file in Visual Studio, set lldb as the startup project, and
|
||||
use F5 to run it. You need only edit the project settings to set the executable
|
||||
and the working directory to point to binaries inside of the ninja tree.
|
||||
|
||||
Building LLDB on macOS
|
||||
----------------------
|
||||
|
||||
There are two ways to build LLDB on macOS: Using Xcode and using CMake
|
||||
|
||||
**Preliminaries**
|
||||
|
||||
In addition to any dependencies required by LLVM and Clang, LLDB needs a few
|
||||
development packages that may also need to be installed depending on your
|
||||
system. The current list of dependencies are:
|
||||
|
||||
* Xcode 4.3 or newer requires the "Command Line Tools" component (XCode->Preferences->Downloads->Components)
|
||||
* `Swig <http://swig.org/>`_
|
||||
|
||||
**Building LLDB with Xcode**
|
||||
|
||||
Building on macOS with Xcode is as easy as downloading the code and building
|
||||
the Xcode project or workspace:
|
||||
|
||||
* Download the lldb sources.
|
||||
* Follow the code signing instructions in ``lldb/docs/code-signing.txt``.
|
||||
* In Xcode, open ``lldb/lldb.xcworkspace``, select the lldb-tool scheme, and build.
|
||||
|
||||
**Building LLDB with CMake**
|
||||
|
||||
First download the LLVM, Clang, libc++ and LLDB sources. Refer to this page for
|
||||
precise instructions on this step.
|
||||
|
||||
Refer to the code signing instructions in ``lldb/docs/code-signing.txt`` for
|
||||
info on codesigning debugserver during the build.
|
||||
|
||||
Using CMake is documented on the `Building LLVM with CMake
|
||||
<http://llvm.org/docs/CMake.html>`_ page. Ninja is the recommended generator to
|
||||
use when building LLDB with CMake.
|
||||
|
||||
::
|
||||
|
||||
> cmake $PATH_TO_LLVM -G Ninja
|
||||
> ninja lldb
|
||||
|
||||
As noted in the "Building LLVM with CMake" page mentioned above, you can pass
|
||||
variables to cmake to change build behavior. If LLDB is built as a part of
|
||||
LLVM, then you can pass LLVM-specific CMake variables to cmake when building
|
||||
LLDB.
|
||||
|
||||
If you are building both Clang and LLDB together, be sure to also add libc++,
|
||||
which is currently required for testing on macOS:
|
||||
|
||||
::
|
||||
|
||||
> cmake -D LLVM_ENABLE_PROJECTS='clang;lldb;libcxx' $PATH_TO_LLVM -G Ninja
|
||||
|
||||
Here are some commonly used LLDB-specific CMake variables:
|
||||
|
||||
* ``LLDB_EXPORT_ALL_SYMBOLS:BOOL`` : Exports all symbols. Useful in conjunction
|
||||
with CMAKE_BUILD_TYPE=Debug.
|
||||
* ``LLDB_BUILD_FRAMEWORK:BOOL`` : Builds LLDB.framework as Xcode would
|
||||
* ``LLDB_CODESIGN_IDENTITY:STRING`` : Determines the codesign identity to use.
|
||||
An empty string means skip building debugserver to avoid codesigning.
|
||||
|
||||
Building LLDB on Linux, FreeBSD and NetBSD
|
||||
------------------------------------------
|
||||
|
||||
This document describes the steps needed to compile LLDB on most Linux systems,
|
||||
FreeBSD and NetBSD.
|
||||
|
||||
**Preliminaries**
|
||||
|
||||
LLDB relies on many of the technologies developed by the larger LLVM project.
|
||||
In particular, it requires both Clang and LLVM itself in order to build. Due to
|
||||
this tight integration the Getting Started guides for both of these projects
|
||||
come as prerequisite reading:
|
||||
|
||||
* `LLVM <http://llvm.org/docs/GettingStarted.html>`_
|
||||
* `Clang <http://clang.llvm.org/get_started.html>`_
|
||||
|
||||
Supported compilers for building LLDB on Linux include:
|
||||
|
||||
* Clang 3.2
|
||||
* GCC 4.6.2 (later versions should work as well)
|
||||
|
||||
It is recommended to use libstdc++ 4.6 (or higher) to build LLDB on Linux, but
|
||||
using libc++ is also known to work.
|
||||
|
||||
On FreeBSD the base system Clang and libc++ may be used to build LLDB, or the
|
||||
GCC port or package.
|
||||
|
||||
On NetBSD the base system GCC and libstdc++ are used to build LLDB, Clang/LLVM
|
||||
and libc++ should also work.
|
||||
|
||||
In addition to any dependencies required by LLVM and Clang, LLDB needs a few
|
||||
development packages that may also need to be installed depending on your
|
||||
system. The current list of dependencies are:
|
||||
|
||||
* `Swig <http://swig.org/>`_
|
||||
* `libedit (Linux only) <http://www.thrysoee.dk/editline>`_
|
||||
* `Python <http://www.python.org/>`_
|
||||
|
||||
|
||||
So for example, on a Fedora system one might run:
|
||||
|
||||
::
|
||||
|
||||
> yum install libedit-devel libxml2-devel ncurses-devel python-devel swig
|
||||
|
||||
On a Debian or Ubuntu system one might run:
|
||||
|
||||
::
|
||||
|
||||
> sudo apt-get install build-essential subversion swig python2.7-dev libedit-dev libncurses5-dev
|
||||
|
||||
or
|
||||
|
||||
::
|
||||
|
||||
> sudo apt-get build-dep lldb-3.3 # or lldb-3.4
|
||||
|
||||
|
||||
On FreeBSD one might run:
|
||||
|
||||
::
|
||||
|
||||
> pkg install swig python
|
||||
|
||||
On NetBSD one might run:
|
||||
|
||||
::
|
||||
|
||||
> pkgin install swig python27 cmake ninja-build
|
||||
|
||||
**To build with CMake**
|
||||
|
||||
Using CMake is documented on the `Building LLVM with CMake
|
||||
<http://llvm.org/docs/CMake.html>`_ page. Building LLDB is possible using one
|
||||
of the following generators:
|
||||
|
||||
* Ninja
|
||||
* Unix Makefiles
|
||||
|
||||
**Using CMake + Ninja**
|
||||
|
||||
Ninja is the fastest way to build LLDB! In order to use ninja, you need to have
|
||||
recent versions of CMake and ninja on your system. To build using ninja:
|
||||
|
||||
::
|
||||
|
||||
> cmake ../llvm -G Ninja
|
||||
> ninja lldb
|
||||
> ninja check-lldb
|
||||
|
||||
|
||||
If you want to debug the lldb that you're building -- that is, build it with
|
||||
debug info enabled -- pass two additional arguments to cmake before running
|
||||
ninja:
|
||||
|
||||
::
|
||||
|
||||
> cmake ../llvm -G Ninja -DLLDB_EXPORT_ALL_SYMBOLS=1 -DCMAKE_BUILD_TYPE=Debug
|
||||
|
||||
|
||||
**Using CMake + Unix Makefiles**
|
||||
|
||||
If you do not have Ninja, you can still use CMake to generate Unix Makefiles that build LLDB:
|
||||
|
||||
::
|
||||
|
||||
> cmake ..
|
||||
> make
|
||||
> make check-lldb
|
||||
|
||||
|
||||
**Building API reference documentation**
|
||||
|
||||
LLDB exposes a C++ as well as a Python API. To build the reference
|
||||
documentation for these two APIs, ensure you have the required dependencies
|
||||
installed, and build the ``lldb-python-doc`` and ``lldb-cpp-doc`` CMake
|
||||
targets.
|
||||
|
||||
The output HTML reference documentation can be found in
|
||||
``<build-dir>/tools/lldb/docs/``.
|
||||
|
||||
**Additional Notes**
|
||||
|
||||
LLDB has a Python scripting capability and supplies its own Python module named
|
||||
lldb. If a script is run inside the command line lldb application, the Python
|
||||
module is made available automatically. However, if a script is to be run by a
|
||||
Python interpreter outside the command line application, the ``PYTHONPATH``
|
||||
environment variable can be used to let the Python interpreter find the lldb
|
||||
module.
|
||||
> cmake -G Ninja^
|
||||
-DLLDB_TEST_DEBUG_TEST_CRASHES=1^
|
||||
-DPYTHON_HOME=C:\Python35^
|
||||
-DLLDB_TEST_USE_CUSTOM_C_COMPILER=ON^
|
||||
-DLLDB_TEST_C_COMPILER=d:\src\llvmbuild\ninja_release\bin\clang.exe^
|
||||
<path to root of llvm source tree>
|
||||
|
||||
NetBSD
|
||||
******
|
||||
|
||||
Current stable NetBSD release doesn't ship with libpanel(3), therefore it's
|
||||
required to disable curses(3) support with the
|
||||
``-DLLDB_DISABLE_CURSES:BOOL=TRUE`` option. To make sure check if
|
||||
``/usr/include/panel.h`` exists in your system.
|
||||
|
||||
The correct path can be obtained by invoking the command line lldb tool with
|
||||
the -P flag:
|
||||
macOS
|
||||
*****
|
||||
|
||||
Here are some commonly used LLDB-specific CMake variables on macOS.
|
||||
|
||||
* ``LLDB_BUILD_FRAMEWORK:BOOL`` : Builds the LLDB.framework.
|
||||
* ``LLDB_CODESIGN_IDENTITY:STRING`` : Determines the codesign identity to use.
|
||||
An empty string means skip building debugserver to avoid codesigning.
|
||||
|
||||
Building LLDB with CMake and Other Generators
|
||||
---------------------------------------------
|
||||
|
||||
Compiling with ninja is both faster and simpler than compiling with MSVC or
|
||||
Xcode, but chances are you still want to debug LLDB with those IDEs. One
|
||||
solution to this is to run cmake twice and generate the output into two
|
||||
different folders. One for compiling (the ninja folder), and one for editing,
|
||||
browsing and debugging.
|
||||
|
||||
|
||||
Visual Studio
|
||||
*************
|
||||
|
||||
Follow the previous instructions in one directory, and generate a Visual Studio
|
||||
project in another directory.
|
||||
|
||||
::
|
||||
|
||||
> export PYTHONPATH=`$llvm/build/Debug+Asserts/bin/lldb -P`
|
||||
> cmake -G "Visual Studio 14 2015" <cmake variables> <path to root of llvm source tree>
|
||||
|
||||
If you used a different build directory or made a release build, you may need
|
||||
to adjust the above to suit your needs. To test that the lldb Python module is
|
||||
built correctly and is available to the default Python interpreter, run:
|
||||
Then you can open the .sln file in Visual Studio, set lldb as the startup
|
||||
project, and use F5 to run it. You need only edit the project settings to set
|
||||
the executable and the working directory to point to binaries inside of the
|
||||
ninja tree.
|
||||
|
||||
Xcode
|
||||
*****
|
||||
|
||||
Follow the previous instructions in one directory, and generate an Xcode
|
||||
project in another directory.
|
||||
|
||||
::
|
||||
|
||||
> python -c 'import lldb'
|
||||
> cmake -G Xcode <cmake variables> <path to root of llvm source tree>
|
||||
|
||||
**Cross-compiling LLDB**
|
||||
|
||||
Building The Documentation
|
||||
--------------------------
|
||||
|
||||
If you wish to build the optional (reference) documentation, additional
|
||||
dependencies are required:
|
||||
|
||||
* Sphinx (for the website)
|
||||
* Graphviz (for the 'dot' tool)
|
||||
* doxygen (if you wish to build the C++ API reference)
|
||||
* epydoc (if you wish to build the Python API reference)
|
||||
|
||||
To install the prerequisites for building the documentation (on Debian/Ubuntu)
|
||||
do:
|
||||
|
||||
::
|
||||
|
||||
> sudo apt-get install doxygen graphviz python3-sphinx
|
||||
> sudo pip install epydoc
|
||||
|
||||
To build the documentation, build the desired target(s).
|
||||
|
||||
::
|
||||
|
||||
> cmake --build . --target docs-lldb-html
|
||||
> cmake --build . --target lldb-cpp-doc
|
||||
> cmake --build . --target lldb-python-doc
|
||||
|
||||
Cross-compiling LLDB
|
||||
--------------------
|
||||
|
||||
In order to debug remote targets running different architectures than your
|
||||
host, you will need to compile LLDB (or at least the server component) for the
|
||||
|
|
@ -389,7 +310,8 @@ The most important cmake options here are:
|
|||
You can of course also specify the usual cmake options like
|
||||
``CMAKE_BUILD_TYPE``, etc.
|
||||
|
||||
**Example 1: Cross-compiling for linux arm64 on Ubuntu host**
|
||||
Example 1: Cross-compiling for linux arm64 on Ubuntu host
|
||||
*********************************************************
|
||||
|
||||
Ubuntu already provides the packages necessary to cross-compile LLDB for arm64.
|
||||
It is sufficient to install packages ``gcc-aarch64-linux-gnu``,
|
||||
|
|
@ -429,7 +351,8 @@ qemu and chroot to simulate the target environment. Then you can install the
|
|||
necessary packages in this environment (python-dev, libedit-dev, etc.) and
|
||||
point your compiler to use them using the correct -I and -L arguments.
|
||||
|
||||
**Example 2: Cross-compiling for Android on Linux**
|
||||
Example 2: Cross-compiling for Android on Linux
|
||||
***********************************************
|
||||
|
||||
In the case of Android, the toolchain and all required headers and libraries
|
||||
are available in the Android NDK.
|
||||
|
|
@ -458,29 +381,105 @@ arm64 build:
|
|||
Note that currently only lldb-server is functional on android. The lldb client
|
||||
is not supported and unlikely to work.
|
||||
|
||||
Building The Documentation
|
||||
--------------------------
|
||||
Verifying Python Support
|
||||
------------------------
|
||||
|
||||
If you wish to build the optional (reference) documentation, additional
|
||||
dependencies are required:
|
||||
LLDB has a Python scripting capability and supplies its own Python module named
|
||||
lldb. If a script is run inside the command line lldb application, the Python
|
||||
module is made available automatically. However, if a script is to be run by a
|
||||
Python interpreter outside the command line application, the ``PYTHONPATH``
|
||||
environment variable can be used to let the Python interpreter find the lldb
|
||||
module.
|
||||
|
||||
* Sphinx (for the website)
|
||||
* Graphviz (for the 'dot' tool)
|
||||
* doxygen (if you wish to build the C++ API reference)
|
||||
* epydoc (if you wish to build the Python API reference)
|
||||
|
||||
To install the prerequisites for building the documentation (on Debian/Ubuntu)
|
||||
do:
|
||||
The correct path can be obtained by invoking the command line lldb tool with
|
||||
the -P flag:
|
||||
|
||||
::
|
||||
|
||||
> sudo apt-get install doxygen graphviz python3-sphinx
|
||||
> sudo pip install epydoc
|
||||
> export PYTHONPATH=`$llvm/build/Debug+Asserts/bin/lldb -P`
|
||||
|
||||
To build the documentation, build the desired target(s).
|
||||
If you used a different build directory or made a release build, you may need
|
||||
to adjust the above to suit your needs. To test that the lldb Python module is
|
||||
built correctly and is available to the default Python interpreter, run:
|
||||
|
||||
::
|
||||
|
||||
> cmake --build . --target docs-lldb-html
|
||||
> cmake --build . --target lldb-cpp-doc
|
||||
> cmake --build . --target lldb-python-doc
|
||||
> python -c 'import lldb'
|
||||
|
||||
.. _CodeSigning:
|
||||
|
||||
Code Signing on macOS
|
||||
---------------------
|
||||
|
||||
To use the in-tree debug server on macOS, lldb needs to be code signed. The
|
||||
Debug, DebugClang and Release builds are set to code sign using a code signing
|
||||
certificate named ``lldb_codesign``. This document explains how to set up the
|
||||
signing certificate.
|
||||
|
||||
Note that it's possible to build and use lldb on macOS without setting up code
|
||||
signing by using the system's debug server. To configure lldb in this way with
|
||||
cmake, specify ``-DLLDB_CODESIGN_IDENTITY=''``.
|
||||
|
||||
If you have re-installed a new OS, please delete all old ``lldb_codesign`` items
|
||||
from your keychain. There will be a code signing certification and a public
|
||||
and private key. Reboot after deleting them. You will also need to delete and
|
||||
build folders that contained old signed items. The darwin kernel will cache
|
||||
code signing using the executable's file system node, so you will need to
|
||||
delete the file so the kernel clears its cache.
|
||||
|
||||
Automatic setup:
|
||||
|
||||
* Run ``scripts/macos-setup-codesign.sh``
|
||||
|
||||
Manual setup steps:
|
||||
|
||||
* Launch /Applications/Utilities/Keychain Access.app
|
||||
* In Keychain Access select the ``login`` keychain in the ``Keychains`` list in
|
||||
the upper left hand corner of the window.
|
||||
* Select the following menu item: Keychain Access->Certificate Assistant->Create a Certificate...
|
||||
* Set the following settings
|
||||
|
||||
::
|
||||
|
||||
Name = lldb_codesign
|
||||
Identity Type = Self Signed Root
|
||||
Certificate Type = Code Signing
|
||||
|
||||
* Click Create
|
||||
* Click Continue
|
||||
* Click Done
|
||||
* Click on the "My Certificates"
|
||||
* Double click on your new ``lldb_codesign`` certificate
|
||||
* Turn down the "Trust" disclosure triangle, scroll to the "Code Signing" trust
|
||||
pulldown menu and select "Always Trust" and authenticate as needed using your
|
||||
username and password.
|
||||
* Drag the new ``lldb_codesign`` code signing certificate (not the public or
|
||||
private keys of the same name) from the ``login`` keychain to the ``System``
|
||||
keychain in the Keychains pane on the left hand side of the main Keychain
|
||||
Access window. This will move this certificate to the ``System`` keychain.
|
||||
You'll have to authorize a few more times, set it to be "Always trusted" when
|
||||
asked.
|
||||
* Remove ``~/Desktop/lldb_codesign.cer`` file on your desktop if there is one.
|
||||
* In the Keychain Access GUI, click and drag ``lldb_codesign`` in the
|
||||
``System`` keychain onto the desktop. The drag will create a
|
||||
``Desktop/lldb_codesign.cer`` file used in the next step.
|
||||
* Switch to Terminal, and run the following:
|
||||
|
||||
::
|
||||
|
||||
sudo security add-trust -d -r trustRoot -p basic -p codeSign -k /Library/Keychains/System.keychain ~/Desktop/lldb_codesign.cer
|
||||
rm -f ~/Desktop/lldb_codesign.cer
|
||||
|
||||
* Drag the ``lldb_codesign`` certificate from the ``System`` keychain back into
|
||||
the ``login`` keychain
|
||||
* Quit Keychain Access
|
||||
* Reboot
|
||||
* Clean by removing all previously creating code signed binaries and rebuild
|
||||
lldb and you should be able to debug.
|
||||
|
||||
When you build your LLDB for the first time, the Xcode GUI will prompt you for
|
||||
permission to use the ``lldb_codesign`` keychain. Be sure to click "Always
|
||||
Allow" on your first build. From here on out, the ``lldb_codesign`` will be
|
||||
trusted and you can build from the command line without having to authorize.
|
||||
Also the first time you debug using a LLDB that was built with this code
|
||||
signing certificate, you will need to authenticate once.
|
||||
|
|
|
|||
Loading…
Reference in New Issue