bazel compile commands extractor
1.0.0
Что этот проект пытается сделать для меня?
Во-первых, предоставьте кроссплатформенное автоплатформенное автозаполнение пользователей Bazel для семейства языков C (C ++, C, объектив-C, Objective-C ++ и CUDA) и, тем самым сделать разработку более эффективной и веселой!
В более общем плане, экспорт Bazel строит действия в формат compile_commands.json , который позволяет отличным инструментам, отделенным от Bazel.
▲ Извлекать compile_commands.json , включив автозаполнение clangd в вашем редакторе ▼
Довольно здорово с очень незначительными грубыми краями. Мы используем это каждый день и любим это.
Если некоторое время не было, это из -за стабильности, а не пренебрежения. Это в ежедневном использовании внутри Хедрона.
Для повседневного использования мы рекомендуем использовать это, а не адаптеры IDE, специфичные для платформы (такие как Tulsi или плагин ASWB/Clion в той мере, в какой степени он работает), за исключением времени, когда вам нужна какая-то функция, специфичная для платформы (например, строитель интерфейса Apple), которая никогда не поддерживается в редакторе Cross-Platform.
Есть много людей, использующих этот инструмент. Это включает в себя крупные компании и проекты с хитрыми стеками, как в робототехнике.
Мы включаем пару вещей, которые они сказали. Мы надеемся, что они дадут вам достаточную уверенность, чтобы попробовать этот инструмент!
«Спасибо за отличный инструмент! Супер легко настроить и использовать». - Инженер робототехники в Бостонской динамике
«Спасибо за то, что показали столько строгости в том, что в противном случае было бы просто неинтересным проектом по инструментам. Это определенно похоже на момент прохождения эстафеты/факела. Мои наилучшие пожелания всего, что вы делаете в жизни». - Автор предыдущего лучшего инструмента такого типа
Основное время настройки: 10 м
Привет, пользователь Bazel? Давайте быстро настроим вас с некоторыми потрясающими инструментами для семейства языков C.
Здесь есть куча текста, но только потому, что мы пытаемся что -то изложить и облегчить их. Если у вас есть проблемы, дайте нам знать; Мы хотели бы, чтобы ваша помощь сделала вещи еще лучше и более полной - и мы хотели бы помочь вам!
Скопируйте это в свой MODULE.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 ()Усовершенствования приходят часто, поэтому мы рекомендуем быть в курсе.
Мы настоятельно рекомендуем вам настроить Renovate (или аналогичный) в какой-то момент, чтобы по умолчанию поддерживать эту зависимость (и другие). [Мы не связаны с ремонтом или чем -то еще, но мы думаем, что это круто. Он наблюдает за новыми версиями и отправляет вам PRS для просмотра или автоматического тестирования. Это бесплатно и легко настроить. Это было поразительно полезно в нашей кодовой базе, и мы работали с замечательным сопровождающим, чтобы сделать все отлично для использования Bazel. И он используется в официальных репозиториях Bazel.] Вот пример отремонтирования конфигурации из одного из наших проектов, в надежде, что это может сэкономить ваше время.
Если нет сейчас, возможно, вернитесь к этому шагу позже или посмотрите эту репо для обновлений. [Или эй, может быть, дайте нам быструю звезду, пока вы думаете о просмотре.] Как и Абсейл, мы живем в голове; Последний коммит в основной филиале - это коммит, который вы хотите. Так что не полагайтесь на уведомления о выпуске; Используйте ремонт или опрос вручную для новых коммитов.
Мы создадим файл compile_commands.json в корне рабочего пространства Bazel.
Этот файл описывает, как Bazel компилирует все файлы (Objective-) C (++) или CUDA. Благодаря командам компиляции в общем формате, независимых от сборки, независимого от инструментов (например, clangd AutoComplete, clang-tidy Linting и т. Д.), Может прийти к работе.
Мы запустим его, а затем перейдем к следующему разделу, пока он уходит. Но в будущем каждый раз, когда вы хотите, чтобы инструмент (например, автозаполнение), чтобы увидеть новые изменения в BUILD , повторно затроните команду, которую вы выбрали ниже! Clangd автоматически заберут изменения.
В этом случае Just bazel run @hedron_compile_commands//:refresh_all
ПРИМЕЧАНИЕ: вы должны bazel run этот инструмент, а не только bazel build его.
--config=my_important_flags_or_toolchains --compilation_mode=dbg , что вы применяете вручную ко всем своими сборками во время разработки?Вполне важно, чтобы вы также предоставили те же самые флаги базеля при запуске этого инструмента, чтобы мы могли точно понять сборку, где генерируются файлы и т. Д.
Приложение, например -- --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
В этом случае вы можете легко указать целевые показатели верхнего уровня, вы работаете, и флаги, необходимые для их построения.
Откройте файл 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
ccls или другого инструмента, который, в отличие от clangd , не хочет или не нуждаются в заголовках в compile_commands.json ? Подобно вышеуказанно, мы будем использовать refresh_compile_commands для конфигурации, но вместо установления targets установите exclude_headers = "all" .
compile_commands.json требует некоторого времени, чтобы генерировать: Добавление exclude_external_sources = True и exclude_headers = "external" может помочь, с некоторыми компромиссами.
На данный момент мы бы предложили продолжить настроить clangd (ниже). После этого, если вы, ваш проект, оказывается достаточно большим, что он увеличивает способность clangd и/или этот инструмент быстро индексировать, взгляните на документы на вершине refresh_compile_commands.bzl для инструкций о том, как настроить эти флаги и другие.
compile_commands.json Давайте установим и настроен расширение 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= ** (Просто скопируйте каждый, как написано; VSCODE правильно расширит ${workspaceFolder} для каждого рабочего пространства.)
clangd допросить обертки компилятора Bazel, чтобы выяснить, какие заголовки системы включены по умолчанию.WORKSPACE Bazel является подкаталогом вашего проекта, изменить --compile-commands-dir чтобы указать на этот подкаталог, переопределив флаги в настройках рабочей области . Вам нужно будет повторно определить все флаги при переопределении, потому что настройки рабочего пространства заменяют все флаги в настройках пользователя.Включите: clangd: проверьте обновления
clangd Apple, предназначенную для XCode. В то время как мы можем и прилагаем большие усилия для обходных проблем в текущей версии clangd , мы удаляем эти обходные пути, когда clangd исправляет их вверх по течению. Это делает код простой и скоростью развития быстро! Если включение автоматических обновлений не заставляет вас загружать фактический бинар clangd Server, HIT (CMD/CTRL+SHIFT+P)-> Загрузить языковой сервер.
Возможно, вам потребуется впоследствии перезагрузить vscode [(cmd/ctrl+shift+p)-> перезагрузить] для загрузки плагина. Загрузка clangd должна побудить вас сделать это, когда она завершается.
... и хотел бы, чтобы эти настройки были автоматически применены для ваших товарищей по команде, также добавьте настройки в настройки рабочего пространства VSCODE, а затем проверяйте .vscode/settings.json в управление источником.
Если вы используете другого редактора, вам нужно будет выполнить те же грубые шаги, что и выше: Получите последнюю версию Clangd настроить, чтобы расширить редактор, а затем предоставить те же флаги, что и VSCODE. Мы знаем, что у людей было легко настроить этот инструмент с другими редакторами, например, Emacs и Vim+YouCompleteme (YCM), например.
После того, как вам удастся настроить другого редактора-или настроить clang-tidy , или иным образом увидеть что-то, что может улучшить этот Readme,-мы хотели бы его, если бы вы отдали и внесли свой вклад в то, что вы знаете! Просто отредактируйте этот README.md на GitHub и подайте пиар :)
Теперь вы должны быть готовы к работе! Способ сделать это через настройку.
Должен быть файл compile_commands.json в корне вашего рабочего пространства, что позволяет вашему редактору предоставить отличное автозаполнение на основе кланг. И вы должны знать, какую цель bazel run , чтобы обновить это автозаполнение, когда вы вносите изменения в BUILD , достаточно большие, чтобы потребовать обновления.
За кулисами этот файл compile_commands.json содержит записи, описывающие все команды, используемые для создания каждого исходного файла в вашем проекте. И пока есть также одна запись на заголовок, описывающий один из способов, которые она скомпилирована. (Это также дает вам отличную автозаполнение в файлах заголовков, поэтому вам не нужно думать о самых грубых краях clangd ). Важно отметить, что все эти команды были в достаточной степени отменены для инструментов Clang (или вас!), Чтобы понять их.
Мы используем этот инструмент каждый день для разработки кроссплатформенной библиотеки для iOS и Android на MacOS. Ожидайте завершения Android в Android Source, MacOS в MacOS, iOS в iOS и т. Д. Люди используют его на Linux/Ubuntu и Windows.
Все обычные функции Clangd должны работать. CMD/CTRL+Нажмите навигацию (или опцию, если вы изменили соединения клавиш), Smart Ername, автозаполнение, выделение и т. Д. Все, что вы ожидаете в IDE, должно быть там (потому что большинство хороших IDE поддерживаются clangd ). В качестве общего принципа: если вы выбираете инструмент, который должен понимать язык программирования, вы хотите, чтобы он основывался на фронте компилятора для этого языка, который Clangd делает как часть проекта LLVM/Clang.
Все должно также работать для сгенерированных файлов, хотя вам, возможно, придется запустить сборку для существования сгенерированного файла. Если вы используете это с удаленным выполнением или кэшем, вам, вероятно, придется использовать --remote_download_regex , чтобы стянуть заголовок и исходные файлы и избежать ошибок в редакторе, теперь это строительство без байтов ( --remote_download_toplevel ) является по умолчанию Bazel. Если вы проработаете это, нам понравится, если бы вы вернули и подали пиар, добавляя хорошие инструкции для всех остальных -или, по крайней мере, поделитесь тем, что вы узнали в проблеме. Вы также захотите потянуть файлы зависимости *.d на не-окне; Они позволяют нам найти заголовки намного быстрее, когда они доступны в качестве кеша. Мы будем признателен, если вы также проверили, чтобы убедиться, что они сняты даже без ( --noexperimental_inmemory_dotd_files ). Спасибо за помощь!
В противном случае у нас есть проблемы с самостоятельностью для грубых краев, о которых мы знаем и отслеживаем. Мы хотели бы услышать от вас о том, что вы видите, хорошо и плохо. Пожалуйста, добавьте вещи, если вы найдете больше грубых краев, и дайте нам знать, если вам нужна помощь или больше функций.
С другой стороны, если вы настроили вещи, и они работают хорошо, мы все равно хотели бы услышать от вас. Пожалуйста, подайте «не проблема» на вкладку «Проблемы», описывающая ваш успех! Мы хотели бы услышать, над чем вы работаете, какие платформы вы используете, и что вы находите наиболее полезным. И, возможно, также бросьте звезду по нашему пути, чтобы мы знали, что это было полезно для вас.
Конечно, мы также хотели бы работать с вами над вкладами и улучшениями! Настройка разработки легко, а не обременительно; У нас есть отличный док, который быстро поможет вам внести необходимые вам изменения. Кодовая база очень чистая и дружелюбная. Вступление в код - это забавный и эффективный способ получить необходимые улучшения.
Если вы используете Bazel для семейства языков C, вы, вероятно, также захотите некоторые другие наши инструменты, такие как ...
Вместо этого ищете детали реализации? Хотите погрузиться в кодовую базу? См. Реализация readureD.md.
Bazel/Blaze Savingerter читает это? Если вы будете заинтересованы в интеграции этого в официальные инструменты Bazel, сообщите нам об этом в проблеме или электронной почте, и давайте поговорим! Мы любим использовать Bazel и хотели бы помочь.
