docs: expand compilation database generation guide (#401)

## 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 <Stehsaer@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
ykiko
2026-04-06 15:51:46 +08:00
committed by GitHub
parent d253c1f099
commit a40c0b3bf8
2 changed files with 124 additions and 6 deletions

View File

@@ -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.

View File

@@ -54,14 +54,73 @@ bazel run @hedron_compile_commands//:refresh_all
### Visual Studio
TODO:
Visual Studio2019 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) 来生成编译数据库。它通过伪装编译器的方式来捕获编译命令,能够可靠地与任何调用编译器可执行文件的构建系统配合工作