diff --git a/lldb/docs/resources/build.rst b/lldb/docs/resources/build.rst --- a/lldb/docs/resources/build.rst +++ b/lldb/docs/resources/build.rst @@ -78,23 +78,85 @@ * 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 --------------------------------- +Building LLDB with CMake +------------------------ + +The LLVM project is migrating to a single monolithic respository for LLVM and +its subprojects. This is the recommended way to build LLDB. Check out the +source-tree with git: + +:: + + > git clone https://github.com/llvm/llvm-project.git 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: +project, it generates the files needed by your build tool. The recommended +build tool for LLVM is Ninja, but other generators like Xcode or Visual Studio +may be used as well. Please also read `Building LLVM with CMake +`_. + +Regular in-tree builds +********************** + +Create a new directory for your build-tree. From there run CMake and point it +to the ``llvm`` directory in the source-tree: :: - > cmake -G Ninja + > cmake -G Ninja -DLLVM_ENABLE_PROJECTS="clang;lldb" [] path/to/llvm-project/llvm -Once CMake has configured your build, you can run ``ninja`` to build LLDB. +We used the ``LLVM_ENABLE_PROJECTS`` option here to tell the build-system which +subprojects to build in addition to LLVM (for more options see +:ref:`CommonCMakeOptions` and :ref:`CMakeCaches`). Parts of the LLDB test suite +require ``lld``. Add it to the list in order to run all tests. Once CMake is done, +run ninja to perform the actual build. We pass ``lldb`` here as the target, so +it only builds what is necessary to run the lldb driver: :: > ninja lldb +Standalone builds +***************** + +This is another way to build LLDB. We can use the same source-tree as we +checked out above, but now we will have two build-trees: + +* the main build-tree for LLDB in ``/path/to/lldb-build`` +* a provided build-tree for LLVM and Clang in ``/path/to/llvm-build`` + +Run CMake with ``-B`` pointing to a new directory for the provided build-tree +and the positional argument pointing to the ``llvm`` directory in the +source-tree. Note that we leave out LLDB here and only include Clang. +Then we build the ``ALL`` target with ninja: + +:: + + > cmake -B /path/to/llvm-build -G Ninja \ + -DLLVM_ENABLE_PROJECTS=clang \ + [] /path/to/llvm-project/llvm + > ninja + +Now run CMake a second time with ``-B`` pointing to a new directory for the +main build-tree and the positional argument pointing to the ``lldb`` directory +in the source-tree. In order to find the provided build-tree, the build-system +needs the options ``LLVM_DIR`` and ``Clang_DIR`` (CMake variables are +case-sensitive!): + +:: + + > cmake -B /path/to/lldb-build -G Ninja \ + -DLLVM_DIR=/path/to/llvm-build/lib/cmake/llvm \ + -DClang_DIR=/path/to/llvm-build/lib/cmake/clang \ + [] /path/to/llvm-project/lldb + > ninja lldb + + +.. _CommonCMakeOptions: + +Common CMake options +******************** + 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. @@ -128,7 +190,7 @@ test execution. Windows -******* +^^^^^^^ Although the following CMake variables are by no means Windows specific, they are commonly used on Windows. @@ -161,8 +223,27 @@ -DLLDB_TEST_C_COMPILER=d:\src\llvmbuild\ninja_release\bin\clang.exe^ + +Building with ninja is both faster and simpler than building with Visual Studio, +but chances are you still want to debug LLDB with an IDE. One solution 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. + +Follow the previous instructions in one directory, and generate a Visual Studio +project in another directory. + +:: + + > cmake -G "Visual Studio 15 2017 Win64" -Thost=x64 + +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. + + NetBSD -****** +^^^^^^ Current stable NetBSD release doesn't ship with libpanel(3), therefore it's required to disable curses(3) support with the @@ -170,48 +251,71 @@ ``/usr/include/panel.h`` exists in your system. macOS -***** +^^^^^ -Here are some commonly used LLDB-specific CMake variables on macOS. +On macOS the LLDB test suite requires libc++. Either add ``libcxx`` to +``LLVM_ENABLE_PROJECTS`` or disable the test suite with +``LLDB_ENABLE_TESTS=OFF``. Further useful options: -* ``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. +* ``LLDB_BUILD_FRAMEWORK:BOOL``: Builds the LLDB.framework. +* ``LLDB_CODESIGN_IDENTITY:STRING``: Set the identity to use for code-signing + all executables. If not explicitly specified, only ``debugserver`` will be + code-signed with identity ``lldb_codesign`` (see :ref:`CodeSigning`). +* ``LLDB_USE_SYSTEM_DEBUGSERVER:BOOL``: Use the system's debugserver, so lldb is + functional without setting up code-signing. -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. +.. _CMakeCaches: +CMake caches +************ -Visual Studio -************* +CMake caches allow to store common sets of configuration options in the form of +CMake scripts and can be useful to reproduce builds for particular use-cases +(see by analogy `usage in LLVM and Clang `_). +A cache is passed to CMake with the ``-C`` flag, following the absolute path to +the file on disk. Subsequent ``-D`` options are still allowed. Please find the +currently available caches in the `lldb/cmake/caches/ +`_ +directory. -Follow the previous instructions in one directory, and generate a Visual Studio -project in another directory. +Common configurations on macOS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Build, test and install a distribution of LLDB from the `monorepo +`_ (see also `Building a Distribution of +LLVM `_): :: - > cmake -G "Visual Studio 14 2015" + > git clone https://github.com/llvm/llvm-project -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. + > cmake -B /path/to/lldb-build -G Ninja \ + -C /path/to/llvm-project/lldb/cmake/caches/Apple-lldb-macOS.cmake \ + -DLLVM_ENABLE_PROJECTS="clang;libcxx;lldb" \ + llvm-project/llvm -Xcode -***** + > DESTDIR=/path/to/lldb-install ninja -C /path/to/lldb-build check-lldb install-distribution -Follow the previous instructions in one directory, and generate an Xcode -project in another directory. +Build LLDB standalone for development with Xcode: :: - > cmake -G Xcode + > git clone https://github.com/llvm/llvm-project + + > cmake -B /path/to/llvm-build -G Ninja \ + -C /path/to/llvm-project/lldb/cmake/caches/Apple-lldb-base.cmake \ + -DLLVM_ENABLE_PROJECTS="clang;libcxx" \ + llvm-project/llvm + > ninja -C /path/to/llvm-build + + > cmake -B /path/to/lldb-build -G Xcode \ + -C /path/to/llvm-project/lldb/cmake/caches/Apple-lldb-Xcode.cmake \ + -DLLVM_DIR=/path/to/llvm-build/lib/cmake/llvm \ + -DClang_DIR=/path/to/llvm-build/lib/cmake/clang \ + llvm-project/lldb + > open lldb.xcodeproj + > cmake --build /path/to/lldb-build --target check-lldb Building The Documentation @@ -233,7 +337,7 @@ > sudo apt-get install doxygen graphviz python3-sphinx > sudo pip install epydoc -To build the documentation, build the desired target(s). +To build the documentation, configure with ``LLVM_ENABLE_SPHINX=ON`` and build the desired target(s). :: @@ -418,7 +522,7 @@ 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=''``. +cmake, specify ``-DLLDB_USE_SYSTEM_DEBUGSERVER=ON``. 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 diff --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst --- a/llvm/docs/GettingStarted.rst +++ b/llvm/docs/GettingStarted.rst @@ -160,9 +160,9 @@ Software -------- -Compiling LLVM requires that you have several software packages installed. The -table below lists those required packages. The Package column is the usual name -for the software package that LLVM depends on. The Version column provides +Working with LLVM requires that you have several software packages installed. +The table below lists those required packages. The Package column is the usual +name for the software package that LLVM depends on. The Version column provides "known to work" versions of the package. The Notes column describes how LLVM uses the package and provides other details. @@ -503,8 +503,8 @@ A helper script is provided in ``llvm/utils/git-svn/git-llvm``. After you add it to your path, you can push committed changes upstream with ``git llvm -push``. While this creates a Subversion checkout and patches it under the hood, -it does not require you to have interaction with it. +push``\ :sup:`1`. While this creates a Subversion checkout and patches it under +the hood, it does not require you to have interaction with it. .. code-block:: console @@ -525,6 +525,10 @@ tell you what it would have done. That can be useful if you're unsure whether the right thing will happen. +.. note:: + + #. The helper script works with git versions >=2.9.3 + Reverting a change when using Git ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^