language-servers/roc
1
0
Fork 0
mirror of https://github.com/roc-lang/roc.git synced 2025-08-04 04:08:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

move debug tips

Browse source
This commit is contained in:
Anton-4 2024-08-09 15:47:54 +02:00 • committed by GitHub
parent 1a09a5347d
commit bf63c79997
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 19 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

18
CONTRIBUTING.md
View file

@ -43,23 +43,9 @@ Execute `cargo fmt --all` to fix the formatting.
- The [compiler's README](https://github.com/roc-lang/roc/tree/main/crates/compiler) contains important info.
- The AI chat in the [cursor editor](https://www.cursor.com/) can also help you find your way in the codebase.
<details>
<summary>:beetle: Debugging Tips</summary>
### Debugging tips
- When using github search to find similar errors/issues use `org:roc-lang`, for example `org:roc-lang valgrind unrecognised instruction`. This will search in basic-cli, basic-webserver, ... as well. Just using `roc` instead of `org:roc-lang` may yield useful results as well.
- Use a debug build of the compiler. We have many asserts enabled in the debug compiler that can alert you to something going wrong. When building from source, build the debug compiler with `cargo build --bin roc`, the binary is at roc/target/debug/roc. When using roc through a nix flake like in [basic-cli](https://github.com/roc-lang/basic-cli), use `rocPkgs.cli-debug` instead of `rocPkgs.cli`.
- At the bottom of [.cargo/config.toml](https://github.com/roc-lang/roc/blob/main/.cargo/config.toml) we have useful debug flags that activate certain debug prints and extra checks.
- For Roc code; minimize the code that produces the issue.
- If you plan to look at the data used and produced inside the compiler, try to reproduce your issue with a very simple platform like our [minimal Rust platform](https://github.com/roc-lang/roc/tree/main/examples/platform-switching/rust-platform) instead of for example basic-cli.
- For segmentation faults:
+ In general we recommend using linux to investigate, it has better tools for this.
+ If your segfault also happens when using `--linker=legacy`, using it will improve valgrind output. Use `roc build myApp.roc --linker=legacy` followed by `valgrind ./myApp`.
+ Use gdb to step through the code, [this gdb script](https://roc.zulipchat.com/#narrow/stream/395097-compiler-development/topic/gdb.20script/near/424422545) can be helpful.
+ Use objdump to look at the assembly of the code, for example `objdump -d -M intel ./examples/Arithmetic/main`. Replace `-M intel` with the appropriate flag for your CPU.
+ Inspect the generated LLVM IR (`roc build myApp.roc --emit-llvm-ir`) between Roc code that encounters the segfault and code that doesn't.
</details>
If you need to do some debugging, check out [our tips](devtools/debug_tips.md).
### Commit signing

17
devtools/debug_tips.md Normal file
View file

@ -0,0 +1,17 @@
# Debug Tips
## General
- When using github search to find similar errors/issues use `org:roc-lang`, for example: `org:roc-lang valgrind unrecognised instruction`. This will search in basic-cli, basic-webserver, ... as well. Just using `roc` instead of `org:roc-lang` may yield useful results as well.
- Use a debug build of the compiler. We have many asserts enabled in the debug compiler that can alert you to something going wrong. When building from source, build the debug compiler with `cargo build --bin roc`, the binary is at `roc/target/debug/roc`. When using roc through a nix flake like in [basic-cli](https://github.com/roc-lang/basic-cli), use `rocPkgs.cli-debug` instead of `rocPkgs.cli`.
- At the bottom of [.cargo/config.toml](https://github.com/roc-lang/roc/blob/main/.cargo/config.toml) we have useful debug flags that activate certain debug prints and extra checks.
- For Roc code; minimize the code that produces the issue.
- If you plan to look at the data used and produced inside the compiler, try to reproduce your issue with a very simple platform like our [minimal Rust platform](https://github.com/roc-lang/roc/tree/main/examples/platform-switching/rust-platform) instead of for example basic-cli.
## Segmentation Faults
- In general we recommend using linux to investigate, it has better tools for this.
- If your segfault also happens when using `--linker=legacy`, use it to improve valgrind output. For example: `roc build myApp.roc --linker=legacy` followed by `valgrind ./myApp`.
- Use gdb to step through the code, [this gdb script](https://roc.zulipchat.com/#narrow/stream/395097-compiler-development/topic/gdb.20script/near/424422545) can be helpful.
- Use objdump to look at the assembly of the code, for example `objdump -d -M intel ./examples/Arithmetic/main`. Replace `-M intel` with the appropriate flag for your CPU.
- Inspect the generated LLVM IR (`roc build myApp.roc --emit-llvm-ir`) between Roc code that encounters the segfault and code that doesn't.