How to debug

[NickHu]

Firstly, determine whether the issue lies within purely homotopy-core, or if it involves homotopy-web. It might be the case that it's easy to trigger the bug from the web interface, and for all intents and purposes in this sense it involves homotopy-web (even if the faulty behaviour only occurs in homotopy-core).

Rust has standard debugging via DWARF (so you can use gdb, lldb, etc.), but not when compiled for wasm32-unknown-unknown. The principal idea is to build all the parts of the project for your native target (e.g. x86_64-unknown-linux-gnu), as only yew depends on a WASM target.

Doesn't involve homotopy-web

1. write a test which triggers the bug in homotopy-rs/homotopy-core/tests/mytest.rs;
2. run cargo test: this generates a binary in homotopy-rs/targets/debug/deps/mytest-.*;
3. run your debugger on this binary.

Involves homotopy-web

Here, we will build the model part of homotopy-web without the UI part, so it can run natively (and hence we can debug it).

1. prepare the workspace so that the next action you trigger causes a panic;
2. export the workspace;
3. trigger the panic:
   
   (the highlighted Action needs to be recreated in Rust code);
4. replace https://github.com/homotopy-io/homotopy-rs/blob/master/homotopy-web/tests/action.rs#L15 with the trigger action previously determined;
5. in homotopy-web run cargo test action --no-run to build the debug binary (this will need to be repeated each time you edit action.rs);
6. run HOMOTOPY_IMPORT=/path/to/exported/workspace.hom targets/debug/deps/action-.* --ignored in your debugger.

[NickHu]

Which debugger should I use?

lldb seems to crash all the time, or just blatantly skip breakpoints, for me on Linux, so I would suggest using gdb. I think lldb is the primary debugger on macOS though, so YMMV.

gdb also has the advantage that it can be used with rr, allowing for reverse-execution in the debugger. This can be really useful to step backwards during a debugging session. More tips on using this with rust here.