curds/boredos_mirror
1
0
Fork 0
mirror of https://github.com/BoredDevNL/BoredOS.git synced 2026-05-15 10:48:38 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

doc: adjust examples with ELF metadata

Browse source
This commit is contained in:
boreddevnl 2026-04-21 00:28:29 +02:00
parent d14000b7eb
commit 8d51238a3d
6 changed files with 32 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
docs/appdev/examples/01_hello_cli.md
View file

@ -7,16 +7,18 @@
This example demonstrates the bare minimum structure of a BoredOS application that outputs text to the standard output (usually the Terminal executing the binary). This example demonstrates the bare minimum structure of a BoredOS application that outputs text to the standard output (usually the Terminal executing the binary).
## 📝 Concepts Introduced ## Concepts Introduced
* Including `stdlib.h` for basic IO. * Including `stdlib.h` for basic IO.
* The `main()` entry point. * The `main()` entry point.
* Using `printf()` for formatted output. * Using `printf()` for formatted output.
* Declaring app metadata via source annotations.
--- ---
## 💻 The Code (`src/userland/cli/hello_world.c`) ## The Code (`src/userland/cli/hello_world.c`)
```c ```c
// BOREDOS_APP_DESC: Hello World — a minimal CLI demo.
#include <stdlib.h> #include <stdlib.h>
int main(int argc, char **argv) { int main(int argc, char **argv) {
@ -34,14 +36,15 @@ int main(int argc, char **argv) {
} }
``` ```
## 🛠️ How it Works ## How it Works
1. **`#include <stdlib.h>`**: We include the SDK's standard library header which gives us access to `printf`. 1. **`#include <stdlib.h>`**: We include the SDK's standard library header which gives us access to `printf`.
2. **`int main(...)`**: Every process begins execution here (managed transparently by `crt0.asm`). 2. **`int main(...)`**: Every process begins execution here (managed transparently by `crt0.asm`).
3. **`printf(...)`**: The SDK routes this call internally directly to the `SYS_WRITE` system call, making it available on the terminal. 3. **`printf(...)`**: The SDK routes this call internally directly to the `SYS_WRITE` system call, making it available on the terminal.
4. **`return 0`**: A successful exit code. 4. **`return 0`**: A successful exit code.
5. **`BOREDOS_APP_DESC` / `BOREDOS_APP_ICONS`**: These comment annotations are read by the build system (`gen_userland_note.sh`) and embedded as a `boredos_app_metadata_t` NOTE entry inside the compiled `.elf`. The File Explorer and Desktop use this to display the correct icon. See [`elf_metadata.md`](../elf_metadata.md) for full details.
## 🚀 Running It ## Running It
If you build the project, you can open the Terminal and type: If you build the project, you can open the Terminal and type:
```sh ```sh

9
docs/appdev/examples/02_basic_window.md
View file

@ -7,17 +7,19 @@
This example demonstrates how to create an empty window that stays active on the screen until the user explicitly closes it by clicking the 'X' button. This example demonstrates how to create an empty window that stays active on the screen until the user explicitly closes it by clicking the 'X' button.
## 📝 Concepts Introduced ## Concepts Introduced
* Including `libui.h` and the event structure. * Including `libui.h` and the event structure.
* Creating a `ui_window_t` handle. * Creating a `ui_window_t` handle.
* Creating an infinite event loop using `ui_get_event()`. * Creating an infinite event loop using `ui_get_event()`.
* Yielding CPU time to the kernel via `sys_yield()`. * Yielding CPU time to the kernel via `sys_yield()`.
* Declaring app metadata via source annotations.
--- ---
## 💻 The Code (`src/userland/gui/basic_window.c`) ## The Code (`src/userland/gui/basic_window.c`)
```c ```c
// BOREDOS_APP_DESC: Basic Window — a minimal graphical window demo.
#include <stdlib.h> #include <stdlib.h>
#include <libui.h> #include <libui.h>
#include <syscall.h> #include <syscall.h>
@ -65,7 +67,8 @@ int main(void) {
2. **The Event Loop**: Graphical programs run forever until closed. The `while (1)` loop serves this purpose. 2. **The Event Loop**: Graphical programs run forever until closed. The `while (1)` loop serves this purpose.
3. **Polling**: `ui_get_event` asks the kernel, "Hey, did the user click my window or press a key since the last time I asked?". It is non-blocking, so it immediately returns `false` if nothing happened. 3. **Polling**: `ui_get_event` asks the kernel, "Hey, did the user click my window or press a key since the last time I asked?". It is non-blocking, so it immediately returns `false` if nothing happened.
4. **CPU Yielding**: Since we are constantly polling in a tight loop, we call `sys_yield()` at the end of the loop frame. This politely tells the OS scheduler, "I'm done checking for events, go ahead and let another program run for a bit." 4. **CPU Yielding**: Since we are constantly polling in a tight loop, we call `sys_yield()` at the end of the loop frame. This politely tells the OS scheduler, "I'm done checking for events, go ahead and let another program run for a bit."
5. **`BOREDOS_APP_DESC` / `BOREDOS_APP_ICONS`**: Embedded into the `.elf` by the build system as a BoredOS NOTE section. The Window Manager reads this at runtime to render the app's icon on the Desktop and in the File Explorer. See [`elf_metadata.md`](../elf_metadata.md) for full details.
## 🚀 Running It ## Running It
Launch the Terminal and type `basic_window`. You'll see an empty window appear that you can move around the screen! Launch the Terminal and type `basic_window`. You'll see an empty window appear that you can move around the screen!

10
docs/appdev/examples/03_bouncing_ball.md
View file

@ -7,17 +7,20 @@
This example builds upon the `02_basic_window` guide. It demonstrates how to constantly update the screen to simulate a bouncing square moving freely inside the window bounds. This example builds upon the `02_basic_window` guide. It demonstrates how to constantly update the screen to simulate a bouncing square moving freely inside the window bounds.
## 📝 Concepts Introduced ## Concepts Introduced
* Maintaining application state across frames (Velocity/Position). * Maintaining application state across frames (Velocity/Position).
* Drawing primitives (`ui_fill_rect`, `ui_draw_string`). * Drawing primitives (`ui_fill_rect`, `ui_draw_string`).
* The importance of clearing the screen on a new frame. * The importance of clearing the screen on a new frame.
* Explicitly forcing standard visual updates via `ui_mark_dirty()`. * Explicitly forcing standard visual updates via `ui_mark_dirty()`.
* Declaring app metadata via source annotations.
--- ---
## 💻 The Code (`src/userland/gui/bounce.c`) ## The Code (`src/userland/gui/bounce.c`)
```c ```c
// BOREDOS_APP_DESC: Bouncing ball animation demo.
// BOREDOS_APP_ICONS: /Library/images/icons/colloid/applications-games.png
#include <stdlib.h> #include <stdlib.h>
#include <libui.h> #include <libui.h>
#include <syscall.h> #include <syscall.h>
@ -81,12 +84,13 @@ int main(void) {
} }
``` ```
## 🛠️ How it Works ## How it Works
1. **State Management**: We store `pos_x`, `pos_y`, `vel_x`, and `vel_y`. These variables represent the "physics" of our system. Notice that they update *outside* the event-checking logic so that the animation runs even if the user isn't clicking the mouse. 1. **State Management**: We store `pos_x`, `pos_y`, `vel_x`, and `vel_y`. These variables represent the "physics" of our system. Notice that they update *outside* the event-checking logic so that the animation runs even if the user isn't clicking the mouse.
2. **Screen Clearing**: We *must* fill the screen with black (`ui_draw_rect(wid, 0, 0, W_WIDTH, W_HEIGHT, ...)`). If we don't clear the screen, the red square will leave a permanent trailing smear everywhere it goes! 2. **Screen Clearing**: We *must* fill the screen with black (`ui_draw_rect(wid, 0, 0, W_WIDTH, W_HEIGHT, ...)`). If we don't clear the screen, the red square will leave a permanent trailing smear everywhere it goes!
3. **The Double Buffer**: `ui_draw_rect` and `ui_draw_string` do not immediately appear on your monitor. They just color a hidden buffer within the kernel. 3. **The Double Buffer**: `ui_draw_rect` and `ui_draw_string` do not immediately appear on your monitor. They just color a hidden buffer within the kernel.
4. **`ui_mark_dirty`**: This is the crucial command that tells the kernel Window Manager, "I'm done drawing my frame. Can you quickly copy my hidden buffer over to the real screen now?" 4. **`ui_mark_dirty`**: This is the crucial command that tells the kernel Window Manager, "I'm done drawing my frame. Can you quickly copy my hidden buffer over to the real screen now?"
5. **`BOREDOS_APP_DESC` / `BOREDOS_APP_ICONS`**: Embedded into the compiled `.elf` as a BoredOS NOTE section. The Desktop and File Explorer read this to show the game's icon instead of the generic binary icon. See [`elf_metadata.md`](../elf_metadata.md) for full details.
> [!WARNING] > [!WARNING]
> Because `sys_yield()`'s pause duration depends heavily on CPU load and how many other processes are running (or QEMU emulation speed), tying physics/movement strictly to loops can make the game run faster on faster computers. Advanced developers will want to calculate delta time (time elapsed since the last frame) for smooth motion. > Because `sys_yield()`'s pause duration depends heavily on CPU load and how many other processes are running (or QEMU emulation speed), tying physics/movement strictly to loops can make the game run faster on faster computers. Advanced developers will want to calculate delta time (time elapsed since the last frame) for smooth motion.

10
docs/appdev/examples/04_tcp_client.md
View file

@ -12,12 +12,15 @@ This advanced example demonstrates the steps required to use the raw network sys
* Performing DNS lookups manually via `sys_dns_lookup`. * Performing DNS lookups manually via `sys_dns_lookup`.
* Managing strict TCP flow logic (`sys_tcp_connect`, send, block for receive). * Managing strict TCP flow logic (`sys_tcp_connect`, send, block for receive).
* Using the terminal `SYS_WRITE` output for debugging. * Using the terminal `SYS_WRITE` output for debugging.
* Declaring app metadata via source annotations.
--- ---
## 💻 The Code (`src/userland/cli/http_get.c`) ## The Code (`src/userland/cli/http_get.c`)
```c ```c
// BOREDOS_APP_DESC: HTTP GET client — fetches a webpage over TCP.
// BOREDOS_APP_ICONS: /Library/images/icons/colloid/network-wired.png
#include <stdlib.h> #include <stdlib.h>
#include <string.h> #include <string.h>
#include <syscall.h> #include <syscall.h>
@ -79,14 +82,15 @@ int main(void) {
} }
``` ```
## 🛠️ How it Works ## How it Works
1. **Network Setup**: First, we must ensure the host machine or QEMU environment gave BoredOS a valid IP address via DHCP. The `sys_network_has_ip()` check prevents our app from hanging trying to route data to nowhere. 1. **Network Setup**: First, we must ensure the host machine or QEMU environment gave BoredOS a valid IP address via DHCP. The `sys_network_has_ip()` check prevents our app from hanging trying to route data to nowhere.
2. **DNS (`sys_dns_lookup`)**: Since we want to connect to a domain name, not a raw IP, we query the DNS server configured by the OS (which it received via DHCP). 2. **DNS (`sys_dns_lookup`)**: Since we want to connect to a domain name, not a raw IP, we query the DNS server configured by the OS (which it received via DHCP).
3. **Connection (`sys_tcp_connect`)**: We block the application thread while the OS performs the 3-way TCP handshake over port 80. 3. **Connection (`sys_tcp_connect`)**: We block the application thread while the OS performs the 3-way TCP handshake over port 80.
4. **Payload (`sys_tcp_send`)**: We format a compliant HTTP/1.1 payload representing a simple GET request for the root directory `/`. 4. **Payload (`sys_tcp_send`)**: We format a compliant HTTP/1.1 payload representing a simple GET request for the root directory `/`.
5. **Chunked Receiving (`sys_tcp_recv`)**: The server's response might be larger than our `recv_buf` (512 bytes). Therefore, we loop. `sys_tcp_recv` blocks execution until data arrives. If it returns `0`, the remote server cleanly closed the connection (which happens automatically because we specified `Connection: close` in our request payload!). 5. **Chunked Receiving (`sys_tcp_recv`)**: The server's response might be larger than our `recv_buf` (512 bytes). Therefore, we loop. `sys_tcp_recv` blocks execution until data arrives. If it returns `0`, the remote server cleanly closed the connection (which happens automatically because we specified `Connection: close` in our request payload!).
6. **`BOREDOS_APP_DESC` / `BOREDOS_APP_ICONS`**: Embedded into the compiled `.elf` as a BoredOS NOTE section. The Desktop and File Explorer read this to display the app's icon. See [`elf_metadata.md`](../elf_metadata.md) for full details.
## 🚀 Running It ## Running It
Make sure QEMU is running with networking enabled. Launch the terminal and type `http_get`. You will see the raw headers and HTML source of the target webpage scroll down the CLI interface! Make sure QEMU is running with networking enabled. Launch the terminal and type `http_get`. You will see the raw headers and HTML source of the target webpage scroll down the CLI interface!

2
docs/architecture/core.md
View file

@ -34,7 +34,7 @@ BoredOS uses **Limine** as its primary bootloader.
5. **Driver Initialization**: PCI buses are scanned, finding the network card or disk controllers. The filesystem is mounted. 5. **Driver Initialization**: PCI buses are scanned, finding the network card or disk controllers. The filesystem is mounted.
6. **Window Manager**: The UI is drawn on top of the Limine-provided framebuffer. 6. **Window Manager**: The UI is drawn on top of the Limine-provided framebuffer.
## 🧵 Multi-Core & Scheduling ## Multi-Core & Scheduling
BoredOS utilizes Symmetric Multi-Processing (SMP) to distribute workloads across all available CPU cores. BoredOS utilizes Symmetric Multi-Processing (SMP) to distribute workloads across all available CPU cores.

4
docs/architecture/window_manager.md
View file

@ -16,7 +16,7 @@ BoredOS features a fully custom, graphical Window Manager built directly into th
> [!TIP] > [!TIP]
> The performance of the window manager heavily depends on minimizing the "dirty regions" drawn in the compositing loop rather than sweeping the whole screen. > The performance of the window manager heavily depends on minimizing the "dirty regions" drawn in the compositing loop rather than sweeping the whole screen.
## 🪟 Window System (`wm.c`) ## Window System (`wm.c`)
The windowing system is built around a linked list of `Window` structures. The windowing system is built around a linked list of `Window` structures.
@ -34,7 +34,7 @@ The WM acts as the central hub for input routing.
- **Event Polling**: The UI loop inside an app continuously calls `ui_poll_event()` to respond to mouse clicks and window movement dispatched by the kernel WM. - **Event Polling**: The UI loop inside an app continuously calls `ui_poll_event()` to respond to mouse clicks and window movement dispatched by the kernel WM.
## 🧵 Multi-Core Safety & Performance ## Multi-Core Safety & Performance
With the introduction of Symmetric Multi-Processing (SMP), the Window Manager (WM) was redesigned to ensure stability and high performance across multiple cores. With the introduction of Symmetric Multi-Processing (SMP), the Window Manager (WM) was redesigned to ensure stability and high performance across multiple cores.