Jannis/BoredOS
1
0
Fork 0
mirror of https://github.com/JannisHeydemann/BoredOS.git synced 2026-05-30 02:16:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

DOC: Example applications in documentation

Browse Source
This commit is contained in:
boreddevnl
2026-03-17 18:52:03 +01:00
parent 5b10127e02
commit 2817ad51da
9 changed files with 561 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/appdev/examples/01_hello_cli.md Normal file
View File

@@ -0,0 +1,52 @@
<div align="center">
<h1>Example 01: Hello CLI</h1>
<p><em>The absolute basics. Writing a terminal program.</em></p>
</div>
---
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
* Including `stdlib.h` for basic IO.
* The `main()` entry point.
* Using `printf()` for formatted output.
---
## 💻 The Code (`src/userland/cli/hello_world.c`)
```c
#include <stdlib.h>
int main(int argc, char **argv) {
// Standard library initialization is handled automatically by crt0.asm
// Print a simple string to the terminal
printf("Hello, World from BoredOS Userland!\n");
// Print some formatted data
int favorite_number = 67;
printf("Did you know my favorite number is %d?\n", favorite_number);
// Returning from main automatically terminates the process cleanly
return 0;
}
```
## 🛠️ How it Works
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`).
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.
## 🚀 Running It
If you build the project, you can open the Terminal and type:
```sh
/ # hello_world
Hello, World from BoredOS Userland!
Did you know my favorite number is 67?
/ #
```

71
docs/appdev/examples/02_basic_window.md Normal file
View File

@@ -0,0 +1,71 @@
<div align="center">
<h1>Example 02: Basic Window</h1>
<p><em>An introduction to libui and creating graphical apps.</em></p>
</div>
---
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
* Including `libui.h` and the event structure.
* Creating a `ui_window_t` handle.
* Creating an infinite event loop using `ui_get_event()`.
* Yielding CPU time to the kernel via `sys_yield()`.
---
## 💻 The Code (`src/userland/gui/basic_window.c`)
```c
#include <stdlib.h>
#include <libui.h>
#include <syscall.h>
int main(void) {
// 1. Ask the Window Manager to create a new window
// Arguments are: Title, X Position, Y Position, Width, Height
ui_window_t wid = ui_window_create("My First GUI", 100, 100, 400, 300);
if (wid < 0) {
printf("Failed to create the window!\n");
return 1;
}
// 2. Define our event object
gui_event_t event;
// 3. Enter the main event loop
while (1) {
// ui_get_event is non-blocking. It returns true if an event was waiting.
if (ui_get_event(wid, &event)) {
// Check what type of event occurred
if (event.type == GUI_EVENT_CLOSE) {
// The user clicked the 'X' button in the titlebar!
printf("Window closed cleanly by user.\n");
break; // Break the infinite loop
}
}
// 4. CRITICAL: Yield the remainder of our timeslice
// If we don't do this, the while(1) loop will consume 100% of the CPU
// and starve the rest of the OS!
sys_yield();
}
// Returning from main will automatically destroy the window and exit the process.
return 0;
}
```
## 🛠️ How it Works
1. **Window Handle (`wid`)**: `ui_window_create` sends a request to the kernel. The kernel allocates the memory for the window and returns a numerical ID (the handle) that we use for all future interactions with that specific window.
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.
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."
## 🚀 Running It
Launch the Terminal and type `basic_window`. You'll see an empty window appear that you can move around the screen!

92
docs/appdev/examples/03_bouncing_ball.md Normal file
View File

@@ -0,0 +1,92 @@
<div align="center">
<h1>Example 03: Bouncing Ball</h1>
<p><em>Animating graphics and managing application state.</em></p>
</div>
---
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
* Maintaining application state across frames (Velocity/Position).
* Drawing primitives (`ui_fill_rect`, `ui_draw_string`).
* The importance of clearing the screen on a new frame.
* Explicitly forcing standard visual updates via `ui_mark_dirty()`.
---
## 💻 The Code (`src/userland/gui/bounce.c`)
```c
#include <stdlib.h>
#include <libui.h>
#include <syscall.h>
// Window Dimensions
#define W_WIDTH 400
#define W_HEIGHT 300
// Square Dimensions
#define SQ_SIZE 30
int main(void) {
ui_window_t wid = ui_window_create("Bouncing Box Animation", 50, 50, W_WIDTH, W_HEIGHT);
if (wid < 0) return 1;
// Define object state variables
int pos_x = 50;
int pos_y = 50;
int vel_x = 2; // Move 2 pixels per frame horizontally
int vel_y = 2; // Move 2 pixels per frame vertically
gui_event_t event;
while (1) {
// 1. Process Events
while (ui_get_event(wid, &event)) {
if (event.type == GUI_EVENT_CLOSE) {
return 0; // Exit cleanly
}
}
// 2. Physics & Logic Update
pos_x += vel_x;
pos_y += vel_y;
// Collision logic (Bounce off edges)
// The window has a 20px title bar, so the usable client height is W_HEIGHT - 20.
if (pos_x <= 0 || pos_x + SQ_SIZE >= W_WIDTH) {
vel_x = -vel_x; // Reverse horizontal direction
}
if (pos_y <= 0 || pos_y + SQ_SIZE >= W_HEIGHT - 20) {
vel_y = -vel_y; // Reverse vertical direction
}
// 3. Rendering Update
// Step A: Clear the entire background to Black (0xFF000000)
ui_draw_rect(wid, 0, 0, W_WIDTH, W_HEIGHT, 0xFF000000);
// Step B: Draw our shape in Red (0xFFFF0000) at the new position
ui_draw_rect(wid, pos_x, pos_y, SQ_SIZE, SQ_SIZE, 0xFFFF0000);
// Step C: Draw some UI text over the animation in White
ui_draw_string(wid, 10, 10, "BoredOS Animation Demo!", 0xFFFFFFFF);
// Step D: Instruct the compositor to flush our drawing buffer to the physical screen
ui_mark_dirty(wid, 0, 0, W_WIDTH, W_HEIGHT);
// 4. Yield and throttle
sys_yield();
}
return 0;
}
```
## 🛠️ 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.
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.
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?"
> [!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.

92
docs/appdev/examples/04_tcp_client.md Normal file
View File

@@ -0,0 +1,92 @@
<div align="center">
<h1>Example 04: TCP HTTP Client</h1>
<p><em>Utilizing lwIP to establish an outbound TCP connection.</em></p>
</div>
---
This advanced example demonstrates the steps required to use the raw network system calls to establish a connection with an external HTTP server and dump the response over the terminal.
## 📝 Concepts Introduced
* Verifying the network state (`sys_network_is_initialized`, `sys_network_has_ip`).
* Performing DNS lookups manually via `sys_dns_lookup`.
* Managing strict TCP flow logic (`sys_tcp_connect`, send, block for receive).
* Using the terminal `SYS_WRITE` output for debugging.
---
## 💻 The Code (`src/userland/cli/http_get.c`)
```c
#include <stdlib.h>
#include <string.h>
#include <syscall.h>
int main(void) {
if (!sys_network_is_initialized() || !sys_network_has_ip()) {
printf("Network is unreachable! Make sure you inited the network first!\n");
return 1;
}
// 1. Resolve host name to IP
const char *target_host = "boreddev.nl";
net_ipv4_address_t server_ip;
printf("Resolving %s...\n", target_host);
if (sys_dns_lookup(target_host, &server_ip) < 0) {
printf("DNS Lookup failed.\n");
return 1;
}
printf("Resolved to: %d.%d.%d.%d\n", server_ip.bytes[0], server_ip.bytes[1],
server_ip.bytes[2], server_ip.bytes[3]);
// 2. Establish a TCP connection on port 80 (HTTP)
printf("Connecting...\n");
if (sys_tcp_connect(&server_ip, 80) < 0) {
printf("Connection failed.\n");
return 1;
}
printf("Connected! Sending GET request...\n");
// 3. Format and send the raw HTTP Request
char request[256];
strcpy(request, "GET / HTTP/1.1\r\nHost: ");
strcat(request, target_host);
strcat(request, "\r\nConnection: close\r\n\r\n");
if (sys_tcp_send(request, strlen(request)) < 0) {
printf("Failed to send data.\n");
sys_tcp_close();
return 1;
}
// 4. Block and wait for response data
char recv_buf[512];
int bytes_received;
printf("\n--- RESPONSE ---\n");
while ((bytes_received = sys_tcp_recv(recv_buf, sizeof(recv_buf) - 1)) > 0) {
recv_buf[bytes_received] = '\0'; // Null-terminate the chunk
printf("%s", recv_buf); // Print the chunk to stdout
}
// 5. Cleanup
printf("\n--- END RESPONSE ---\n");
sys_tcp_close();
printf("Connection closed.\n");
return 0;
}
```
## 🛠️ 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.
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.
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!).
## 🚀 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!

28
docs/appdev/examples/README.md Normal file
View File

@@ -0,0 +1,28 @@
<div align="center">
<h1>Example Applications</h1>
<p><em>From basic output to complex Graphical and Network applications.</em></p>
</div>
---
Welcome to the examples directory! These guides are designed to help you understand how to write C applications for the BoredOS userland, utilizing the custom `libc` SDK.
The examples are listed in order of increasing complexity. Click on a tutorial to view the complete source code and an explanation of the concepts it introduces.
## 🟢 Beginner
* **[`01_hello_cli.md`](01_hello_cli.md)**: The absolute basics. Learn how to write a simple Terminal program that outputs text and processes standard system calls.
* **[`02_basic_window.md`](02_basic_window.md)**: An introduction to `libui.h`. Learn how to create an empty window, set up a basic event loop, and handle the "Close" button cleanly.
## 🟡 Intermediate
* **[`03_bouncing_ball.md`](03_bouncing_ball.md)**: Dive deeper into graphical rendering. This example introduces the `ui_mark_dirty` command, framerate independence via `sys_yield()`, and state management to animate a shape moving around the screen and bouncing off the window edges.
## 🔴 Advanced
* **[`04_tcp_client.md`](04_tcp_client.md)**: Using the lwIP networking stack. This example demonstrates how to perform a DNS lookup, connect to an external server over TCP (like an HTTP server), send a raw request, and print the response to the terminal.
---
> [!TIP]
> If you want to test these out, simply create a new `.c` file in `src/userland/cli/` (for terminal apps) or `src/userland/gui/` (for windowed apps), paste the example code, then run `make clean && make run` from the project root!