Stack size troubleshooting (#1548)

- **Run Cairo compiler in new thread**
- **Add troubleshooting page to docs**

Author: maciektr

scarb/src/ops/compile.rs

@@ -5,6 +5,7 @@ use cairo_lang_utils::Upcast;
 use indoc::formatdoc;
 use itertools::Itertools;
 use smol_str::{SmolStr, ToSmolStr};
+use std::thread;
 
 use scarb_ui::args::FeaturesSpec;
 use scarb_ui::components::Status;
@@ -150,7 +151,20 @@ where
     Ok(())
 }
 
+/// Run compiler in a new thread.
+/// The stack size of created threads can be altered with `RUST_MIN_STACK` env variable.
 pub fn compile_unit(unit: CompilationUnit, ws: &Workspace<'_>) -> Result<()> {
+    thread::scope(|s| {
+        thread::Builder::new()
+            .name(format!("scarb compile {}", unit.id()))
+            .spawn_scoped(s, || compile_unit_inner(unit, ws))
+            .expect("Failed to spawn compiler thread.")
+            .join()
+            .expect("Compiler thread has panicked.")
+    })
+}
+
+fn compile_unit_inner(unit: CompilationUnit, ws: &Workspace<'_>) -> Result<()> {
     let package_name = unit.main_package_id().name.clone();
 
     ws.config()

website/.vitepress/config.mjs

@@ -90,6 +90,7 @@ const sidebar = {
           "https://github.com/software-mansion/scarb/tree/main/examples",
         ),
         p("Scarb vs Cargo", "/docs/scarb-vs-cargo"),
+        p("Troubleshooting", "/docs/troubleshooting"),
       ],
     },
   ],

website/docs/troubleshooting.md

@@ -0,0 +1,32 @@
+# Troubleshooting
+
+It is possible that you encounter some issues while working with Scarb.
+This page lists some common issues and their possible solutions.
+Before reporting an issue to the Scarb team, please make sure to check the following list.
+
+## Stack overflow
+
+In case of a bug in the Cairo compiler implementation, it may consume too much stack space in some specific cases.
+Usually, this happens while compiling large Cairo codebases.
+This often results in an error message like:
+
+```
+thread 'main' has overflowed its stack
+fatal runtime error: stack overflow
+Aborted (core dumped)
+```
+
+Usually it does not seem to consume infinite amounts though, so you can try to confine it in an arbitrarily chosen
+big memory chunk.
+
+To run the Cairo compiler with a bigger stack size, you can use the `RUST_MIN_STACK` environmental variable.
+For example, to set the stack size to 128MB, you can run:
+
+```bash
+RUST_MIN_STACK=134217728 scarb build
+```
+
+Please note that this is a workaround and not a permanent solution.
+If you encounter this issue, please report it to the compiler team at [Cairo issues].
+
+[Cairo issues]: https://github.com/starkware-libs/cairo/issues/