Explain dependencies, add to FAQ, improve readback err msg

Cargo.lock

@@ -83,7 +83,7 @@ checksum = "0c4b4d0bd25bd0b74681c0ad21497610ce1b7c91b1022cd21c80c6fbdd9476b0"
 
 [[package]]
 name = "bend-lang"
-version = "0.2.8"
+version = "0.2.9"
 dependencies = [
  "TSPL 0.0.12",
  "clap",

Cargo.toml

@@ -2,7 +2,7 @@
 name = "bend-lang"
 description = "A high-level, massively parallel programming language"
 license = "Apache-2.0"
-version = "0.2.8"
+version = "0.2.9"
 edition = "2021"
 exclude = ["tests/snapshots/"]
 

GUIDE.md

@@ -36,7 +36,8 @@ To test if it worked, type:
 bend --help
 ```
 
-For GPU support, you also need CUDA version `12.X`.
+For GPU support, you also need the CUDA toolkit (CUDA and `nvcc`) version `12.X`. **It needs to be installed _before_ you install HVM.**
+At the moment, **only Nvidia GPUs** are supported.
 
 Hello, World!
 -------------

KNOWN_ISSUES.md

@@ -1,14 +1,17 @@
 # Known Issues
 
-### Why are my numbers giving me wrong results?
-- Either cause overflowing u24 or mixing different number types.
-
-### Can I run this on AMD/METAL GPUs?
-- We plan on adding support to many other GPUs as soon as the CUDA version is sufficiently stable.
-
 ### Can I run this on Windows?
 - We're still working on the windows support, for the moment, please use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).
 
+### I'm getting a `CUDA not available!` error even though I have it installed?
+- CUDA support is enable only during installation. If you first installed HVM and then installed CUDA and `nvcc`, please try to install HVM again.
+
+### I'm getting a `Failed to launch kernels (error code invalid argument)!` error.
+- The current iteration of the `hvm.cu` was written with the RTX 4090 in mind, and won't work on older GPUs, since they contain about half of the newer GPUs shared memory, for better understanding please refer to [HVM#283](https://github.com/HigherOrderCO/HVM/issues/283). We are working on support for older GPUs and will release it soon.
+
+### Can I run this on AMD/Intel/Apple GPUs?
+- We plan on adding support to many other GPUs as soon as the CUDA version is sufficiently stable.
+
 ### I get "Command `bend` not found" after installing, what do I do?
 - If you are on Unix system (or WSL) then most likely bend did not add itself to the PATH variable in your rc file. To remedy this:
   - Determine if you are using bash or zsh (check for presence of `~/.bashrc` or `~/.zshrc`)
@@ -17,23 +20,26 @@
   - You will then need to run `source ~/.bashrc` or `source ~/.zshrc` for the changes to take effect immediately
   - Try running `bend` once more - it should work now! 
 
-### How do I use IO?
-- IO is still being developed and is expected to come soon.
-
-### How to do FFI?
-- Not as soon as IO, but planned or at least something similar to FFI.
-
-### Are there any Libraries, Packages etc?
-- A package manager will be added soon.
-
 ### I got an error when installing HVM on Linux
 - If the error contains anything regarding `ccbin`, please refer to [HVM#291](https://github.com/HigherOrderCO/HVM/issues/291)
 
 - If the error contains anything regarding `libc` missing, please refer to [HVM#355](https://github.com/HigherOrderCO/Bend/issues/355)
 
+### How do I use IO?
+- IO is still being developed and is expected to come soon.
+
+### How to do FFI?
+- Not as soon as basic IO, but planned or at least something similar to FFI.
+
+### Are there any Libraries, Packages etc?
+- A package manager will be added soon.
+
+### Why are my numbers giving me wrong results?
+Some possibilities:
+- Your program is causing an overflow on 24-bit number values.
+- Your program is doing operations on numbers of different types. (e.g. `2.0 + 1` is not allowed, you must use `2.0 + 1.0`)
+- Floating point numbers are currently bugged and are interpreted incorrectly in some cases.
+- There's a bug with signed integers numbers that flips that sometimes flips the order of the operations.
+
 ### I'm getting an error of failed assertion
 - HVM currently has a bug in its conversion of f32 to f24 and it's unable to read the number 0.0. We already have a fix that we're working on.
-
-### Why am I getting a CUDA not supported error even though I have it installed?
-- The current iteration of the `hvm.cu` was written with the RTX 4090 in mind, and won't work on older GPUs, since they contain about half of the newer GPUs shared memory, for better understanding please refer to [HVM#283](https://github.com/HigherOrderCO/HVM/issues/283). We are working on the support for other GPUs and will release it soon.
-

README.md

@@ -19,7 +19,16 @@ A Quick Demo
 
 > Currently not working on Windows, please use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) as a workaround.
 
-First, install [Rust nightly](https://www.oreilly.com/library/view/rust-programming-by/9781788390637/e07dc768-de29-482e-804b-0274b4bef418.xhtml). Then, install both HVM2 and Bend with:
+> If you're having issues or have a question about Bend, please first read the [Known Issues](https://github.com/HigherOrderCO/Bend/blob/main/KNOWN_ISSUES.md) page and check if your question has already been addressed.
+
+First, install [Rust nightly](https://www.oreilly.com/library/view/rust-programming-by/9781788390637/e07dc768-de29-482e-804b-0274b4bef418.xhtml).
+
+If you want to use the C runtime, install a C compiler (like GCC or Clang).
+If you want to use the CUDA runtime, install the CUDA toolkit (CUDA and `nvcc`) version 12.x.
+
+> **_Note_: [Only Nvidia GPUs are supported at the moment](https://github.com/HigherOrderCO/Bend/issues/341).**
+
+Then, install both HVM2 and Bend with:
 
 ```sh
 cargo +nightly install hvm
@@ -29,9 +38,9 @@ cargo +nightly install bend-lang
 Finally, write some Bend file, and run it with one of these commands:
 
 ```sh
-bend run    <file.hvm> # uses the Rust interpreter (sequential)
-bend run-c  <file.hvm> # uses the C interpreter (parallel)
-bend run-cu <file.hvm> # uses the CUDA interpreter (massively parallel)
+bend run    <file.bend> # uses the Rust interpreter (sequential)
+bend run-c  <file.bend> # uses the C interpreter (parallel)
+bend run-cu <file.bend> # uses the CUDA interpreter (massively parallel)
 ```
 
 You can also compile `Bend` to standalone C/CUDA files with `gen-c` and

src/fun/net_to_term.rs

@@ -622,7 +622,6 @@ pub enum ReadbackError {
   InvalidNumericOp,
   ReachedRoot,
   Cyclic,
-  InvalidBind,
 }
 
 impl PartialEq for ReadbackError {
@@ -642,11 +641,14 @@ impl std::hash::Hash for ReadbackError {
 impl std::fmt::Display for ReadbackError {
   fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
     match self {
-      ReadbackError::InvalidNumericMatch => write!(f, "Invalid Numeric Match."),
-      ReadbackError::InvalidNumericOp => write!(f, "Invalid Numeric Operation."),
-      ReadbackError::ReachedRoot => write!(f, "Reached Root."),
-      ReadbackError::Cyclic => write!(f, "Cyclic Term."),
-      ReadbackError::InvalidBind => write!(f, "Invalid Bind."),
+      ReadbackError::InvalidNumericMatch => write!(f, "Encountered an invalid 'switch'."),
+      ReadbackError::InvalidNumericOp => write!(f, "Encountered an invalid numeric operation."),
+      ReadbackError::ReachedRoot => {
+        write!(f, "Unable to interpret the HVM result as a valid Bend term. (Reached Root)")
+      }
+      ReadbackError::Cyclic => {
+        write!(f, "Unable to interpret the HVM result as a valid Bend term. (Cyclic Term)")
+      }
     }
   }
 }

tests/snapshots/readback_lnet__bad_net.bend.snap

@@ -4,6 +4,6 @@ input_file: tests/golden_tests/readback_lnet/bad_net.bend
 ---
 Warnings:
 During readback:
-  Reached Root.
+  Unable to interpret the HVM result as a valid Bend term. (Reached Root)
 
 <Invalid>

tests/snapshots/readback_lnet__invalid_op2_op2.bend.snap

@@ -4,6 +4,6 @@ input_file: tests/golden_tests/readback_lnet/invalid_op2_op2.bend
 ---
 Warnings:
 During readback:
-  Invalid Numeric Operation. (3 occurrences)
+  Encountered an invalid numeric operation. (3 occurrences)
 
 λa <Invalid>

tests/snapshots/run_file__lam_op2_nested.bend.snap

@@ -4,6 +4,6 @@ input_file: tests/golden_tests/run_file/lam_op2_nested.bend
 ---
 Warnings:
 During readback:
-  Invalid Numeric Operation. (2 occurrences)
+  Encountered an invalid numeric operation. (2 occurrences)
 
 λa (* a (+ a <Invalid>))

tests/snapshots/run_file__let_tup_readback.bend.snap

@@ -4,6 +4,6 @@ input_file: tests/golden_tests/run_file/let_tup_readback.bend
 ---
 Warnings:
 During readback:
-  Reached Root.
+  Unable to interpret the HVM result as a valid Bend term. (Reached Root)
 
 λa ($b (a λc (<Invalid> λ$b c)))

tests/snapshots/run_file__linearize_match.bend.snap

@@ -4,6 +4,6 @@ input_file: tests/golden_tests/run_file/linearize_match.bend
 ---
 Warnings:
 During readback:
-  Invalid Numeric Match.
+  Encountered an invalid 'switch'.
 
 λa switch a = a { 0: λb b; _: λa λb (+ a b); }

tests/snapshots/run_file__match_mult_linearization.bend.snap

@@ -4,6 +4,6 @@ input_file: tests/golden_tests/run_file/match_mult_linearization.bend
 ---
 Warnings:
 During readback:
-  Invalid Numeric Match.
+  Encountered an invalid 'switch'.
 
 λa switch a = a { 0: λa λb λc (+ (+ a b) c); _: λa λb λc λd (+ (+ (+ a b) c) d); }