flowistry
v0.5.42
Le flux est un outil qui analyse le flux d'informations des programmes de rouille. Flowistry comprend s'il est possible qu'un morceau de code affecte un autre. Flowistry s'intègre dans l'IDE pour fournir un "mode de mise au point" qui vous aide à vous concentrer sur le code lié à votre tâche actuelle.
Par exemple, ce GIF montre le mode de mise au point lors de la lecture d'une fonction qui syndics deux ensemble:
Lorsque l'utilisateur clique sur une variable ou une expression donnée, Flowistry s'estompe tout le code qui n'influence pas ce code et n'est pas influencé par ce code. Par exemple, orig_len n'est pas influencé par la boucle for, tandis que set.len() est.
Le flux peut être utile lorsque vous lisez une fonction avec beaucoup de code. Par exemple, ce GIF montre une fonction réelle dans le compilateur de rouille. Si vous souhaitez comprendre le rôle d'un argument spécifique à la fonction, alors le flux peut filtrer la majeure partie du code comme non pertinent:
L'algorithme qui alimente le flux de flux a été publié dans l'article "Flux d'informations modulaires à travers la propriété" au PLDI 2022.
Table des matières
Le flux est disponible en tant que plugin VScode. Vous pouvez installer Flowistry à partir du Visual Studio Marketplace ou du Registre Open VSX. Dans vScode:
Remarque sur la prise en charge de la plate-forme: Flowistry ne prend pas encore en charge Nixos. Le flux ne peut pas fournir des binaires prédéfinis pour des cibles ARM comme les Mac M1, de sorte que le flux doit être installé à partir de zéro sur ces cibles (ceci est fait pour vous, mais prendra quelques minutes de plus que d'habitude).
Alternativement, vous pouvez l'installer à partir de la source:
# Install flowistry binaries
git clone https://github.com/willcrichton/flowistry
cd flowistry
cargo install --path crates/flowistry_ide
# Install vscode extension
cd ide
npm install
npm run build
ln -s $(pwd) ~/.vscode/extensions/flowistry
Si vous êtes intéressé par l'analyse sous-jacente, vous pouvez utiliser la caisse flowistry publiée sur crates.io: https://crates.io/crates/flowisty
La documentation est publiée ici: https://willcrichton.net/flowistry/flowistry/
Remarque: Docs.rs ne prend pas en charge la documentation pour les caisses qui utilisent
#![feature(rustc_private)], nous devons donc l'héberger nous-mêmes.
Notez que le dernier flux de flux a une version maximale de rouille prise en charge de Rust 1.73 . Le flux de flux n'est pas garanti de travailler avec des fonctionnalités implémentées après 1,73.
Une fois que vous avez installé Flowistry, ouvrez un espace de travail Rust dans VSCODE. Vous devriez voir cette icône dans la barre d'outils inférieure:
Le flux commence en vérifiant votre base de code. Cela peut prendre quelques minutes si vous avez de nombreuses dépendances.
Remarque: Les résultats de vérification du type de flux sont mis en cache dans le répertoire
target/flowistry. Si vous supprimez ce dossier, Flowistry devra recomputer les types. Pour une grande base de code, ce répertoire peut occuper une bonne quantité d'espace disque.
Une fois que le flux a démarré, l'icône de chargement disparaîtra. Ensuite, vous pouvez saisir le mode de mise au point en exécutant la commande "Toggle Focus Mode". Par défaut, le raccourci clavier est Ctrl + R Ctrl + A (⌘ + R ⌘ + A sur Mac), ou vous pouvez utiliser le menu contextuel en flux:
En mode Focus, le flux de flux calculer automatiquement le flux d'informations dans une fonction donnée une fois que vous y mettiez votre curseur. Une fois que Flowistry aura terminé l'analyse, la barre d'état ressemblera à ceci:
Remarque: Le flux peut être un peu lent pour les fonctions plus grandes. Cela peut prendre jusqu'à 15 secondes pour terminer l'analyse.
Le flux déduit sur ce sur quoi vous voulez vous concentrer en fonction de votre curseur. Donc, si vous cliquez sur une variable, vous devriez voir la région de mise au point de cette variable. Flowistry mettra en évidence le code ciblé en gris, puis décolorera le code en dehors de la région de mise au point. Par exemple, parce que le curseur de l'utilisateur est sur view_projection , cette variable est mise en évidence en gris et sa région de mise au point est affichée.
Parfois, vous voulez garder la région de mise au point où elle se trouve, et cliquez sur un autre code pour l'inspecter sans changer de focus. À cette fin, Flowistry a un concept de "marque". Une fois que vous avez sélectionné du code sur lequel vous concentrer, vous pouvez exécuter la commande "Set Mark" (Ctrl + R Ctrl + S / ⌘ + R ⌘ + S). Ensuite, une marque est définie à la position actuelle de votre curseur, et l'accent restera là jusqu'à ce que vous exécutiez la commande "Unset Mark" (Ctrl + R Ctrl + D / ⌘ + R ⌘ + D).
Si vous souhaitez modifier tout le code dans la région de mise au point, par exemple pour le commenter ou le copier, vous pouvez exécuter la commande "Sélectionner la région focalisée" (Ctrl + R Ctrl + T / ⌘ + R ⌘ + T). Cela ajoutera toute la région de mise au point dans la sélection de votre éditeur.
Le flux est un projet de recherche actif sur les applications de l'analyse du flux d'informations pour la rouille. Il évolue continuellement à mesure que nous expérimentons les techniques d'analyse et les paradigmes d'interaction. Il n'est donc pas aussi poli ou efficace que des outils comme Rust Analyzer, mais nous espérons que vous pourrez toujours le trouver utile! Néanmoins, vous devez comprendre un certain nombre de limitations importantes lors de l'utilisation du flux pour éviter d'être surpris.
Si vous avez des questions ou des problèmes, veuillez déposer un problème GitHub, rejoignez notre discorde ou DM @WCrichton sur Twitter.
Lorsque votre code a des références, le flux doit comprendre ce que ces points de référence. Flowistry utilise les informations à vie de Rust pour déterminer les informations sur les points. Cependant, les structures de données qui utilisent la mutabilité intérieure telles que Arc<Mutex<T>> ne partagent explicitement pas des durées de vie entre les pointeurs vers les mêmes données. Par exemple, dans cet extrait:
let x = Arc :: new ( Mutex :: new ( 0 ) ) ;
let y = x . clone ( ) ;
* x . lock ( ) . unwrap ( ) = 1 ;
println ! ( "{}" , y . lock ( ) . unwrap ( ) ) ; Le flux de flux peut déterminer que *x.lock().unwrap() = 1 est une mutation à x , mais il ne peut pas déterminer qu'il s'agit d'une mutation à y . Donc, si vous vous concentrez sur y , l'affectation à 1 serait disparu, même si elle est pertinente pour la valeur de y
Nous recherchons des méthodes pour surmonter cette limitation, mais pour l'instant, sachez que c'est le cas principal où le flux est connu pour fournir une réponse incorrecte.
L'analyse de Flowistry essaie d'inclure tout le code qui pourrait avoir une influence sur un point focal. Cette analyse fait un certain nombre d'hypothèses pour des raisons pratiques et fondamentales. Par exemple, dans cet extrait:
let mut v = vec ! [ 1 , 2 , 3 ] ;
let x = v . get_mut ( 0 ) ;
println ! ( "{:?} {}" , v , x ) ; Si vous vous concentrez sur v sur la ligne 3, il inclura v.get_mut(0) comme opération qui aurait pu modifier v . La raison en est que le flux n'exécute pas réellement les corps des fonctions appelées, mais plutôt approximativement en fonction de leurs signatures de type. Parce que get_mut prend &mut self en entrée, il suppose que le vecteur pourrait être modifié.
En général, vous devez utiliser le mode de mise au point comme outil d'élagage. Si le code est disparu, vous n'avez pas à le lire (moins la limitation mentionnée ci-dessus!). S'il n'est pas disparu, cela pourrait être pertinent pour votre tâche.
Flowistry fonctionne en analysant le graphique MIR pour une fonction donnée à l'aide de l'API du compilateur Rust. Ensuite, l'extension IDE soulève les résultats de l'analyse du niveau MIR au niveau de la source. Cependant, beaucoup d'informations sur le programme sont perdues dans le parcours du code source à MIR.
Par exemple, si la source contient une expression foo.whomp.bar().baz() , il est possible qu'une variable temporaire soit générée uniquement pour l'expression foo.whomp.bar() . Donc, si l'utilisateur sélectionne foo , Flowistry peut ne pas être en mesure de déterminer que cela correspond au lieu MIR qui représente foo .
C'est pourquoi l'extension IDE met en évidence le code ciblé en gris, afin que vous puissiez comprendre à quoi mappe réellement la sélection de votre curseur.
Le flux analyse une seule fonction à la fois. Si une fonction contient d'autres fonctions, par exemple des définitions ou des fermetures fn , ou implicitement via Async, Flowistry ne vous montrera que des régions de concentration dans le corps de la plus petite fonction contenant votre curseur. Ceci est généralement bien défini pour les définitions et les fermetures de fonctions, mais peut être déroutant pour l'async, car cela dépend de la façon dont RustC décide de se tailler votre fonction asynchrone.
Si la rustup échoue, surtout avec une erreur comme "ne pourrait pas renommer le fichier téléchargé", c'est probablement parce que Flowistry fonctionne en même temps que la rustup avec un autre outil (comme Rust-Analyzer). Jusqu'à ce que la rustup # 988 soit résolue, il n'y a malheureusement pas de moyen automatisé.
Pour résoudre le problème, accédez à la ligne de commande et exécutez:
rustup toolchain install nightly-2023-08-25 -c rust-src -c rustc-dev -c llvm-tools-preview
Revenez ensuite à VScode et cliquez sur "Continuer" pour laisser le flux de fluidité continuer à installer.
Rust Analyzer ne prend pas en charge Mir et le vérificateur d'emprunt, qui sont des parties essentielles de l'analyse de Flowistry. Ce fait est peu susceptible de changer longtemps, donc le flux de fleuve est un outil autonome.
Voir les limites des problèmes connus. Si cela n'explique pas ce que vous voyez, veuillez le publier dans le problème des faits saillants inattendus ou demander sur Discord.
