https://github.com/rustviz/rustviz Skip to content Sign up * Why GitHub? Features - + Mobile - + Actions - + Codespaces - + Packages - + Security - + Code review - + Issues - + Integrations - + GitHub Sponsors - + Customer stories- * Team * Enterprise * Explore + Explore GitHub - Learn and contribute + Topics - + Collections - + Trending - + Learning Lab - + Open source guides - Connect with others + The ReadME Project - + Events - + Community forum - + GitHub Education - + GitHub Stars program - * Marketplace * Pricing Plans - + Compare plans - + Contact Sales - + Education - [ ] [search-key] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this organization All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} rustviz / rustviz * Notifications * Star 233 * Fork 5 Interactively Visualizing Ownership and Borrowing MIT License 233 stars 5 forks Star Notifications * Code * Issues 16 * Pull requests 0 * Actions * Projects 0 * Wiki * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Wiki * Security * Insights master Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags 3 branches 0 tags Code Clone HTTPS GitHub CLI [https://github.com/r] Use Git or checkout with SVN using the web URL. [gh repo clone rustvi] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching Xcode If nothing happens, download Xcode and try again. Go back Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit @marcelo-a marcelo-a Update README.md ... d1a3b3b Apr 8, 2021 Update README.md d1a3b3b Git stats * 109 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time rustviz_mdbook Update README.md Apr 8, 2021 src updated annotated_source files Apr 8, 2021 .gitignore moved files to top-level directory Apr 3, 2021 Cargo.toml moved files to top-level directory Apr 3, 2021 LICENSE.txt moved files to top-level directory Apr 3, 2021 README.md Update README.md Apr 8, 2021 View code RustViz What does it look like? Usage Step-By-Step Guide Appendix Visualization Limitations README.md RustViz Build Status RustViz is a tool that generates visualizations from simple Rust programs to assist users in better understanding the Rust Lifetime and Borrowing mechanism. What does it look like? RustViz generates SVG files with graphical indicators that integrate with mdbook to render visualizations of data-flow in Rust programs. Here's a sample view of what a visualization can look like: alt tag Usage RustViz is capable of visualizing simple Rust programs (albeit with certain limitations) via user definition. In this section, we'll showcase how to generate SVG renderings of examples provided by us. RustViz requires Rust, Cargo and mdbook to be installed. Once you have installed all the above prerequisites, direct into / rustviz_mdbook and run the script: ~/rustviz/rustviz_mdbook$ ./view_examples.sh You may have an output similar to this: Generating visualizations for the following examples: building copy... building hatra1... building hatra2... building func_take_ownership... building func_take_return_ownership... 2021-01-19 12:36:13 [INFO] (mdbook::book): Book building has started 2021-01-19 12:36:13 [INFO] (mdbook::book): Running the html backend Serving HTTP on :: port 8000 (http://[::]:8000/) ... If you observed this output, then you have successfully generated the Rust visualization examples! Now open your browser and navigate to http://localhost:8000/. You should be able to view the examples individually by selecting them from the left side bar. To view the visualization, click the toggle button on the top right corner of the code block. Great, this is how you can generate and view visualizations created using RustViz. Now let's create one from scratch! Step-By-Step Guide In this section, we'll dive into creating an example, string_from_move_print. First, take note of the file structure we'll need to run the example: string_from_move_print +-- input | +-- annotated_source.rs +-- main.rs +-- source.rs source.rs contains the untouched source code we wish to render into an image: fn main() { let x = String::from("hello"); let y = x; println!("{}", y); } In this example, String::from() moves a string ("hello") to x, then x's resource is moved to y. Subsequently, println!() outputs a message to io::stdout without moving the resource. Next, let's familiarize ourselves with the syntax used in main.rs. The RustViz tool defines all possible owners, references or input of any memory resource as a ResourceAccessPoint. In this case, we consider the function String::from() and two variables, x and y, as Resource Access Points (RAPs). Each of String::from() and x/y corresponds to RAPs ResourceAccessPoint::Function and ResourceAccessPoint::Owner, respectively. In main.rs, we define these RAPs between the BEGIN and END comments on lines 1 and 2: /*--- BEGIN Variable Definitions --- Owner x; Owner y; Function String::from() --- END Variable Definitions ---*/ The format for each ResourceAccessPoint enum is shown below, where fields preceded by ':' denote an optional field: ResourceAccessPoint Usage -- Owner <:mut> MutRef <:mut> StaticRef <:mut> Struct <:mut> {<:mut> , <:mut> , ... } Function Alternatively, some code let mut a = 5; and let b = &a; would correspond to Owner mut a and StaticRef b, respectively. An immutable instance of some struct with member variables x and mut y, on the other hand, may be annotated as Struct a{x, mut y}. It is important to note: 1. all definitions must lie between BEGIN and END 2. all definitions must be defined in the same order by which they were declared in the source code 3. all definitions must be separated by a singular semicolon 4. each field within a RAP definition must be separated by a whitespace Next, we annotate the code with the use of ExternalEvents that describe move, borrow, and drop semantics of Rust. In string_from_move_print, we have four such events: 1. Move of resource from String::from() to x 2. Move of resource from y to x 3. Drop of resource binded to x 4. Drop of resource binded to y We can specify Events in structured comments like so: /* --- BEGIN Variable Definitions --- Owner x; Owner y; Function String::from() --- END Variable Definitions --- */ fn main() { let x = String::from("hello"); // !{ Move(String::from()->x) } let y = x; // !{ Move(x->y) } println!("{}", y); // print to stdout! } /* !{ GoOutOfScope(x), GoOutOfScope(y) } */ Each Event is defined on the line where it occurs and within delimiters !{ and }. Events can be annotated within block comments; however, the block must start on the line in which the events occur. Additionally, all Events within a !{} delimitation must be separated by a singular comma and must each follow the format: ExternalEvents Usage: Format: (->) e.g.: // !{ PassByMutableReference(a->Some_Function()), ... } Note: GoOutOfScope and InitializeParam require only the parameter e.g.: // !{ GoOutOfScope(x) } Refer to the Appendix for a list of usable ExternalEvent's. Phew! All that's left is running the program. Simply run: cargo run string_from_move_print Now your folder should look like this: string_from_move_print +-- input | +-- annotated_source.rs +-- main.rs +-- source.rs +-- vis_code.svg +-- vis_timeline.svg Congratulations! You have successfully generated your first visualization! As a last step, add the name of your example to targetExamples under view_examples.sh and run the script to see it in your browser. Appendix ExternalEvent Usage: Event Usage Bind(a->b) Let binding or assignment. e.g.: let a = 1; Copy(a->b) Copies the resource of a to variable b. Here, a implements the Copy trait. Move(a->b) Moves the resource of a to variable b. Here, a implements the Move trait. StaticBorrow(a->b) Assigns an immutable reference of a to b. e.g.: let b = &a; MutableBorrow(a->b) Assigns a mutable reference of a to b. e.g.: let b = &mut a; Ends the non-lexical lifetime of the reference StaticReturn(a->b) variable a and returns the resource back to its owner b. Ends the non-lexical lifetime of the reference MutableReturn(a->b) variable a and returns the resource back to its owner b. PassByStaticReference Passes an immutable reference of variable a to (a->b) function b. Not to be confused with StaticBorrow. PassByMutableReference Passes a mutable reference of variable a to (a->b) function b. Not to be confused with MutableBorrow. Creates a struct instance a whose last member variable is b. Notes: (1) This event should be specified on the same StructBox(a->b) line the struct instance, a, goes out of lexical scope. (2) A struct's member variables should always be defined in the same order they are declared in. GoOutOfScope(a) Ends the lexical lifetime of variable a. InitializeParam(a) Initializes the parameter a of some function. e.g.: some_fn(a: String) {..} Note: 1. GoOutOfScope and InitializeParam require a singular parameter previously defined in the Variable Definitions section. (e.g.: // !{ GoOutOfScope(x) }) 2. All other events require two parameters, a and b, which can either be defined (e.g.: Owner a) or undefined (None). The None option is generally used for scalar types or undefined variables (e.g.: let x = 1 can be annotated as Bind(None-> x)). Visualization Limitations Some features are still being built. As of now, we are limited to: * No branching logic * No looping * No explicit lifetime annotation About Interactively Visualizing Ownership and Borrowing Resources Readme License MIT License Releases No releases published Packages 0 No packages published Contributors 4 * @marcelo-a marcelo-a Marcelo Almeida * @vishnureddy17 vishnureddy17 Vishnu Reddy * @jesssleepy jesssleepy * @jisonZ jisonZ Haochen Zhang Languages * Rust 76.7% * JavaScript 20.8% * CSS 1.3% * Shell 1.2% * (c) 2021 GitHub, Inc. * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.