Choisir quoi essayer

Commencez par les includes et les dépendances inutiles. Vérifiez le temps gagné sur les builds que vous lancez réellement, pas seulement le pourcentage. Faites une expérience à la fois pour comprendre ce qui a produit le résultat.

Repérer les headers coûteux

buildray profile --source /chemin/du/projet \
  --compiler clang++-21 --jobs 2

headers.md classe les headers par temps d’analyse, à partir des traces Clang. Les temps de headers imbriqués se recouvrent : ne les additionnez pas pour prédire un gain. Les traces servent au diagnostic, pas aux mesures avant/après.

Nettoyer les includes

buildray clean /chemin/du/projet --runs 3 --jobs 2
buildray headers --source /chemin/du/projet \
  --forward-declarations --header-path src \
  --exclude third_party --runs 3 --jobs 2

clean (anciennement optimize) essaie de supprimer les includes inutiles dans les sources C++. headers travaille sur les headers observés ; son option --forward-declarations essaie aussi des déclarations anticipées. L’analyse utilise les commandes de compilation réelles. Elle ne constitue pas un audit de toutes les règles de style de clang-tidy.

Les chemins exclus restent compilés et testés, mais leur contenu n’est pas modifié. Les fichiers générés ou téléchargés pendant la configuration sont également exclus des modifications.

Essayer Unity

buildray unity --source /chemin/du/projet --target ma_bibliotheque \
  --batch-size 4 --runs 3 --jobs 2 \
  --rebuild-file src/model.cc --rebuild-file include/model.h

Unity produit une option CMake désactivée par défaut. Après application du patch, -DBUILDRAY_UNITY=ON active les groupes testés. Ajoutez --rebuild-file pour mesurer les fichiers que vous modifiez souvent.

Pour Unity ou un PCH choisi manuellement, remplacez --jobs par --job-levels 1,2,4,8 pour comparer plusieurs nombres de jobs. Cette option ne se combine pas avec --auto ni les tentatives de regroupement Unity. Buildray exécute les niveaux l’un après l’autre, valide le même patch et garde leurs mesures séparées. Le rapport signale les niveaux qui dépassent la capacité CPU détectée. Voir la référence du parallélisme.

Le PCH reste une expérience facultative, désactivée par défaut. Appliquer son patch ne l’active pas ; il faut choisir -DBUILDRAY_PCH=ON. Ne l’envisagez que si le temps gagné justifie la configuration ajoutée. La référence PCH décrit ces essais explicites.

Examiner les dépendances

buildray deps --source /chemin/du/projet
buildray prune-links --source /chemin/du/projet --runs 3 --jobs 2

deps montre les relations entre headers et cibles, ainsi que les cycles. Il ne casse pas les cycles automatiquement : certains sont valides.

prune-links teste la suppression d’une seule déclaration CMake redondante dont les exigences restent accessibles par un autre chemin. Il ne recherche pas encore toutes les bibliothèques réellement inutiles. Si la commande finale de lien reste identique, aucun gain de temps n’est attendu de cette seule suppression.

prune-deps vérifie une fois par programme quelles archives sont utilisées, puis essaie de retirer ensemble les bibliothèques statiques privées éligibles. Il divise les groupes qui échouent et conserve les retraits acceptés dans chaque essai suivant. Les commandes de compilation doivent rester identiques, et le lien rejoué doit produire les mêmes binaires avec les mêmes objets. Le patch combiné doit aussi passer le build complet et les tests.

CMake peut aussi retirer une copie redondante d’une bibliothèque qui reste liée. Buildray ne l’accepte que si le binaire obtenu est identique ; toutes les sources de cette bibliothèque restent compilées.

Les noms de cibles et les listes de bibliothèques peuvent utiliser des variables CMake, y compris dans des boucles et des fonctions. Le patch ne change que les cibles et les valeurs de listes testées. Les autres valeurs conservent la commande d’origine, et les définitions des variables partagées restent intactes.

Ce mode demande ELF LLD, choisi explicitement pour les deux versions. Si une bibliothèque fournit seulement des headers ou des paramètres de compilation, le patch peut les conserver tout en retirant le lien. Ajoutez --rebuild-file pour vérifier si une modification déclenche moins de liens. La référence de la commande donne la configuration et les limites.

Les dépendances peuvent aussi être des alias CMake. Buildray vérifie la bibliothèque désignée, garde la définition de l’alias et conserve son nom dans le patch. Si un autre argument du linker change, l’essai est rejeté et les deux commandes sont conservées dans link-command-change.json.

La recherche est limitée par défaut à 64 configurations d’essai et 300 secondes. Modifiez ces limites avec --max-dependency-trials et --dependency-time-budget. Le build final et les tests ont quand même lieu une fois ce budget atteint.

Si votre projet ignore volontairement certains tests, utilisez --allow-baseline-skips. Buildray les compte à part et exige que les mêmes tests restent ignorés après le patch et chaque modification de fichier mesurée. Ils ne comptent jamais comme réussis. Les tests désactivés, les échecs et une exécution où tous les tests sont ignorés bloquent toujours la validation.

Garder uniquement un patch vérifié

Lisez patch_validated, patch_recommended et performance_result dans report.json. Un fichier .patch peut exister même après un échec ; sa présence ne vaut pas validation.

Pour un patch d’includes validé, depuis votre projet :

git apply --check /chemin/du/run/includes.patch
git apply /chemin/du/run/includes.patch

Relisez les modifications et testez vos autres configurations avant de les intégrer. Les références techniques détaillent les règles de chaque commande.

buildray clean-deps . lance cette recherche avec LLD pour les deux versions. --linker /chemin/vers/ld.lld choisit son exécutable. L’ancien nom prune-deps conserve le linker configuré, sauf si --linker est fourni.