From a40c0b3bf8c308fed86e7f3d6de88fef516e67d7 Mon Sep 17 00:00:00 2001 From: ykiko Date: Mon, 6 Apr 2026 15:51:46 +0800 Subject: [PATCH] docs: expand compilation database generation guide (#401) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Fill in Visual Studio, Makefile, Meson sections (previously TODO) - Expand Xmake section with CLI and VSCode extension workflows - Simplify Others section to recommend [catter](https://github.com/clice-io/catter) - Fix CJK-Latin spacing in Chinese docs - English and Chinese docs updated in sync Supersedes #313 by @Stehsaer. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Stehsaer Co-authored-by: Claude Opus 4.6 (1M context) --- docs/en/guide/quick-start.md | 65 ++++++++++++++++++++++++++++++++++-- docs/zh/guide/quick-start.md | 65 ++++++++++++++++++++++++++++++++++-- 2 files changed, 124 insertions(+), 6 deletions(-) diff --git a/docs/en/guide/quick-start.md b/docs/en/guide/quick-start.md index 03886ffb..a396b60c 100644 --- a/docs/en/guide/quick-start.md +++ b/docs/en/guide/quick-start.md @@ -54,14 +54,73 @@ bazel run @hedron_compile_commands//:refresh_all ### Visual Studio -TODO: +Visual Studio (2019 16.1+) can generate a compilation database via CMake integration. Open your project as a CMake project, then configure the generation in `CMakeSettings.json`: + +```json +{ + "configurations": [ + { + "name": "x64-Debug", + "generator": "Ninja", + "buildRoot": "${projectDir}\\build", + "cmakeCommandArgs": "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON" + } + ] +} +``` + +Alternatively, for MSBuild-based projects (`.vcxproj`), you can use [compiledb-vs](https://github.com/pjbroad/compiledb-vs) or [catter](https://github.com/clice-io/catter) to generate the compilation database. ### Makefile -TODO: +For Makefile-based projects, use [bear](https://github.com/rizsotto/Bear) to intercept compilation commands: + +```bash +bear -- make +``` + +This will generate a `compile_commands.json` in the current directory. Note that `bear` requires a clean build to capture all commands — run `make clean` before `bear -- make` if needed. + +Alternatively, if you use GNU Make, you can use [compiledb](https://github.com/nicktimko/compiledb): + +```bash +compiledb make +``` + +### Meson + +Meson generates a compilation database automatically during setup: + +```bash +meson setup build +``` + +The `compile_commands.json` will be in the `build` directory. ### Xmake +Use one of the following approaches to generate a compilation database. + +#### Command Line + +Run the following command to manually generate a compilation database: + +```bash +xmake project -k compile_commands --lsp=clangd build +``` + +> Compilation database generated manually doesn't automatically update itself. Re-generate if changes are made to the project. + +#### VSCode Extension + +The Xmake official VSCode extension automatically generates the compilation database when `xmake.lua` is updated. However, it generates the database to the `.vscode` directory by default. Add this setting in `settings.json`: + +```json +"xmake.compileCommandsDirectory": "build" +``` + +to explicitly ask the extension to generate the compilation database in `build`. + ### Others -For any other build system, you can try using [bear](https://github.com/rizsotto/Bear) or [scan-build](https://github.com/rizsotto/scan-build) to intercept compilation commands and obtain the compilation database (no guarantee of success). We plan to write a **new tool** in the future that captures compilation commands through a fake compiler approach. +For any other build system, you can use [catter](https://github.com/clice-io/catter) to generate a compilation database. It captures compilation commands through a fake compiler approach and is designed to work reliably with any build system that invokes a compiler executable. diff --git a/docs/zh/guide/quick-start.md b/docs/zh/guide/quick-start.md index 04485d8a..bb10ecde 100644 --- a/docs/zh/guide/quick-start.md +++ b/docs/zh/guide/quick-start.md @@ -54,14 +54,73 @@ bazel run @hedron_compile_commands//:refresh_all ### Visual Studio -TODO: +Visual Studio（2019 16.1+）可以通过 CMake 集成来生成编译数据库。将项目作为 CMake 项目打开，然后在 `CMakeSettings.json` 中配置： + +```json +{ + "configurations": [ + { + "name": "x64-Debug", + "generator": "Ninja", + "buildRoot": "${projectDir}\\build", + "cmakeCommandArgs": "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON" + } + ] +} +``` + +对于基于 MSBuild 的项目（`.vcxproj`），可以使用 [compiledb-vs](https://github.com/pjbroad/compiledb-vs) 或 [catter](https://github.com/clice-io/catter) 来生成编译数据库。 ### Makefile -TODO: +对于基于 Makefile 的项目，使用 [bear](https://github.com/rizsotto/Bear) 来拦截编译命令： + +```bash +bear -- make +``` + +这会在当前目录生成 `compile_commands.json`。注意 `bear` 需要干净的构建来捕获所有命令——如果需要的话，在运行 `bear -- make` 之前先执行 `make clean`。 + +另外，如果使用 GNU Make，也可以使用 [compiledb](https://github.com/nicktimko/compiledb)： + +```bash +compiledb make +``` + +### Meson + +Meson 在配置阶段会自动生成编译数据库： + +```bash +meson setup build +``` + +`compile_commands.json` 会生成在 `build` 目录下。 ### Xmake +用下列任意方法生成编译数据库。 + +#### 命令行手动生成 + +在命令行中执行以下命令： + +```bash +xmake project -k compile_commands --lsp=clangd build +``` + +> 通过这种方法生成的编译数据库无法自动更新，需要在项目编译配置更改时手动重新生成。 + +#### VSCode 扩展 + +Xmake 提供的官方 VSCode 扩展会在 `xmake.lua` 更新时自动生成编译数据库。然而默认情况下，它将编译数据库生成到了 `.vscode` 文件夹。在 `settings.json` 中添加以下配置： + +```json +"xmake.compileCommandsDirectory": "build" +``` + +以将编译数据库的生成目录调整到 `build`，供 clice 使用。 + ### Others -对于任意其它的构建系统，可以尝试使用 [bear](https://github.com/rizsotto/Bear) 或者 [scan-build](https://github.com/rizsotto/scan-build) 来拦截编译命令并获取到编译数据库（不保证成功）。我们计划在未来编写一个**新的工具**，通过假编译器的方式来实现编译命令的捕获。 +对于任意其它的构建系统，可以使用 [catter](https://github.com/clice-io/catter) 来生成编译数据库。它通过伪装编译器的方式来捕获编译命令，能够可靠地与任何调用编译器可执行文件的构建系统配合工作。