bazel compile commands extractor

Hedron的编译命令提取器 - 用户界面

这个项目试图为我做什么？

首先，为C语言家族（C ++，C，Objective-C，Objective-C ++和CUDA）提供Bazel用户跨平台自动完成，从而使开发更加有效和有趣！

更一般而言，导出Bazel在compile_commands.json格式中构建了动作，该格式使得能够与Bazel解耦。

使用视觉效果

▲提取compile_commands.json ，在编辑器中启用clangd autocomplet

地位

只有非常小的粗糙边缘非常好。我们每天都使用它并喜欢它。

如果有一段时间没有提交，那是由于稳定而不是忽视。这是在Hedron内的日常使用。

对于日常使用，我们建议使用此此功能而不是平台特定的IDE适配器（例如TULSI或ASWB/CLION插件的工作范围），除非您需要一些需要某些平台特定功能（例如Apple的NextStep Interface Buolder）（例如，苹果的NextStep Interface Buolder）在交叉分配图编辑器中都不会支持这些功能。

外部推荐

有很多人使用此工具。其中包括大型公司和具有棘手堆栈的项目，例如机器人技术。

我们包括他们说的几件事。我们希望他们也能给您足够的信心，可以尝试一下此工具！

“感谢您的出色工具！超级设置和使用。” - 波士顿动力学的机器人工程师

“感谢您在某个无趣的工具项目中表现出如此严格的表现。这绝对感觉就像是通过指挥棒/火炬的时刻。我对生活中所做的一切的最大祝福。” - 此类以前最佳工具的作者

用法

基本设置时间：10m

Howdy，Bazel用户？让我们通过为C语言家族提供一些很棒的工具来让您快速设置。

这里有很多文字，但这仅仅是因为我们试图阐明事情并使它们变得容易。如果您有问题，请告诉我们；我们希望您的帮助使事情变得更好，更完整 - 我们很乐意为您提供帮助！

首先，将此工具添加到您的Bazel设置中。

如果您有一个模块。Bazel文件，并且正在使用新的BZLMOD系统

将其复制到您的MODULE.bazel中。Bazel，确保根据以下说明更新到最新提交。

 # Hedron's Compile Commands Extractor for Bazel
# https://github.com/hedronvision/bazel-compile-commands-extractor
bazel_dep ( name = "hedron_compile_commands" , dev_dependency = True )
git_override (
    module_name = "hedron_compile_commands" ,
    remote = "https://github.com/hedronvision/bazel-compile-commands-extractor.git" ,
    commit = "0e990032f3c5a866e72615cf67e5ce22186dcb97" ,
    # Replace the commit hash (above) with the latest (https://github.com/hedronvision/bazel-compile-commands-extractor/commits/main).
    # Even better, set up Renovate and let it do the work for you (see "Suggestion: Updates" in the README).
)

如果您使用的是传统工作区系统

将其复制到Bazel WORKSPACE文件的顶部，确保根据以下说明更新到最新提交。将其放在顶部将阻止其他工具用旧版本抓住其任何依赖性；我们保证将保持依赖版本的最新状态。

 load ( "@bazel_tools//tools/build_defs/repo:http.bzl" , "http_archive" )


# Hedron's Compile Commands Extractor for Bazel
# https://github.com/hedronvision/bazel-compile-commands-extractor
http_archive (
    name = "hedron_compile_commands" ,

    # Replace the commit hash (0e990032f3c5a866e72615cf67e5ce22186dcb97) in both places (below) with the latest (https://github.com/hedronvision/bazel-compile-commands-extractor/commits/main), rather than using the stale one here.
    # Even better, set up Renovate and let it do the work for you (see "Suggestion: Updates" in the README).
    url = "https://github.com/hedronvision/bazel-compile-commands-extractor/archive/0e990032f3c5a866e72615cf67e5ce22186dcb97.tar.gz" ,
    strip_prefix = "bazel-compile-commands-extractor-0e990032f3c5a866e72615cf67e5ce22186dcb97" ,
    # When you first run this tool, it'll recommend a sha256 hash to put here with a message like: "DEBUG: Rule 'hedron_compile_commands' indicated that a canonical reproducible form can be obtained by modifying arguments sha256 = ..."
)
load ( "@hedron_compile_commands//:workspace_setup.bzl" , "hedron_compile_commands_setup" )
hedron_compile_commands_setup ()
load ( "@hedron_compile_commands//:workspace_setup_transitive.bzl" , "hedron_compile_commands_setup_transitive" )
hedron_compile_commands_setup_transitive ()
load ( "@hedron_compile_commands//:workspace_setup_transitive_transitive.bzl" , "hedron_compile_commands_setup_transitive_transitive" )
hedron_compile_commands_setup_transitive_transitive ()
load ( "@hedron_compile_commands//:workspace_setup_transitive_transitive_transitive.bzl" , "hedron_compile_commands_setup_transitive_transitive_transitive" )
hedron_compile_commands_setup_transitive_transitive_transitive ()

无论哪种方式：通过翻新来获取更新

改进经常出现，因此我们建议保持最新状态。

我们强烈建议您在某个时候设置翻新（或类似）的装修（或类似），以默认情况下保持这种依赖性（和其他）。 [我们没有隶属于翻新或其他任何东西，但我们认为这很棒。它观看新版本，并向您发送PRS以进行审查或自动测试。它是免费的，易于设置。它在我们的代码库中非常有用，我们已经与出色的维护者合作，使其非常适合Bazel使用。它用于官方Bazel存储库。]这是我们一个项目中的翻新配置示例，希望它可以节省您的时间。

如果不是现在，也许稍后再回到此步骤，或者观看此存储库以获取更新。 [或者，当您在考虑观看时，也许给我们一个快速的明星。]像Abseil一样，我们住在头上；主要分支的最新提交是您想要的提交。因此，不要依靠发布通知；使用翻新或手动进行新的提交。

其次，让提取器运行。

我们将在Bazel Workspace的根部生成compile_commands.json文件。

该文件描述了Bazel如何编译所有（Objective-）C（++）或CUDA文件。借助公共格式的编译命令，独立于构建系统的工具（例如clangd Autococtlete， clang-tidy linting等）可以使用。

我们将其运行，然后在下一个部分旋转时移至下一个部分。但是将来，每当您想要工具（例如自动完成）以查看新的BUILD - 文件更改时，请重新运行您在下面选择的命令！ Clangd将自动拾取更改。

有四个常见路径：

1。具有相对简单的代码库，每个目标都在不需要任何其他配置或标志的情况下构建.bazelrc中的任何其他配置或标志？

在这种情况下，只需bazel run @hedron_compile_commands//:refresh_all

注意：您必须bazel run此工具，而不仅仅是bazel build它。

2。是否有bazel标志，例如--config=my_important_flags_or_toolchains --compilation_mode=dbg ，您在开发时手动应用于所有构建？

运行此工具时，也要提供相同的Bazel标志很重要，因此我们可以准确地了解构建，生成文件的位置，等等。

append，例如-- --config=my_important_flags_or_toolchains --compilation_mode=dbg ，或者在开发时通常使用的任何标志。

注意：额外--不是错字，并且在运行时将标志传递给该工具而不是构建时的功能。您的命令应该看起来像：

bazel run @hedron_compile_commands//:refresh_all -- --config=my_important_flags_or_toolchains --compilation_mode=dbg

3。通常，您需要指定顶级，输出目标您关心的目标和/或他们单独需要的标志。这避免了无法自行建立某些目标的问题；他们需要在命令行或父规则上进行配置。后者的一个示例是Android_library，它可能不能独立于配置它的Android_binary构建。

在这种情况下，您可以轻松地指定您正在使用的顶级，输出目标以及构建它们所需的标志。

打开一个BUILD文件 - 建议使用（或创建） //BUILD - 并添加类似的内容：

 load ( "@hedron_compile_commands//:refresh_compile_commands.bzl" , "refresh_compile_commands" )

refresh_compile_commands (
    name = "refresh_compile_commands" ,

    # Specify the targets of interest.
    # For example, specify a dict of targets and any flags required to build.
    targets = {
      "//:my_output_1" : "--important_flag1 --important_flag2=true" ,
      "//:my_output_2" : "" ,
    },
    # No need to add flags already in .bazelrc. They're automatically picked up.
    # If you don't need flags, a list of targets is also okay, as is a single target string.
    # Wildcard patterns, like //... for everything, *are* allowed here, just like a build.
      # As are additional targets (+) and subtractions (-), like in bazel query https://docs.bazel.build/versions/main/query.html#expressions
    # And if you're working on a header-only library, specify a test or binary target that compiles it.
)

（有关refresh_compile_commands的更多详细信息，请查看refresh_compile_commands.bzl顶部的文档）。

最后，您需要进行bazel run :refresh_compile_commands

4.使用ccls或其他工具，这些工具与clangd不同，不需要或需要compile_commands.json中的标题？

与上面的类似，我们将使用refresh_compile_commands进行配置，但是不是设置targets ，而是设置exclude_headers = "all" 。

如果您有一个非常大的项目，并且compile_commands.json需要一段时间来生成：

添加exclude_external_sources = True and exclude_headers = "external"可以在某些权衡方面有所帮助。

目前，我们建议继续设置clangd （下图）。此后，如果您的项目被证明足够大，可以扩展clangd和/或此工具快速索引的能力，请查看refresh_compile_commands.bzl的文档，以获取有关如何调整这些标志和其他人的说明。

编辑设置 - 用于基于compile_commands.json的自动完成

VSCODE

让我们安装和配置clangd的扩展名。

code --install-extension llvm-vs-code-extensions.vscode-clangd
# We also need make sure that Microsoft's C++ extension is not involved and interfering.
code --uninstall-extension ms-vscode.cpptools

然后，打开VSCODE用户设置，因此将自动为您打开的所有项目设置情况。

搜索“ clangd”。

将以下三个单独的条目添加到"clangd.arguments" ：

--header-insertion=never
--compile-commands-dir= ${workspaceFolder} /
--query-driver= **

（只需按${workspaceFolder}复制每个；

• 他们摆脱了（过度狂热的）标头插入；即使浏览源树外面的系统标头，也可以正确找到编译命令。并导致clangd询问Bazel的编译器包装器，以找出默认情况下包含哪些系统标头。
• 如果您的Bazel WORKSPACE是您项目的子目录，则通过覆盖工作区设置中的标志来更改--compile-commands-dir指向该子目录。覆盖时，您需要重新指定所有标志，因为工作区设置替换了用户设置中的所有标志。

打开：clangd：检查更新

• 您总是想要最新的！新的伟大功能和修复程序总是会添加到Clangd。
• 我们假设您始终拥有最新的内容，并且不使用旧版本也不使用Apple的clangd用于Xcode。尽管我们可以并且确实竭尽全力在当前版本的clangd中解决解决问题，但当clangd将它们修复到上游时，我们将删除这些解决方法。这使代码保持简单，开发速度快速！

如果打开自动更新不会提示您下载实际的clangd Server二进制文件，请点击（CMD/CTRL+Shift+P） - >下载语言服务器。

您可能需要随后重新加载VSCODE [（CMD/CTRL+SHIFT+P） - > Reload]才能加载插件。 clangd下载应提示您完成后。

如果您与其他人一起工作...

...并希望这些设置自动为队友应用，也将设置添加到VSCODE工作区设置中，然后将.vscode/settings.json检查到源控制中。

其他编辑

如果您使用的是另一个编辑器，则需要遵循与上述相同的粗略步骤：获取最新版本的Clangd设置以扩展编辑器，然后提供与VSCODE相同的标志。我们知道人们很容易与其他编辑器（例如Emacs和vim+YouCompleteme（YCM））设置此工具。

一旦您成功设置了另一个编辑器或设置clang-tidy或以其他方式看到任何可能改善此读数的内容，我们就会喜欢它，如果您回馈并贡献您所知道的一切！只需在github上编辑此README.md并提交PR :)

“平滑边缘” - 我们喜欢使用它

您现在应该全力以赴！通过设置使其实现。

工作空间的根部中应该有一个compile_commands.json文件，使您的编辑器能够提供出色的，基于clang的自动完成。而且，当您将BUILD - 文件更大的变化大大以需要刷新时，您应该知道bazel run刷新该自动完成的。

在幕后，该compile_commands.json文件包含描述所有用于构建项目中每个源文件的命令的条目。而且，目前，每个标题也有一个条目，描述了它的一种编译方式。 （这也使您在标头文件中也可以自动完成，因此您不必考虑clangd的最大粗糙边缘）。至关重要的是，所有这些命令都已经充分拆除了叮当的工具（或您！）以理解它们。

根据我们的经验，这是您应该期望的：

我们每天使用此工具为MACOS上的iOS和Android开发一个跨平台库。期望Android源，MACOS中的MACOS，iOS中的MACOS，iOS等。人们也将其在Linux/Ubuntu和Windows上使用。

所有通常的clangd功能都应起作用。 cmd/ctrl+单击导航（或选项，如果您更改了键键），智能重命名，自动完成，突出显示等。您期望在IDE中期望的一切都应该存在（因为大多数好的IDE都由clangd支持）。一般原则：如果您选择需要了解编程语言的工具，则希望它基于该语言的编译器前端，而Clangd是LLVM/Clang项目的一部分。

一切也应该适用于生成的文件，尽管您可能必须运行一个构建才能存在生成的文件。如果您使用远程执行或缓存使用此功能，则可能必须使用--remote_download_regex将标题和源文件拉下并避免在编辑器中避免错误，现在构建没有字节（ --remote_download_toplevel ）是Bazel default。如果您努力工作，如果您还要回馈并提交PR为其他所有人添加良好的说明，或者至少要分享您在问题中学到的知识，我们会很喜欢。您还需要在非窗口上下拉 *.d依赖项文件；他们让我们在缓存时找到标题更快。我们很感激您是否还要检查以确保即使没有（ --noexperimental_inmemory_dotd_files ）即使将其拉下来。感谢您的帮助！

粗糙的边缘

否则，我们将为我们所了解和正在跟踪的粗糙边缘提供自养问题。我们很想听听您在那里看到的东西，好与坏。如果您发现更多粗糙的边缘，请添加内容，并告诉我们您是否需要帮助或更多功能。

另一方面，如果您已经设置了问题并且运行良好，我们仍然很想收到您的来信。请在描述您的成功的“问题”选项卡中提交“非问题”！我们很想听听您在从事的工作，您正在使用的平台以及您发现最有用的东西。也许我们的方式也扔了一颗星星，所以我们知道这对您有帮助。

当然，我们还希望与您一起进行贡献和改进！开发设置很容易，不是繁重的。我们有一个很棒的文档，可以很快地指导您能够进行所需的更改。代码库超级干净，友好。介入代码是获得所需改进的一种有趣而有效的方法。

---

其他可能感兴趣的项目

如果您正在为C语言家族使用Bazel，则可能还需要我们的其他一些工具，例如...

1. 制作安全网络请求的一种好方法：Hedronvision/Bazel-Make-Make-Make-CC-HTTPS-Easy
2. 跨平台使用std ::文件系统的一种方法：Hedronvision/Bazel-cc-filesystem-backport

---

寻找实施详细信息？想潜入代码库吗？请参阅ImparionationReadMe.md。

Bazel/Blaze维护者阅读此书吗？如果您有兴趣将其集成到官方的Bazel工具中，请在问题或电子邮件中告诉我们，让我们谈谈！我们喜欢使用Bazel，很乐意提供帮助。