Getting Started with TAIL OS

Welcome to TAIL OS! This guide will help you download, build, run, and develop applications for TAIL OS.

Table of Contents

1. Prerequisites
2. Download and Setup
3. Building TAIL OS
4. Running TAIL OS
5. Developing Applications
6. Troubleshooting

Prerequisites

System Requirements

• Operating System: Ubuntu 24.04 or higher
• Architecture: x86_64 host system
• Memory: At least 4GB RAM
• Storage: At least 10GB free space
• Required Software: The following packages must be installed:

Download and Setup

1. Download

wget https://tail-os.com/wp-content/uploads/2025/09/install_tail_os_for_qemu.sh
wget https://tail-os.com/wp-content/uploads/2025/09/run_tail_os_on_qemu.sh

2. Install

chmod +x ./install_tail_os_for_qemu.sh
./install_tail_os_for_qemu.sh
# Follow the instructions

3. Running TAIL OS

# Set up TAIL OS environment
source ~/.bashrc
chmod +x ./run_tail_os_on_qemu.sh

Expected Output

When TAIL OS boots successfully, you should see:

[START] kernel
[SUCCESS] KERNEL_MEMORY_ALLOCATOR is initialized
[SUCCESS] exception manager is initialized
[SUCCESS] system clock is initialized
#  Type 'exit' to terminate TSH    #

tsh> 

Developing Applications

1. Creating Your Own Application

Step 1: Create Project

# Create a new Rust project in your workspace
cargo new myapp
cd myapp

Step 2: Set the TAIL Toolchain

# Set the TAIL OS Rust toolchain for this project
rustup override set tail_release

Step 3: Build the project

# Build for TAIL OS target
cargo build --target aarch64-unknown-tail --release

The compiled binary will be located at target/aarch64-unknown-tail/release/myapp.

Step 6: Copy Binary to TAIL OS Disk Image

Mount the TAIL OS disk image and copy your application:

# Set the path to your TAIL OS disk image
export IMAGE="${TAIL_ROOT}/os_image/tail_disk.img"

# Create mount point if it doesn't exist
sudo mkdir -p /mnt/tailos

# Mount the TAIL OS disk image
LOOP_DEV=$(sudo losetup -fP --show $IMAGE)
sudo mount -o loop,offset=1048576 -t vfat $LOOP_DEV /mnt/tailos

# Copy your compiled binary to the TAIL OS file system
sudo cp target/aarch64-unknown-tail/release/myapp /mnt/tailos/

# Unmount and cleanup
sudo umount /mnt/tailos
sudo losetup -d $LOOP_DEV

echo "Application copied to TAIL OS disk image successfully!"

2. Executing Your Application

Step 1: Run TAIL OS

# Run TAIL OS with your application
./run_tail_os_on_qemu.sh

Step 2: Execute from Shell

When TAIL OS boots successfully, you’ll see the shell prompt:

[START] kernel
[SUCCESS] KERNEL_MEMORY_ALLOCATOR is initialized
[SUCCESS] exception manager is initialized
[SUCCESS] system clock is initialized
#  Type 'exit' to terminate TSH    #

tsh> 

Type your application name to execute it:

tsh> myapp
Hello, world!

5. Advanced Application Development

Using System Calls

use tail_core::syscall::*;

fn main() {
    // Create a topic for IPC
    let topic_id = create_topic("my_topic").unwrap();

    // Publish data to topic
    let data = b"Hello, World!";
    publish_to_topic(topic_id, data).unwrap();

    // Subscribe to topic
    subscribe_topic(topic_id).unwrap();
}

Memory Management

use tail_core::syscall::*;

fn main() {
    // Allocate memory
    let size = 4096; // 4KB
    let addr = mmap(0, size, PROT_READ | PROT_WRITE).unwrap();

    // Use the memory
    unsafe {
        let slice = std::slice::from_raw_parts_mut(addr as *mut u8, size);
        slice[0] = 42;
    }

    // Free memory
    munmap(addr, size).unwrap();
}

Inter-Process Communication

use tail_core::syscall::*;

fn main() {
    // Create a server
    let server_id = create_server("my_service").unwrap();

    // Handle requests
    loop {
        if let Ok(request) = receive_service_request(server_id) {
            // Process request
            let response = b"Response data";
            reply_to_service_request(request.id, response).unwrap();
        }
    }
}

6. Debugging Applications

Using GDB

# Build with debug symbols
cargo build --target aarch64-unknown-tail

# Run with GDB
make run-gdb

# In GDB
(gdb) target remote localhost:1234
(gdb) file target/aarch64-unknown-tail/debug/myapp
(gdb) break main
(gdb) continue

Using Kernel Print

use tail_core::kprint;

fn main() {
    kprint!("Debug: Application startedn");
    kprint!("Debug: Variable value = {}n", 42);
}

Troubleshooting

Common Issues

Build Failures

# Clean and rebuild
make clean
make build-debug

QEMU Issues

# Check QEMU installation
qemu-system-aarch64 --version

# Try different QEMU options
qemu-system-aarch64 -M raspi3b -kernel ${TAIL_ROOT}/os_image/tail.rfs -serial stdio

Rust Toolchain Issues

# Update Rust
rustup update

# Reinstall target
rustup target remove aarch64-unknown-tail
rustup target add aarch64-unknown-tail

Cross-Compiler Issues

# Rebuild toolchain
cd toolchain/aarch64-elf-gcc
./build_target_toolchain.sh

Getting Help

• Documentation: Check doc/ directory for detailed documentation
• Issues: Report bugs and ask questions on the project repository
• Community: Join discussions in project forums

Development Tips

1. Start Simple: Begin with basic applications before complex ones
2. Use Debug Builds: Debug builds include more error checking
3. Test Frequently: Test your applications regularly during development
4. Read Documentation: Familiarize yourself with tail_core API
5. Use GDB: Debugging is essential for complex applications

---

This guide provides the foundation for TAIL OS development. For advanced topics, refer to the detailed documentation in the doc/ directory.