Metadata-Version: 2.1
Name: sootty
Version: 0.3
Summary: Displays vcd files to the command line.
Home-page: https://github.com/Ben1152000/sootty
Author: Ben Darnell
Author-email: ben@bdarnell.com
License: BSD
Description: # Sootty
        
        Sootty is a graphical command-line tool for visualizing waveforms from hardware simulations, as a substitute for waveform visualizers like Verdi and GTKWave. It is designed with a focus on being lightweight and easy to use, and takes advantage of modern terminals’ capabilities to provide a clean graphical display. Current features include:
        - Customizable display style
        - Search and highlight events using a simple query language
        
        And here's an example of how sootty can be used directly from the terminal:
        
        <img width="979" alt="Screenshot of sootty in action" src="https://raw.githubusercontent.com/Ben1152000/sootty/master/image/screenshot.png">
        
        ## Getting Started
        
        1. Install sootty using pip:
        
        ```bash
        pip install sootty
        ```
        
        2. Display a waveform file to the terminal:
        
        ```bash
        sootty "waveform.vcd" -o > image.svg
        ```
        
        Optional arguments include:
        - `-s | --start FORMULA` Specify the start of the window.
        - `-e | --end FORMULA` Specify the end of the window.
        - `-l | --length N` Specify the number of ticks in the window (mutually exclusive with `-e`).
        - `-o | --output` Print svg data to `stdout` rather than display on terminal.
        - `-w | --wires LIST` Comma-separated list of wires to include in the visualization (default to all wires).
        - `-b | --break FORMULA` Specify the formula for the points in time to be highlighted.
        - `-r | --radix N` Display values in radix N (default 10).
        - `-S | --save SAVENAME` Saves current query for future reuse.
        - `-R | --reload SAVENAME` Loads a saved query. Requires query name as string.
        - `--btable` Print the wire value table at breakpoints to `stdout` (`-b` is required).
        
        *Note: For more detailed information on the query language, check out [syntax.md](syntax.md)
        
        ### Examples
        
        Below are some more examples  that take advantage of some of the features sootty has to offer:
        
        - Display all wires starting at time 4 and ending at wire `clk`'s tenth tick:
        
        ```bash
        sootty "example/example3.vcd" -s "time 4" -e "acc clk == const 10" -w "clk,rst_n,pc,inst"
        ```
        
        - Display wires `Data` and `D1` for 8 units of time starting when `Data` is equal to 20:
        
        ```bash
        sootty "example/example1.vcd" -l 8 -s "Data == const 20" -w "D1,Data"
        ```
        
        - Saving a query for future use:
        
        ```bash
        sootty "example/example2.vcd" -s "rdata && wdata == const 22" -l 10 -w "rdata, wdata" -S "save.txt"
        ```
        
        - Reloading a saved query:
        
        ```bash
        sootty -R "save.txt"
        ```
        
        - Add breakpoints at time 9, 11, and 16 - 17 and print wire values at breakpoints:
        
        ```bash
        sootty "example/example5.evcd" -b "time 9 || time 11 || after time 15 && before time 18" --btable
        ```
        
        ### Running with python
        
        Sootty can also be run from within a python program:
        
        ```python
        from sootty import WireTrace, Visualizer, Style
        from sootty.utils import evcd2vcd
        
        # Create wiretrace object from vcd file:
        wiretrace = WireTrace.from_vcd_file("example/example1.vcd")
        
        # Convert wiretrace to svg:
        image = Visualizer(Style.Dark).to_svg(wiretrace, start=0, length=8)
        
        # Display to stdout:
        image.display()
        
        # Manually convert EVCD file to VCD file:
        with open('myevcd.evcd', 'rb') as evcd_stream:
            vcd_reader = evcd2vcd(evcd_stream)
            with open('myvcd.vcd', 'wb') as vcd_stream:
                vcd_stream.write(vcd_reader.read())
        ```
        
        *Note: You can view and modify the save files for the queries in the `~/.config/sootty/save` directory.*
        
        ## Dependencies
        
        As of the current release, Sootty can only display images in certain terminals with builtin graphics support. This currently includes the following terminal replacements:
        
        - [iTerm2](https://iterm2.com/)
        - [kitty](https://sw.kovidgoyal.net/kitty/)
        
        The following external dependencies are also needed to properly display images within the terminal:
        
        - [viu](https://github.com/atanunq/viu)
        
          ```bash
          # From source (rust package manager)
          cargo install viu
          # MacOS
          brew install viu
          # Arch Linux
          pacman -S viu
          ```
        - rsvg-convert
          ```bash
          # Ubuntu
          apt install librsvg2-bin
          # MacOS
          brew install librsvg
          ```
        
        ## Contributing
        
        If you are interested in contributing to this project, feel free to take a look at the existing issues and submit a PR. Beginners are encouraged to focus on issues with the "good first issue" label. This project has also been involved with Google Summer of Code through the [FOSSi Foundation](https://www.fossi-foundation.org/). Check out our project idea for GSoC '23: https://www.fossi-foundation.org/gsoc23-ideas#enhancing-the-sootty-terminal-based-graphical-waveform-viewer
        
Platform: UNKNOWN
Description-Content-Type: text/markdown
