bazel compile commands extractor
1.0.0
Qu'est-ce que ce projet essaie de faire pour moi?
Tout d'abord, fournissez aux utilisateurs de Bazel une assortie automatique multiplateforme pour la famille de la langue C (C ++, C, Objective-C, Objective-C ++ et CUDA), et rendez ainsi le développement plus efficace et amusant!
Plus généralement, l'exportation de bazel entreprend des actions dans le format compile_commands.json qui permet un excellent outillage découplé de Bazel.
▲ Extrait compile_commands.json , permettant à clangd l'administration automatique dans votre éditeur ▼
Assez super avec seulement des arêtes rugueuses très mineures. Nous l'utilisons tous les jours et l'aimons.
S'il n'y a pas eu de validation depuis un moment, c'est à cause de la stabilité, pas de la négligence. Ceci est dans une utilisation quotidienne à l'intérieur de Heddron.
Pour une utilisation quotidienne, nous recommandons de l'utiliser plutôt que les adaptateurs IDE spécifiques à la plate-forme (comme Tulsi ou le plugin ASWB / Clion dans la mesure où cela fonctionne), sauf les moments où vous avez besoin d'une fonctionnalité spécifique à la plate-forme (par exemple, le constructeur d'interface NextStep d'Apple) qui ne sera jamais soutenu dans un éditeur de plateform d'Apple.
Il y a beaucoup de gens qui utilisent cet outil. Cela comprend les grandes entreprises et les projets avec des piles délicates, comme en robotique.
Nous incluons quelques choses qu'ils ont dites. Nous espérons qu'ils vous donneront suffisamment de confiance pour essayer cet outil aussi!
"Merci pour un outil génial! Super facile à configurer et à utiliser." - Un ingénieur en robotique chez Boston Dynamics
"Merci d'avoir montré tant de rigueur dans ce qui serait autrement un projet d'outillage inintéressant. - Auteur du meilleur outil précédent de ce type
Temps de configuration de base: 10m
Howdy, Bazel User ?. Faisons de vous installer rapidement avec des outils impressionnants pour la famille des langues C.
Il y a un tas de texte ici, mais uniquement parce que nous essayons d'épeler les choses et de les rendre faciles. Si vous avez des problèmes, faites-le nous savoir; Nous aimerions votre aide à rendre les choses encore meilleures et plus complètes - et nous serions ravis de vous aider!
Copiez-le dans votre MODULE.bazel , en vous assurant de mettre à jour le dernier engagement selon les instructions ci-dessous.
# 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).
) Copiez-le en haut de votre fichier WORKSPACE Bazel, en vous assurant de mettre à jour le dernier engagement selon les instructions ci-dessous. Le mettre au sommet empêchera d'autres outils de remplir l'une de ses dépendances avec des versions anciennes; Nous nous promettons de maintenir nos versions de dépendance à nos jours.
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 ()Les améliorations arrivent fréquemment, nous vous recommandons donc de rester à jour.
Nous vous recommandons fortement de configurer Renove (ou similaire) à un moment donné pour maintenir cette dépendance (et d'autres) à jour par défaut. [Nous ne sommes pas affiliés à Renovate ou quoi que ce soit, mais nous pensons que c'est génial. Il regarde pour de nouvelles versions et vous envoie des PR pour examen ou tests automatisés. C'est gratuit et facile à installer. Il a été incroyablement utile dans notre base de code, et nous avons travaillé avec le merveilleux mainteneur pour rendre les choses super pour une utilisation en bazel. Et il est utilisé dans les référentiels officiels de Bazel.] Voici un exemple de configuration de rénovation de l'un de nos projets, dans l'espoir que cela pourrait vous faire gagner du temps.
Sinon maintenant, revenez peut-être à cette étape plus tard, ou regardez ce dépôt pour les mises à jour. [Ou bon, peut-être nous donner une star rapide, pendant que vous pensez à regarder.] Comme Abseil, nous vivons à la tête; Le dernier engagement dans la branche principale est l'engagement que vous souhaitez. Alors ne comptez pas sur les notifications de libération; Utilisez rénover ou sonder manuellement pour les nouveaux engins.
Nous générerons un fichier compile_commands.json dans la racine de l'espace de travail Bazel.
Ce fichier décrit comment Bazel compile tous les fichiers (objectif-) C (++) ou CUDA. Avec les commandes de compilation dans un format commun, l'outillage indépendant du système build (par exemple, la saisie semi-automatique clangd , le libelting clang-tidy , etc.), peut se rendre au travail.
Nous allons le faire fonctionner, puis passer à la section suivante pendant qu'il tournure. Mais à l'avenir, chaque fois que vous voulez des outils (comme la saisie semi-automatique) pour voir les nouvelles modifications de BUILD , relancez la commande que vous avez choisie ci-dessous! Clangd ramassera automatiquement les modifications.
Dans ce cas, juste bazel run @hedron_compile_commands//:refresh_all
Remarque: vous devez bazel run cet outil, pas seulement bazel build .
--config=my_important_flags_or_toolchains --compilation_mode=dbg , que vous appliquez manuellement à toutes vos versions pendant le développement?Il est assez important que vous fournissiez ces mêmes drapeaux de bazel lors de l'exécution de cet outil, afin que nous puissions comprendre avec précision la construction, où les fichiers sont générés, etc.
Ajouter, par exemple -- --config=my_important_flags_or_toolchains --compilation_mode=dbg à ce qui précède, ou quels que soient les drapeaux que vous construisez normalement pendant le développement.
Remarque: Le supplément -- n'est pas une faute de frappe, et fonctionne pour passer les indicateurs à cet outil lorsqu'il s'exécute plutôt que lorsqu'il se construit. Votre commande doit ressembler:
bazel run @hedron_compile_commands//:refresh_all -- --config=my_important_flags_or_toolchains --compilation_mode=dbg
Dans ce cas, vous pouvez facilement spécifier les cibles de sortie de haut niveau sur lesquelles vous travaillez et les drapeaux nécessaires pour les construire.
Ouvrez un fichier BUILD - nous recommandons d'utiliser (ou de créer) //BUILD - et d'ajouter quelque chose comme:
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.
) (Pour plus de détails sur refresh_compile_commands , regardez les documents en haut de refresh_compile_commands.bzl ).
Enfin, vous aurez besoin de bazel run :refresh_compile_commands
ccls ou un autre outil qui, contrairement clangd , ne veut pas ou n'a pas besoin d'en-têtes dans compile_commands.json ? Semblable à ce qui précède, nous utiliserons refresh_compile_commands pour la configuration, mais au lieu de définir targets , définissez exclude_headers = "all" .
compile_commands.json prend un certain temps à générer: L'ajout exclude_external_sources = True et exclude_headers = "external" peut aider, avec certains compromis.
Pour l'instant, nous suggérons de continuer à configurer clangd (ci-dessous). Par la suite, si vous, votre projet s'avère suffisamment grand pour que cela étire la capacité de clangd et / ou de cet outil pour indexer rapidement, jetez un œil aux documents en haut de refresh_compile_commands.bzl pour des instructions sur la façon de régler ces drapeaux et autres.
compile_commands.json Faisons l'installation et la configuration de l'extension de 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.cpptoolsEnsuite, ouvrez les paramètres utilisateur VScode, afin que les choses soient automatiquement configurées pour tous les projets que vous ouvrez.
Recherchez "Clangd".
Ajoutez les trois entrées distinctes suivantes à "clangd.arguments" :
--header-insertion=never
--compile-commands-dir= ${workspaceFolder} /
--query-driver= ** (Il suffit de copier chacun comme écrit; vscode élargira correctement ${workspaceFolder} pour chaque espace de travail.)
clangd interroge les emballages du compilateur de Bazel pour déterminer quels en-têtes système sont inclus par défaut.WORKSPACE Bazel est un sous-répertoire de votre projet, modifiez --compile-commands-dir pour pointer dans ce sous-répertoire en remplaçant les drapeaux dans vos paramètres d'espace de travail . Vous devrez redéfinir tous les indicateurs lorsque vous remplacez, car les paramètres de l'espace de travail remplacent tous les indicateurs dans les paramètres de l'utilisateur.Allumez: Clangd: Vérifiez les mises à jour
clangd d'Apple destiné à Xcode. Bien que nous puissions faire et faire de grands efforts pour des problèmes de solution de contournement dans la version actuelle de clangd , nous supprimons ces solutions de contournement lorsque clangd les corrige en amont. Cela maintient le code simple et la vitesse de développement rapidement! Si l'activation des mises à jour automatiques ne vous invite pas à télécharger le binaire clangd Server réel, Hit (CMD / CTRL + Shift + P) -> Télécharger le serveur de langage.
Vous devrez peut-être par la suite de recharger VScode [(CMD / CTRL + Shift + P) -> Recharger] pour que le plugin se charge. Le téléchargement clangd devrait vous inciter à le faire à la fin.
... et souhaite que ces paramètres soient automatiquement appliqués pour vos coéquipiers, ajoutez également les paramètres aux paramètres de l' espace de travail VScode, puis vérifiez .vscode/settings.json dans le contrôle source.
Si vous utilisez un autre éditeur, vous devrez suivre les mêmes étapes rugueuses que ci-dessus: obtenez la dernière version de Clangd configurée pour étendre l'éditeur, puis fournissez les mêmes indicateurs que VScode. Nous savons que les gens ont eu un temps facile à configurer cet outil avec d'autres éditeurs, comme EMACS et VIM + YouCompleteMe (YCM), par exemple.
Une fois que vous avez réussi à mettre en place un autre éditeur - ou à configurer clang-tidy , ou autrement vu tout ce qui pourrait améliorer cette lecture - nous l'adorerons si vous redonnez et contribuez ce que vous savez! Il suffit de modifier ce README.md sur github et de déposer un PR :)
Vous devriez maintenant être prêt à partir! Moyen de le faire grâce à la configuration.
Il devrait y avoir un fichier compile_commands.json à la racine de votre espace de travail, permettant à votre éditeur de fournir une excellente saisie semi-automatique basée sur Clang. Et vous devez savoir quelle cible à bazel run pour actualiser cette saisie semi-automatique, lorsque vous effectuez des changements de BUILD -file suffisamment grands pour nécessiter un rafraîchissement.
Dans les coulisses, ce fichier compile_commands.json contient des entrées décrivant toutes les commandes utilisées pour créer chaque fichier source de votre projet. Et, pour l'instant, il y a aussi une entrée par en-tête, décrivant une façon dont il est compilé. (Cela vous donne également une excellente saisie semi-automatique dans les fichiers d'en-tête, vous n'avez donc pas à penser au plus gros bord rugueux de clangd ). Surtout, toutes ces commandes ont été suffisamment désactivées pour que l'outillage de clang (ou vous!) Pour les comprendre.
Nous utilisons cet outil tous les jours pour développer une bibliothèque multiplateforme pour iOS et Android sur macOS. Attendez-vous à l'achèvement d'Android dans Android Source, MacOS dans MacOS, iOS dans iOS, etc. Les gens l'utilisent également sur Linux / Ubuntu et Windows.
Toutes les fonctionnalités habituelles de Clangd devraient fonctionner. CMD / CTRL + Cliquez sur Navigation (ou option Si vous avez modifié les clés de clés), le renommée intelligente, la saisie semi-automatique, la mise en surbrillance, etc. Tout ce que vous attendez dans un IDE devrait être là (car la plupart des bons IDE sont soutenus par clangd ). En tant que principe général: si vous choisissez des outils qui doivent comprendre un langage de programmation, vous voulez qu'il soit basé sur un frontend de compilateur pour cette langue, que Clangd fait dans le cadre du projet LLVM / Clang.
Tout devrait également fonctionner pour les fichiers générés, bien que vous puissiez exécuter une version pour exister le fichier généré. Si vous utilisez cela avec une exécution ou un cache à distance, vous devrez probablement utiliser --remote_download_regex pour baisser l'en-tête et les fichiers source et pour éviter les erreurs en éditeur, maintenant cette construction sans les octets ( --remote_download_toplevel ) est la valeur par défaut de Bazel. Si vous travaillez à ce sujet, nous serions ravis que si vous redonnez et déposiez un RP ajoutant de bonnes instructions pour tout le monde - ou au moins partagez ce que vous avez appris dans un numéro. Vous voudrez également baisser les fichiers de dépendance * .d sur les non-windows; Ils nous ont permis de trouver des en-têtes beaucoup plus rapidement lorsqu'ils sont disponibles en cache. Nous apprécierions si vous vérifiez également que vous êtes abaissé, même sans ( --noexperimental_inmemory_dotd_files ). Merci d'avoir aidé!
Sinon, nous avons des problèmes auto-déposés pour les bords rugueux que nous connaissons et que nous suivons. Nous aimerions avoir de vos nouvelles là-bas sur ce que vous voyez, bon et mauvais. Veuillez ajouter des choses si vous trouvez plus de bords rugueux et faites-nous savoir si vous avez besoin d'aide ou de fonctionnalités.
D'un autre côté, si vous avez installé les choses et qu'ils fonctionnent bien, nous aimerions toujours vous entendre. Veuillez déposer un "non-problème" dans l'onglet Problèmes décrivant votre succès! Nous serions ravis de savoir sur quoi vous travaillez, quelles plateformes vous utilisez et ce que vous trouvez le plus utile. Et peut-être aussi lancer une étoile à notre manière, donc nous savons que cela vous a été utile.
Nous aimerions également travailler avec vous sur les contributions et les améliorations, bien sûr! La configuration du développement est facile, pas onéreuse; Nous avons un excellent doc pour vous guider rapidement pour pouvoir apporter les modifications dont vous avez besoin. La base de code est super propre et amicale. Entrer dans le code est un moyen amusant et efficace d'obtenir les améliorations que vous souhaitez.
Si vous utilisez Bazel pour la famille des langues C, vous voudrez probablement également certains de nos autres outils, comme ...
Vous cherchez plutôt des détails d'implémentation? Vous voulez plonger dans la base de code? Voir implémentationReadme.md.
Le mainteneur bazel / incendie lisant ceci? Si vous êtes intéressé à l'intégrer dans les outils officiels de Bazel, faites-le nous savoir dans un problème ou un e-mail, et parlons! Nous aimons utiliser Bazel et aimerions aider.
