boredos_mirror/docs/appdev/custom_apps.md

Creating a Custom App (Step-by-Step)

This guide explains how to write a new "Hello World" application locally, compile it as an .elf binary into the bin/ folder, and launch it inside BoredOS.

Step 1: Write the C Source

Applications reside entirely in the src/userland/ directory. Create a new file, for example, src/userland/gui/hello.c.

Tip

Group CLI apps into src/userland/cli/ and windowed apps into src/userland/gui/ for organization.

// src/userland/gui/hello.c
#include <stdlib.h>
#include <libui.h>

int main(void) {
    // Attempt to open a 300x200 window
    int wid = ui_create_window("My Custom App", 300, 200, 0);
    if (wid < 0) {
        printf("Error creating window!\n");
        return 1;
    }
    
    // Write text in center
    ui_draw_string(wid, "Hello, BoredOS!!", 50, 90, 0xFFFFFFFF);
    
    // Commit drawing to screen
    ui_swap_buffers(wid);

    ui_event_t event;
    while (1) {
        if (ui_poll_event(&event)) {
            if (event.window_id == wid && event.type == UI_EVENT_WINDOW_CLOSE) {
                break; // Exit loop if 'X' is clicked
            }
        }
        
        syscall1(SYSTEM_CMD_YIELD, 0);
    }

    return 0; // Returning 0 smoothly exits the process via crt0.asm
}

Step 2: Edit the Makefile

Now you need to tell the build system to compile hello.c. Fortunately, the src/userland/Makefile is designed to detect new C files largely automatically!

1. Open src/userland/Makefile.
2. Find the line specifying APP_SOURCES_FULL:

   APP_SOURCES_FULL = $(wildcard cli/*.c gui/*.c sys/*.c games/*.c *.c)
   

   Since you placed the file in gui/hello.c, the wildcard logic will pick it up automatically.
3. The Makefile will generate bin/hello.elf during the build phase.

Step 3: Bundle it into the OS

The main overarching Makefile (in the project root) takes binaries from src/userland/bin/*.elf and places them into the iso_root/bin/ directory, while also adding them to limine.conf as loadable boot modules.

1. Go back to the root of the OS:

   cd ../..
   

2. Compile the entire project to build the ISO and test in QEMU:

   make clean && make run
   

Step 4: Run it inside BoredOS

1. When BoredOS boots, launch the Terminal application.
2. The OS automatically maps built applications to standard shell commands. Simply type your application's filename (without the .elf extension).
3. Type hello in the terminal and press Enter.
4. Your custom window will appear!

you can also open your app by opening the file explorer and navigating to the bin directory and double clicking the executable.