sgraenitz updated this revision to Diff 211951. sgraenitz added a comment. Merge Visual Studio build instructions into `Common CMake options > Windows`
Repository: rG LLVM Github Monorepo CHANGES SINCE LAST ACTION https://reviews.llvm.org/D65330/new/ https://reviews.llvm.org/D65330 Files: lldb/docs/resources/build.rst
Index: lldb/docs/resources/build.rst =================================================================== --- lldb/docs/resources/build.rst +++ lldb/docs/resources/build.rst @@ -78,23 +78,83 @@ * 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. Checkout 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. Please also read `Building LLVM with CMake +<http://llvm.org/docs/CMake.html>`_. + +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 -DLLVM_ENABLE_PROJECTS="clang;lldb" [<cmake options>] path/to/llvm-project/llvm + +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 `Common CMake +Options <#commoncmakeoptions>`_ and `CMake Caches <#cmakecaches>`_). Now 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 (and libcxx +on macOS). Then we build the ``ALL`` target with ninja: :: - > cmake -G Ninja <cmake variables> <path to root of llvm source tree> + > cmake -B /path/to/llvm-build -G Ninja \ + -DLLVM_ENABLE_PROJECTS=clang \ + [<more cmake options>] /path/to/llvm-project/llvm + > ninja -Once CMake has configured your build, you can run ``ninja`` to build LLDB. +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 \ + [<more cmake options>] /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 +188,7 @@ test execution. Windows -******* +^^^^^^^ Although the following CMake variables are by no means Windows specific, they are commonly used on Windows. @@ -161,8 +221,27 @@ -DLLDB_TEST_C_COMPILER=d:\src\llvmbuild\ninja_release\bin\clang.exe^ <path to root of llvm source tree> + +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 14 2015" <cmake variables> <path to root of llvm source tree> + +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 +249,66 @@ ``/usr/include/panel.h`` exists in your system. 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. + The default is ``lldb_codesign`` (see the `Code-signing section <#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. +.. _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 <http://llvm.org/docs/AdvancedBuilds.html>`_). +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/ +<https://github.com/llvm/llvm-project/tree/master/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 LLDB from the `monorepo +<https://github.com/llvm/llvm-project>`_ (see also `Building a Distribution of +LLVM <http://llvm.org/docs/BuildingADistribution.html>`_): :: - > cmake -G "Visual Studio 14 2015" <cmake variables> <path to root of llvm source tree> + > 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 <cmake variables> <path to root of llvm source tree> + > 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 +330,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 +515,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
_______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
