flowistry
v0.5.42
Flowistry ist ein Tool, das den Informationsfluss von Rostprogrammen analysiert. Flowistry versteht, ob es möglich ist, dass ein Code -Stück einen anderen betrifft. Flowistry integriert sich in die IDE, um einen "Fokusmodus" bereitzustellen, mit dem Sie sich auf den Code konzentrieren können, der mit Ihrer aktuellen Aufgabe zusammenhängt.
Beispielsweise zeigt dieses GIF den Fokusmodus beim Lesen einer Funktion, die zwei zusammensätzt:
Wenn der Benutzer auf eine bestimmte Variable oder einen bestimmten Ausdruck klickt, verblasst Flowistry alle Code, die diesen Code nicht beeinflusst und nicht von diesem Code beeinflusst wird . Zum Beispiel wird orig_len nicht von der For-Loop beeinflusst, während set.len() ist.
Flowistry kann hilfreich sein, wenn Sie eine Funktion mit viel Code lesen. Zum Beispiel zeigt dieses GIF eine echte Funktion im Rost -Compiler. Wenn Sie die Rolle eines spezifischen Arguments für die Funktion verstehen möchten, kann Flowistry den größten Teil des Codes als irrelevant herausstellen:
Der Algorithmus, den Mächte Flowistry in der Arbeit "Modular Information Flow durch Eigentum" bei PLDI 2022 veröffentlicht hat.
Inhaltsverzeichnis
Flowistry ist als VSCODE -Plugin erhältlich. Sie können Flowistry vom Visual Studio Marketplace oder der Open VSX -Registrierung installieren. In VSCODE:
Hinweis auf Plattformunterstützung: Flowistry unterstützt Nixos noch nicht. Flowistry kann keine vorgefertigten Binärdateien für Armziele wie M1-Macs bereitstellen. Daher muss die Flowistik auf diesen Zielen von Grund auf neu installiert werden (dies wird für Sie durchgeführt, dauert jedoch einige Minuten mehr als gewöhnlich).
Alternativ können Sie es aus Quelle installieren:
# 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
Wenn Sie an der zugrunde liegenden Analyse interessiert sind, können Sie die in crates.io veröffentlichte flowistry -Kiste verwenden: https://crates.io/crates/flowistry
Die Dokumentation wird hier veröffentlicht: https://illecrichton.net/flowistry/flowistry/
HINWEIS: DOCSS.RS unterstützt keine Dokumentation für Kisten, die
#![feature(rustc_private)]verwenden, daher müssen wir sie selbst hosten.
Beachten Sie, dass die neueste Flowistik eine maximal unterstützte Rust -Version von Rost 1.73 hat. Es wird nicht garantiert, dass Flowistry mit Funktionen funktioniert, die nach 1.73 implementiert sind.
Sobald Sie Flowistry installiert haben, öffnen Sie einen Rust -Arbeitsbereich in VSCODE. Sie sollten dieses Symbol in der unteren Symbolleiste sehen:
Flowistry beginnt durch die Überprüfung Ihrer Codebasis. Dies kann einige Minuten dauern, wenn Sie viele Abhängigkeiten haben.
HINWEIS: Die Ergebnisse des Typs zur Überprüfung von Flowistry werden im Verzeichnis
target/flowistryzwischengespeichert. Wenn Sie diesen Ordner löschen, muss die Flowistry die Typen neu berechnen. Auch für eine große Codebasis kann dieses Verzeichnis eine angemessene Menge an Speicherplatz in Anspruch nehmen.
Sobald die Flowistik gestoßen ist, verschwindet das Ladesymbol. Anschließend können Sie den Fokusmodus eingeben, indem Sie den Befehl "Toggle Focus -Modus" ausführen. Standardmäßig ist die Tastaturverknüpfung Strg+R Strg+A (⌘+r ⌘+a auf dem Mac) oder Sie können das Menü Flowistry Context verwenden:
Im Fokusmodus berechnet Flowistry den Informationsfluss innerhalb einer bestimmten Funktion automatisch, sobald Sie Ihren Cursor dort eingestellt haben. Sobald die Flowistry die Analyse beendet hat, sieht die Statusleiste so aus:
Hinweis: Flowistry kann für größere Funktionen etwas langsam sein. Es kann bis zu 15 Sekunden dauern, um die Analyse zu beenden.
Flowistry färbt sich auf der Grundlage Ihres Cursors, worauf Sie sich konzentrieren möchten. Wenn Sie also auf eine Variable klicken, sollten Sie den Fokusbereich dieser Variablen sehen. Flowistry wird den fokussierten Code in Grau hervorheben und dann den Code außerhalb des Fokusbereichs ausführen. Da der Cursor des Benutzers beispielsweise in view_projection ist, wird diese Variable grau hervorgehoben und seine Fokusregion wird gezeigt.
Manchmal möchten Sie den Fokusbereich dort halten, wo sie sich befindet, und klicken Sie auf einen anderen Code, um ihn zu inspizieren, ohne den Fokus zu ändern. Zu diesem Zweck hat Flowistry ein Konzept einer "Marke". Sobald Sie den Code ausgewählt haben, auf den Sie sich konzentrieren können, können Sie den Befehl "markieren" ausführen (Strg+R Strg+S / ⌘+R ⌘+S). Anschließend wird eine Marke auf die aktuelle Position Ihres Cursors eingestellt, und der Fokus bleibt dort, bis Sie den Befehl "Uneingestellter Marke" ausführen (Strg+r Strg+d / ⌘+r ⌘+d).
Wenn Sie den gesamten Code in der Fokusregion ändern möchten, z. B. um ihn zu kommentieren oder zu kopieren, können Sie den Befehl "Focused Region auswählen" (Strg+R Strg+T / ⌘+R ⌘+T) ausführen. Dadurch wird die gesamte Fokusregion in die Auswahl Ihres Editors aufgenommen.
Flowistry ist ein aktives Forschungsprojekt für die Anwendungen der Informationsflussanalyse für Rost. Es entwickelt sich ständig weiter, wenn wir mit Analysetechniken und Interaktionsparadigmen experimentieren. Es ist also nicht ganz so poliert oder effizient wie Werkzeuge wie Rust Analyzer, aber wir hoffen, dass Sie es immer noch nützlich finden können! Dennoch gibt es eine Reihe wichtiger Einschränkungen, die Sie bei der Verwendung von Flowistry verstehen sollten, um nicht überrascht zu sein.
Wenn Sie Fragen oder Probleme haben, stellen Sie bitte ein GitHub -Problem ein, treten Sie unserer Zwietracht oder DM @wcrichton auf Twitter bei.
Wenn Ihr Code Referenzen hat, muss die Flowistry verstehen, was diese Referenzpunkte haben. Flowistry verwendet die lebenslangen Informationen von Rust, um Punkte zu Informationen zu ermitteln. Datenstrukturen, die innere Veränderbarkeit wie Arc<Mutex<T>> verwenden, teilen jedoch explizit keine Lebensdauer zwischen Zeigern auf dieselben Daten. Zum Beispiel in diesem Snippet:
let x = Arc :: new ( Mutex :: new ( 0 ) ) ;
let y = x . clone ( ) ;
* x . lock ( ) . unwrap ( ) = 1 ;
println ! ( "{}" , y . lock ( ) . unwrap ( ) ) ; Flowistik kann bestimmen, dass *x.lock().unwrap() = 1 eine Mutation an x ist, kann jedoch nicht bestimmen, dass es sich um eine Mutation zu y handelt. Wenn Sie sich also auf y konzentrieren, würde die Zuordnung zu 1 verblasst, obwohl er für den Wert von y relevant ist.
Wir untersuchen Methoden, um diese Einschränkung zu überwinden, sind sich jedoch vorerst bewusst, dass dies der Hauptfall ist, in dem die Flowistik bekanntermaßen eine falsche Antwort liefert.
Die Analyse von Flowistry versucht, alle Code einzubeziehen, die einen Einfluss auf einen Schwerpunkt haben könnten . Diese Analyse macht aus praktischen und grundlegenden Gründen eine Reihe von Annahmen. Zum Beispiel in diesem Snippet:
let mut v = vec ! [ 1 , 2 , 3 ] ;
let x = v . get_mut ( 0 ) ;
println ! ( "{:?} {}" , v , x ) ; Wenn Sie sich auf v in Zeile 3 konzentrieren, enthält es v.get_mut(0) als Operation, die v . Der Grund dafür ist, dass Flowistry nicht die Körpers von so genannten Funktionen analysiert, sondern sich eher anhand ihrer Typsignaturen nähert. Da get_mut als Eingabe &mut self , wird davon ausgegangen, dass der Vektor geändert werden kann .
Im Allgemeinen sollten Sie den Fokusmodus als Schnittwerkzeug verwenden. Wenn der Code verblasst ist, müssen Sie ihn nicht lesen (abzüglich der oben genannten Einschränkung!). Wenn es nicht verblasst ist, ist es möglicherweise für Ihre Aufgabe relevant.
Flowistry funktioniert mit der Analyse des MIR -Diagramms für eine bestimmte Funktion mit der API des Rost Compiler. Dann hebt die IDE -Erweiterung die Analyseergebnisse von der miR -Ebene zurück auf die Quellebene. Auf der Reise vom Quellcode zu MIR gehen jedoch viele Informationen über das Programm verloren.
Wenn beispielsweise die Quelle einen Ausdruck foo.whomp.bar().baz() enthält, ist es möglich, dass eine vorübergehende Variable nur für den Ausdruck foo.whomp.bar() erzeugt wird. Wenn der Benutzer foo auswählt, kann die Flowistry möglicherweise nicht feststellen, dass dies dem MIR -Ort entspricht, foo darstellt.
Aus diesem Grund beleuchtet die IDE -Erweiterung den fokussierten Code in Gray, sodass Sie verstehen können, worauf die Auswahl Ihres Cursors tatsächlich entspricht.
Flowistry analysiert jeweils eine einzige Funktion. Wenn eine Funktion andere Funktionen, z. fn Definitionen oder Verschluss oder implizit über Async enthält, zeigt die Flowistry nur Fokusregionen innerhalb des kleinsten Funktionskörpers, der Ihren Cursor enthält. Dies ist in der Regel für Funktionsdefinitionen und -schließungen gut definiert, kann jedoch für Async verwirrend sein, da dies davon abhängt, wie RustC Ihre asynchronisierte Funktion aufschnitzt.
Wenn Rustup fehlschlägt, insbesondere bei einem Fehler wie "könnte die heruntergeladene Datei nicht umbenennen", liegt dies wahrscheinlich daran, dass Flowistry Rustup gleichzeitig mit einem anderen Tool (wie Rust-Analyzer) ausführt. Bis Rustup#988 gelöst ist, gibt es leider kein automatisiertes Weg.
Um das Problem zu lösen, gehen Sie in die Befehlszeile und führen Sie aus:
rustup toolchain install nightly-2023-08-25 -c rust-src -c rustc-dev -c llvm-tools-preview
Gehen Sie dann zurück zu VSCODE und klicken Sie auf "Weiter", um die Flowistry weiter zu installieren.
Rust Analyzer unterstützt MIR und den Ausleihe -Checker nicht, bei denen es sich um wesentliche Teile der Analyse des Flowistiks handelt. Es ist unwahrscheinlich, dass sich diese Tatsache lange Zeit ändert, daher ist Flowistry ein eigenständiges Tool.
Siehe Einschränkungen für bekannte Themen. Wenn dies nicht erklärt, was Sie sehen, posten Sie es bitte in das Problem der unerwarteten Highlights oder fragen Sie nach Zwietracht.
