README.md

README.md

@@ -0,0 +1,44 @@
+
+# Rustc Log Viewer
+
+This is a log viewer for rustc's tracing output (in JSON form).
+It is made for when you don't yet know in advance how you want to filter your logs,
+and to analyze a large amount of ouput and filter it down to what you want to see.
+It's a TUI, and when you apply filters they get saved to disk.
+
+Filters rarely talk about the "nth log entry".
+That way they are reproducible.
+If you change something, rerun rustc, and gather logs again, the same set of filters will create a similar trace in the UI.
+That way you can compare logs.
+
+The UI shows a kind of tree view, which you can navigate with arrow keys etc.
+Only top-level logs are shown. With `Enter` you can step into a span and see the nested logs.
+Press `?` for all possible keyboard shortcuts.
+You can transform the tree in three ways:
+
+- Delete items (`alt+d`): delete all matching items. If no predicate is given, match only the current item.
+- Inline items (`alt+r`): inlining means taking items that are otherwise nested (which you normally need to navigate into) and display them at the top level.
+- Edit the printing of items (`alt+e`): WIP
+
+An explanation of how to target groups of logs can be found by typing `?`.
+
+## Gatherling logs
+
+To make it easy to gather logs, `lv` can be used as a wraper for `rustc` or `cargo` commands.
+It has built-in presets for sets of rustc crates you might care about, and to ensure logs don't get too large.
+
+For example
+
+```
+lv types x test tests/ui/sometest.rs
+lv types rustc +stage1 example.rs
+lv show
+```
+
+Use `--compiler-root` to make sure links in the tui point to the right directory. And pick a nice theme!
+
+## Integration with `t`
+
+I built a tool to manage temporary directories: <http://github.com/jdonszelmann/t-rs>.
+If you use that tool, you'll have a folder at `~/tempdirs`.
+Logviewer follows that convention: if it finds that directory, logs go there.