From 98d93cf4087de62f707ae80ea0bde81d9edae26d Mon Sep 17 00:00:00 2001 From: Ilija Tovilo Date: Tue, 20 Feb 2024 13:01:58 +0100 Subject: [PATCH 1/2] Add vscode chapter to docs --- docs/source/index.rst | 1 + docs/source/introduction/ides/index.rst | 10 ++ .../introduction/ides/visual-studio-code.rst | 131 ++++++++++++++++++ 3 files changed, 142 insertions(+) create mode 100644 docs/source/introduction/ides/index.rst create mode 100644 docs/source/introduction/ides/visual-studio-code.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index f800042275383..667f761497be4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,6 +7,7 @@ :hidden: introduction/high-level-overview + introduction/ides/index .. toctree:: :caption: Core diff --git a/docs/source/introduction/ides/index.rst b/docs/source/introduction/ides/index.rst new file mode 100644 index 0000000000000..e12e0d5c7ccd0 --- /dev/null +++ b/docs/source/introduction/ides/index.rst @@ -0,0 +1,10 @@ +###### + IDEs +###### + +.. toctree:: + :hidden: + + visual-studio-code + +Here you can find instructions on how to effectively use common IDEs for php-src development. diff --git a/docs/source/introduction/ides/visual-studio-code.rst b/docs/source/introduction/ides/visual-studio-code.rst new file mode 100644 index 0000000000000..e74b2c88292e5 --- /dev/null +++ b/docs/source/introduction/ides/visual-studio-code.rst @@ -0,0 +1,131 @@ +#################### + Visual Studio Code +#################### + +.. note:: + + These instructions have been tested on Linux. macOS should mostly work the same. For Windows, + ymmv. + +An IDE can make navigating large code bases tremendously easier. Visual Studio Code is a popular and +free IDE that is well-suited for C development. It contains syntax highlighting, navigation, +auto-completion and a debugger. Check the `official website `__ for +installation instructions. + +.. note:: + + The ``settings.json`` file referenced below can be opened in the Settings page by pressing the + "Open Settings (JSON)" button in the top right corner. Most of these settings can also be + adjusted through the GUI. + +***************** + C/C++ extension +***************** + +The `C/C++ extension`_ provides most of the features we'll need to php-src development. You can find +it in the extensions marketplace. You will also need ``gcc`` or ``clang`` installed. The extension +will mostly work out of the box, but it is advisable to use the ``compile_commands.json`` file. It +contains a list of all compiled files, along with the commands used to compile them. It provides the +extension with the necessary information about include paths and other compiler flags. + +.. _c/c++ extension: https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools + +To generate the ``compile_commands.json`` file, you can use the compiledb_ tool. Install it using +``pip``, and then prefix your ``make`` command accordingly: + +.. _compiledb: https://github.com/nickdiego/compiledb + +.. code:: bash + + # Install compiledb + pip install compiledb + # Compile php-src and generate compile_commands.json + compiledb make -j8 + +To tell the C/C++ extension to use the ``compile_commands.json`` file, add the following to your +``settings.json`` file: + +.. code:: json + + { + "C_Cpp.default.compileCommands": "${workspaceFolder}/compile_commands.json" + } + +******** + clangd +******** + +The C/C++ extension usually works well enough. Some people find that ``clangd`` works better. +``clangd`` is a language server built on-top of the ``clang`` compiler. It only provides navigation +and code completion but no syntax highlighting and no debugger. As such, it should be used in +conjunction with the C/C++ extension. For the two extensions not to clash, add the following to your +``settings.json`` file: + +.. code:: json + + { + "C_Cpp.intelliSenseEngine": "disabled" + } + +Follow the `official installation instructions for clangd +`__, and then install the `clangd extension`_. +Alternatively, you can let the extension install ``clangd`` for you. ``clangd`` requires a +``compile_commands.json`` file, so make sure to follow the instructions from the previous section. +By default, ``clangd`` will auto-include header files. php-src headers are somewhat peculiar, so you +might want to disable this option in your ``settings.json`` file: + +.. _clangd extension: https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd + +.. code:: json + + { + "clangd.arguments": [ + "-header-insertion=never" + ] + } + +***** + gdb +***** + +The C/C++ extension provides the ability to Visual Studio Code as a frontend for ``gdb``. Of course, +you will need ``gdb`` installed on your system. Copy the following into your projects +``.vscode/launch.json`` file: + +.. code:: json + + { + "version": "0.2.0", + "configurations": [ + { + "name": "(gdb) Launch", + "type": "cppdbg", + "request": "launch", + "program": "${workspaceFolder}/sapi/cli/php", + "args": [ + // Any options you want to test with + // "-dopcache.enable_cli=1", + "${relativeFile}", + ], + "stopAtEntry": false, + "cwd": "${workspaceFolder}", + // Useful if you build with --enable-address-sanitizer + "environment": [ + { "name": "USE_ZEND_ALLOC", "value": "0" }, + { "name": "USE_TRACKED_ALLOC", "value": "1" }, + { "name": "LSAN_OPTIONS", "value": "detect_leaks=0" }, + ], + "externalConsole": false, + "MIMode": "gdb", + "setupCommands": [ + { "text": "source ${workspaceFolder}/.gdbinit" }, + ] + } + ] + } + +Set any breakpoint, open a ``php`` (or ``phpt``) file and start debugging from the "Run and Debug" +tab in the sidebar. + +.. + _todo: lldb should work mostly the same, I believe. It's available by default on macOS, and as such might be more convenient. From 4f206b19c47e36b0711c3c76e59c429f7e7564ce Mon Sep 17 00:00:00 2001 From: Ilija Tovilo Date: Tue, 20 Feb 2024 13:32:55 +0100 Subject: [PATCH 2/2] Fix typo --- docs/source/introduction/ides/visual-studio-code.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/introduction/ides/visual-studio-code.rst b/docs/source/introduction/ides/visual-studio-code.rst index e74b2c88292e5..9bd92cae2d67c 100644 --- a/docs/source/introduction/ides/visual-studio-code.rst +++ b/docs/source/introduction/ides/visual-studio-code.rst @@ -88,8 +88,8 @@ might want to disable this option in your ``settings.json`` file: gdb ***** -The C/C++ extension provides the ability to Visual Studio Code as a frontend for ``gdb``. Of course, -you will need ``gdb`` installed on your system. Copy the following into your projects +The C/C++ extension provides the ability to use Visual Studio Code as a frontend for ``gdb``. Of +course, you will need ``gdb`` installed on your system. Copy the following into your projects ``.vscode/launch.json`` file: .. code:: json