roc/crates/compiler
2024-01-26 16:19:51 -05:00
..
alias_analysis add List.clone 2024-01-20 20:29:07 +01:00
build add --fuzz option to roc 2024-01-25 15:42:18 -08:00
builtins Remove Nat from Num 2024-01-26 16:19:51 -05:00
can Remove Nat from Num 2024-01-26 16:19:51 -05:00
checkmate Consolidate gitignore 2024-01-10 22:16:04 -05:00
checkmate_schema
collections crate upgrades for ahash issue 2023-12-30 16:16:22 +01:00
constrain add src and location to dbg 2023-12-02 21:18:31 -08:00
debug_flags
derive Remove Nat from Hash, Inspect, Encode, Decode 2024-01-26 16:17:05 -05:00
derive_key Remove Nat from Num 2024-01-26 16:19:51 -05:00
exhaustive fix indexing 2023-11-20 21:09:12 -08:00
fmt Parse deprecated interpolation syntax differently 2024-01-06 21:49:00 -05:00
gen_dev Update List.dropAt to no longer use Nat 2024-01-26 16:06:09 -05:00
gen_llvm Update List.replace to no longer use Nat 2024-01-26 16:06:09 -05:00
gen_wasm Update List.dropAt to no longer use Nat 2024-01-26 16:06:09 -05:00
ident incorrect implementation of partial_cmp on an Ord type 2023-10-07 19:11:36 +02:00
late_solve
load Remove Nat from Hash, Inspect, Encode, Decode 2024-01-26 16:17:05 -05:00
load_internal Use Variable::U64 for List.len in file load 2024-01-26 16:06:08 -05:00
module Remove Nat from Num 2024-01-26 16:19:51 -05:00
mono Remove Nat from Num 2024-01-26 16:19:51 -05:00
parse Merge pull request #6361 from faldor20/fix-lang-server-hang 2024-01-21 22:06:48 -05:00
problem Fix errors 2023-10-25 17:14:49 -05:00
region First pass at semantic tokens 2023-10-25 17:15:04 -05:00
roc_target typo and clippy 2023-11-06 21:04:50 -08:00
serialize rust 1.71 clippy fixes 2023-07-25 10:46:46 +02:00
solve Remove Nat from Hash, Inspect, Encode, Decode 2024-01-26 16:17:05 -05:00
solve_problem Remove Nat from Hash, Inspect, Encode, Decode 2024-01-26 16:17:05 -05:00
solve_schema
test_derive add missing ToInspector case 2023-11-28 16:40:40 -08:00
test_gen Remove Nat from some compiler tests that use lists 2024-01-26 16:06:08 -05:00
test_mono Remove Nat from some compiler tests that use lists 2024-01-26 16:06:08 -05:00
test_mono_macros
test_solve_helpers simplify regex expression strings 2023-10-07 19:11:37 +02:00
test_syntax Update fmt tests to not use Nat 2024-01-26 16:17:06 -05:00
types Remove Nat from Num 2024-01-26 16:19:51 -05:00
uitest Remove Nat from Num 2024-01-26 16:19:51 -05:00
unify Remove Nat from Num 2024-01-26 16:19:51 -05:00
DESIGN.md
README.md

The Roc Compiler

For an overview of the design and architecture of the compiler, see DESIGN.md. If you want to dive into the implementation or get some tips on debugging the compiler, see below

Getting started with the code

The compiler contains a lot of code! If you're new to the project it can be hard to know where to start. It's useful to have some sort of "main entry point", or at least a "good place to start" for each of the main phases.

After you get into the details, you'll discover that some parts of the compiler have more than one entry point. And things can be interwoven together in subtle and complex ways, for reasons to do with performance, edge case handling, etc. But if this is "day one" for you, and you're just trying to get familiar with things, this should be "good enough".

The compiler is invoked from the CLI via build_file in cli/src/build.rs

Phase Entry point / main functions
Compiler entry point load/src/file.rs: load, load_and_monomorphize
Parse header parse/src/module.rs: parse_header
Parse definitions parse/src/module.rs: module_defs
Canonicalize can/src/def.rs: canonicalize_defs
Type check solve/src/module.rs: run_solve
Gather types to specialize mono/src/ir.rs: PartialProc::from_named_function
Solve specialized types mono/src/ir.rs: from_can, with_hole
Insert reference counting mono/src/ir.rs: Proc::insert_refcount_operations
Code gen (optimized but slow) gen_llvm/src/llvm/build.rs: build_procedures
Code gen (unoptimized but fast, CPU) gen_dev/src/object_builder.rs: build_module
Code gen (unoptimized but fast, Wasm) gen_wasm/src/lib.rs: build_module

For a more detailed understanding of the compilation phases, see the Phase, BuildTask, and Msg enums in load/src/file.rs.

Debugging the compiler

Please see the debug flags for information on how to ask the compiler to emit debug information during various stages of compilation.

There are some goals for more sophisticated debugging tools:

General Tips

Miscompilations

If you observe a miscomplication, you may first want to check the generated mono IR for your code - maybe there was a problem during specialization or layout generation. One way to do this is to add a test to test_mono/src/tests.rs and run the tests with cargo test -p test_mono; this will write the mono IR to a file.

Typechecking errors

First, try to minimize your reproduction into a test that fits in solve_expr.

Once you've done this, check out the ROC_PRINT_UNIFICATIONS debug flag. It will show you where type unification went right and wrong. This is usually enough to figure out a fix for the bug.

If that doesn't work and you know your error has something to do with ranks, you may want to instrument deep_copy_var_help in solve.

If that doesn't work, chatting on Zulip is always a good strategy.