Feat/writing bitfields proc macro

.gitattributes

@@ -1 +1,2 @@
 theme/whichlang.js linguist-vendored
+theme/highlight.js linguist-vendored

.github/workflows/cleanup.yml

@@ -0,0 +1,31 @@
+name: cleanup-preview
+
+on:
+  delete:
+
+jobs:
+  cleanup:
+    if: github.event.ref_type == 'branch'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          fetch-depth: 0
+
+      - name: Remove preview folder
+        run: |
+          BRANCH="${{ github.event.ref }}"
+          if [ -d "preview/$BRANCH" ]; then
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git rm -rf "preview/$BRANCH"
+            git commit -m "chore: remove preview for $BRANCH"
+            git push
+          else
+            echo "No preview found for $BRANCH, nothing to clean up."
+          fi

.github/workflows/deploy.yml

@@ -24,27 +24,75 @@ jobs:
           submodules: true
           fetch-depth: 0
 
-      - name: Install mdBook and mdbook-linkcheck (cached by action)
+      - name: Cache Rust toolchain & registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.rustup
+            ~/.cargo/registry
+            ~/.cargo/git
+          key: rust-toolchain-${{ runner.os }}-v1
+
+      - name: Cache compiled binaries
+        id: cache-bins
+        uses: actions/cache@v4
+        with:
+          path: ~/.cargo/bin
+          key: mdbook-bins-${{ runner.os }}-mdbook-0.5.3-v1
+
+      - name: Cache preprocessor build targets
+        uses: actions/cache@v4
+        with:
+          path: |
+            mdbook-rust-analyzer-highlight/target
+            mdbook-gh-issue-preview/target
+          key: cargo-preprocessors-${{ runner.os }}-${{ hashFiles('mdbook-rust-analyzer-highlight/Cargo.lock', 'mdbook-gh-issue-preview/Cargo.lock') }}
+          restore-keys: |
+            cargo-preprocessors-${{ runner.os }}-
+
+      - name: Install mdBook and plugins
+        if: steps.cache-bins.outputs.cache-hit != 'true'
         uses: taiki-e/install-action@v2
         with:
-          tool: mdbook@0.4.52,mdbook-linkcheck,mdbook-utils,mdbook-webinclude
+          tool: mdbook@0.5.3,mdbook-utils
 
       - name: Create sitemap
         run: mdbook-utils sitemap -m src -b https://www.learnix-os.com -o src/assets/sitemap.xml
 
       - name: Build the book
         env:
-            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: mdbook build
 
+      - name: Deploy preview
+        if: github.ref_name != 'master'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          personal_token: ${{ secrets.PREVIEW_DEPLOY_TOKEN }}
+          external_repository: sagi21805/LearnixOS-Book-previews
+          publish_branch: gh-pages
+          publish_dir: ./book
+          # no destination_dir → deploys to root, overwrites previous preview
+
+      - name: Print preview URL
+        if: github.ref_name != 'master'
+        run: |
+          echo "=========================================="
+          echo " Preview URL:"
+          echo " https://sagi21805.github.io/LearnixOS-Book-previews"
+          echo "=========================================="
+
       - name: Setup Pages
+        if: github.ref_name == 'master'
         uses: actions/configure-pages@v4
 
       - name: Upload artifact
+        if: github.ref_name == 'master'
         uses: actions/upload-pages-artifact@v3
         with:
-          path: 'book'
+          path: "book"
 
       - name: Deploy to GitHub Pages
+        if: github.ref_name == 'master'
         id: deployment
         uses: actions/deploy-pages@v4

.github/workflows/validate.yml

@@ -16,4 +16,4 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Check the Spelling of the Book
-        uses: crate-ci/typos@v1.34.0
+        uses: crate-ci/typos@v1.47.0

book.toml

@@ -14,19 +14,21 @@ inlay-hint-config = "inlay_config.json"
 after = ["mdbook-rust-analyzer-highlight"]
 command = "cargo run --release --manifest-path mdbook-gh-issue-preview/Cargo.toml"
 
-[preprocessor.webinclude]
-before = ["mdbook-rust-analyzer-highlight"]
 
 [output.html]
 git-repository-url = "https://github.com/sagi21805/LearnixOS"
 default-theme = "navy"
 preferred-dark-theme = "navy"
-preferred-light-theme = "navy"
 additional-css = ["theme/whichlang.css", "theme/hlrs.css", "theme/gh-issue.css", "theme/tags.css"]
 additional-js = [
     "theme/whichlang.js",
     "theme/filepath-links.js",
     "theme/giscuss.js",
-    "theme/tags.js"
+    "theme/tags.js",
+    "theme/highlight.js"
 ]
 mathjax-support = true
+
+[output.html.playground]
+runnable = true
+editable = true

src/SUMMARY.md

@@ -7,13 +7,14 @@
 # Chapters of The Book
 
 - [Getting Started](./ch01-00-getting-started.md)
-    - [Making a Stand Alone Binary [OS]](./ch01-01-making-stand-alone-binary.md)
+    - [Making a Stand Alone Binary [OS] [RUST]](./ch01-01-making-stand-alone-binary.md)
     - [Booting Our Binary [OS]](./ch01-02-booting-our-binary.md)
     - [Debugging Tips](./ch01-03-debugging-methods.md)
 
 - [A Minimal Bootloader](./ch02-00-a-minimal-bootloader.md)
     - [Legacy Legacy Legacy [OS]](./ch02-01-legacy-legacy-legacy.md)
     - [Entering Protected Mode [OS]](./ch02-02-entering-protected-mode.md)
+    - [Implementing the Bitfields Proc-Macro [RUST]](./ch02-03-implementing-the-bitfields-proc-macro.md)
     - [What is Memory Paging? [OS]](./ch02-03-what-is-memory-paging.md)
     - [Booting the Kernel [OS]](./ch02-04-booting-the-kernel.md)
 

src/ch01-01-making-stand-alone-binary.md

@@ -6,7 +6,7 @@ _"Machines take me by surprise with great frequency." - Alan Turing_
 
 The first step in making our operating system is making a program that can be compiled, and executed, without any dependency.
 This is not a straightforward task, because every program that we use in our daily life uses at least one, very important dependency: `The Standard Library`.
-Sometimes, this library is provided by the operating system itself, for example, libc for the Linux operating system, or the WinAPI for the Windows operating system, and most of the time it is wrapped around by our programming languages.
+Sometimes, this library is provided by the operating system itself, for example, libc for the Linux kernel, or the WinAPI for the Windows operating system, and most of the time it is wrapped around by our programming languages.
 Its name may vary per language, but here are some popular names:
 
 ```
@@ -51,8 +51,8 @@ If you have done everything correct, your project should look like this:
 
 And the main file, should look something like this:
 
-```rust,fp=main.rs
-#![function!("snippets/src/book/init.rs", main)]
+```rust,playground
+#![function!("snippets/src/book/ch01_01/init.rs", main)]
 ```
 
 
@@ -121,8 +121,8 @@ def failing_function(x: str):
 ```
 
 Instead, Rust provides us with the `panic!` macro, which will call the `Panic Handler`. This function is very important and it will be called every time the `panic!` macro is invoked, for example:
-```rust,fp=main.rs
-#![function!("snippets/src/book/panic.rs", main)]
+```rust,playground
+#![function!("snippets/src/book/ch01_01/panic.rs", main)]
 ```
 Normally, the Standard Library provides us with an implementation of the Panic Handler, which will typically print the line number and file in which the error occurred. However, because we are now not using the Standard Library, we need to define the implementation of the function ourselves.
 This function can be any function, as long as it includes the attribute `#[panic_handler]`. This attribute is added so the compiler will know which function to use when invoking the `panic!` macro, to enforce that only one function of this type exists, and to enforce the correct input argument signature and return type.
@@ -144,19 +144,19 @@ This means that it wants our function to receive a reference to a structure call
 But what is this struct? and what is this weird type?
 
 The `PanicInfo` struct includes basic information about our panic such as the location, and message. Its definition can be found in the Core library:
-```rust,fp=<rust-doc>core/panic/panic_info.rs
-#![struct!("snippets/src/book/panic.rs", PanicInfo)]
+```rust
+#![struct!("<rustc>/lib/rustlib/src/rust/library/core/src/panic/panic_info.rs", PanicInfo)]
 ```
 
 The `!` type is a very special type in Rust, called the `never` type, as the type name may suggest, it says that a function should **never** return, which means our program will not continue after the function is called.
 In a normal operating system, this is not a problem; just print the panic message + the location, and kill the process so it will not return. But in our own OS, unfortunately, this is not possible because there is not a process that we can exit. So, how can we prove to Rust we are not returning? By endlessly looping!
 
 So at the end, this is the minimal definition of our handler, which results in the following code
 
-```rust,fp=main.rs
-#![function!("snippets/src/book/no_std.rs", main)]
+```rust
+#![function!("snippets/src/book/ch01_01/no_std.rs", main)]
 
-#![function!("snippets/src/book/no_std.rs", panic_handler)]
+#![function!("snippets/src/book/ch01_01/no_std.rs", panic_handler)]
 ```
 
 This code unfortunately still doesn't compile, because we didn't handle the last error.
@@ -249,15 +249,18 @@ This will set our entry point to main, and our output into a raw binary, which m
 [^5]: Operating systems have their own binary header so they can understand how to treat a binary. Some common ones are [ELF](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format) and [PE](https://en.wikipedia.org/wiki/Portable_Executable)
 
 Then, to make our linker to use this script, we mainly have two options; one is to add some arguments to our build command, and the other one is to create a [build script](https://doc.rust-lang.org/cargo/reference/build-scripts.html). In this book, we use the following build script:
-```rust,fp=build.rs
-#![source_file!("snippets/src/book/build.rs")]
+```rust
+#![source_file!("snippets/src/book/ch01_01/build.rs", 1:99)]
 ```
 
 But, after we do all this and again, run `cargo build`, we get the same error. At first, this doesn't seem logical, because we defined a main function. But, although it is true that we defined one, we didn't consider Rust's default [mangling](https://doc.rust-lang.org/rustc/symbol-mangling/index.html).
 This is a very clever idea done by Rust, and without it, things like the following wouldn't be possible:
 
 ```rust
-#![source_file!("snippets/src/book/impl_ex.rs")]
+#![struct!("snippets/src/book/ch01_01/general.rs", A)]
+#![impl!("snippets/src/book/ch01_01/general.rs", A)]
+#![struct!("snippets/src/book/ch01_01/general.rs", B)]
+#![impl!("snippets/src/book/ch01_01/general.rs", A)]
 ```
 Although the functions are defined on different structs, they have the same name. But, because of mangling, the actual name of the function would be something like
 ```
@@ -269,8 +272,8 @@ A similar thing is happening to our `main` function, which makes its name not ex
 To fix it, we can add the `#[unsafe(no_mangle)]` attribute to our main function, which will make its name just 'main'.
 
 Which makes this, our final main.rs file!
-```rust,fp=main.rs
-#![source_file!("snippets/src/book/minimal_main.rs")]
+```rust
+#![source_file!("snippets/src/book/ch01_01/minimal_main.rs", 1:99)]
 ```
 
 ## Build Target

src/ch01-02-booting-our-binary.md

@@ -212,8 +212,8 @@ To print "Hello, World!", we can utilize the BIOS [video interrupt](https://en.w
 
 _For now, don't worry about the code implementation and just use and play with it. This code piece, and a lot more will be explained in the next chapter._
 
-```rust,fp=main.rs
-#![source_file!("snippets/src/book/print.rs")]
+```rust
+#![source_file!("snippets/src/book/ch01_02/print.rs", 1:99)]
 ```
 
 When we try to compile and run our code, we can see that it's indeed booting, but we don't see any message.
@@ -225,24 +225,30 @@ When we do that, we can notice that it seems that code was added, but at the end
 <blockquote>
 
 - **.text** - Includes the code of our program, which is the machine code that is generated for all of the functions
+
 ```rust,banner=no
-#![source_file!("snippets/src/book/func.rs")] 
-#![source_file!("")]
+#![function!("snippets/src/book/ch01_02/general.rs", some_function)] 
+#![]
 ```
+
+
 - **.data** - Includes the initialized data of our program, like static variables.
+
 ```rust,banner=no
-#![source_file!("snippets/src/book/static_var.rs")] 
-#![source_file!("")]
+#![static!("snippets/src/book/ch01_02/general.rs", MESSAGE)] 
+#![]
 ```
 - **.bss** - Includes the uninitialized data of our program
+
 ```rust,banner=no
-#![source_file!("snippets/src/book/static_uninit.rs")] 
-#![source_file!("")]
+#![static!("snippets/src/book/ch01_02/general.rs", UNINIT)] 
+#![]
 ```
 - **.rodata** - Includes the read-only data of our program
+
 ```rust,banner=no
-#![source_file!("snippets/src/book/static_str.rs")] 
-#![source_file!("")]
+#![static!("snippets/src/book/ch01_02/general.rs", VAR)] 
+#![]
 ```
 - **.eh_frame & .eh_frame_hdr** - Includes information that is relevant to exception handling and stack unwinding. These section are not relevant for us because we use `panic = "abort"`.
 </blockquote>

src/ch02-01-legacy-legacy-legacy.md

@@ -122,7 +122,7 @@ With that information, we can understand that the disk uses a 3D coordinate syst
 <figure style="width: 60%; text-align: center;">
     <img src="assets/Cylinder_Head_Sector.svg"
        style="background-color: aliceblue; width: 80%; height: auto;">
-    </img>
+
   <figcaption><strong>Figure 2-0:</strong> Cylinder Head Sector Diagram</figcaption>
 
 </figure>
@@ -198,7 +198,7 @@ $$
 After learning about LBA, the only logical thing to think, is how to read data from the disk using LBA instead of CHS.
 This is where the `extended read` functions comes in; it expects a structure called the `disk address packet` which looks like this:
 
-```rust,fp=<repo>bootloader/first_stage/src/disk.rs#L4
+```rust
 #![struct!("bootloader/first_stage/src/disk.rs", DiskAddressPacket)]
 ```
 
@@ -214,19 +214,19 @@ This is quite straight forward, we will create a `new` function that will initia
 
 First, for organization, we will create some helpful enums:
 
-```rust,fp=<repo>crates/common/src/enums/bios_interrupts.rs
+```rust
 #![enum!("crates/common/src/enums/bios_interrupts.rs", BiosInterrupts)]
 #![enum!("crates/common/src/enums/bios_interrupts.rs", DiskInterrupt)]
 ```
 
 Then, we can create an initializer function for our `disk packet`:
 
-```rust,fp=<repo>bootloader/first_stage/src/disk.rs#L44
+```rust
 #![impl_method!("bootloader/first_stage/src/disk.rs", DiskAddressPacket::new)]
 ```
 And then, finally the function that will call the interrupt with our packet, and will read the disk content into memory.
 
-```rust,fp=<repo>bootloader/first_stage/src/disk.rs#L71
+```rust
 #![impl_method!("bootloader/first_stage/src/disk.rs", DiskAddressPacket::load)]
 ```
 
@@ -249,7 +249,7 @@ Then, we can get the disk number from the stack, and load our packet.
 And create a constant for the disk number memory address
 Then, in the first stage function
 
-```rust,fp=<repo>bootloader/first_stage/src/main.rs#L29
+```rust
 #![const!("crates/common/src/constants/addresses.rs", DISK_NUMBER_OFFSET)]
 
 #![function!("bootloader/first_stage/src/main.rs", load_dap)]