RustBook/README.org

:PROPERTIES:
:header-args:shell: :results output
:END:
#+title: RustBook
#+author: HaQadosch Berraka
#+date: [2024-02-09 Fri]
#+startup: indent

#+link: ch01 https://rust-book.cs.brown.edu/ch01-00-getting-started.html

* Getting Started

** Chapter 01: Installation
Recommendation is to use *rustup* using the command:
#+name: install rustup
#+begin_src shell
  curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
#+end_src

To confirm it's installed:
#+name: confirm rustup installed
#+begin_src shell
  rustup --version
#+end_src

#+RESULTS: confirm rustup installed
: rustup 1.26.0 (5af9b9484 2023-04-05)
*** Update
To update *rustup* and please do regularly
#+name: update rustup
#+begin_src shell :results output
  rustup update
#+end_src
(
#+RESULTS: update rustup
: stable-x86_64-unknown-linux-gnu unchanged - rustc 1.76.0 (07dca489a 2024-02-04)
*** Documentation
*rustup* comes with documentation, just type
#+begin_src shell
  rustup doc
#+end_src

and the browser will open a page with links toward lots of docs.

** Chapter 02: Hello, World!
Basically done in 3 steps:
- Edit the rs file
- Compile using ~rustc~
- Call the executable


Work folder is =Projects/01_HelloWorld=, where we create the file =main.rs=
#+name: hello_world main.rs
#+begin_src rust
  fn main() {
      println!("Hello, World!");
  }
#+end_src

To execute this program:
#+name: 0102 call main
#+begin_src shell :results output
  cd Projects/01_HelloWorld/
  rustc main.rs
  ./main
#+end_src

#+RESULTS: 0102 call main
: Hello, World!

The program works, I'm now done.

*** Note
All rust program starts by calling the function ~main~.
Functions with ~!~ appended to their name, like ~println!~, are macros.

** Chapter 03: Hello, Cargo!
:PROPERTIES:
:header-args:shell: :dir ./Projects/hello_cargo :results output
:END:

Make sure *Cargo* is installed
#+name: cargo version
#+begin_src shell
  cargo --version
#+end_src

#+RESULTS: cargo version
: cargo 1.76.0 (c84b36747 2024-01-18)

*** New project with *Cargo*
#+name: new cargo
#+begin_src shell
  cargo new Projects/hello_cargo
  tree Projects/hello_cargo
#+end_src

#+RESULTS: new cargo
: Projects/hello_cargo
: ├── Cargo.toml
: └── src
:     └── main.rs
: 
: 2 directories, 2 files

*Cargo* creates:
- a directory with the project name given,
- and a project with the same name

The *Cargo* configuration file =Cargo.toml= in the root folder and
the projcet code in the =src/= directiory is what makes it a *Rust* project.

*** Building with Cargo
From the root folder, run
#+name: buiild cargo
#+begin_src shell
  cargo build
#+end_src

#+RESULTS: buiild cargo

This will create a =Cargo.lock= file in the root directory, and
an executable in =src/target/debug/hello_cargo=.
Which means you can display the text "hello, World!" by calling directly the file
#+name: direct call
#+begin_src shell
  ./target/debug/hello_cargo
#+end_src

#+RESULTS: direct call
: Hello, world!

*** Running a cargo
You can both build and run the program with
#+name: run hello_cargo
#+begin_src shell
  cargo run
#+end_src

#+RESULTS: run hello_cargo
: Hello, world!

*** Checking a cargo
*Cargo* can check if the program can compile. It doesn't execute it.
#+name: check hello_cargo
#+begin_src shell
  cargo check
#+end_src

#+RESULTS: check hello_cargo
:     Finished dev [unoptimized + debuginfo] target(s) in 0.01s
: [ Babel evaluation exited with code 0 ]

*** Releasing a cargo
To build a cargo with an optimised build, run

#+name: release hello_cargo
#+begin_src shell
  cargo build --release
  tree
#+end_src

#+RESULTS: release hello_cargo
#+begin_example
.
├── Cargo.lock
├── Cargo.toml
├── src
│   └── main.rs
└── target
    ├── CACHEDIR.TAG
    └── release
        ├── build
        ├── deps
        │   ├── hello_cargo-ac6d8d77e18d4d6b
        │   └── hello_cargo-ac6d8d77e18d4d6b.d
        ├── examples
        ├── hello_cargo
        ├── hello_cargo.d
        └── incremental

8 directories, 8 files
#+end_example

The build results are in the folder =target/release/= now.

**** 
* Programming a guessing game