Hello World Tutorial

Complete tutorial for building your first HolyC BPF program

Beginner ⏱️ 15 minutes Tutorial 1 of 6

Hello World Tutorial

Learn how to create your first HolyC BPF program with this step-by-step tutorial. This example demonstrates the basic structure of a BPF program using HolyC syntax and the divine simplicity of Terry A. Davis’s programming philosophy.

Overview

The Hello World example is the simplest HolyBPF program that demonstrates:

  • Basic HolyC syntax for BPF programs
  • Program entry point structure
  • BPF output using PrintF
  • Divine programming principles

Prerequisites

Before starting this tutorial, ensure you have:

  • ✅ Rust toolchain installed (latest stable version)
  • ✅ Basic understanding of programming concepts
  • ✅ Text editor or IDE of your choice
  • ✅ Terminal access for running commands

Required Setup

  1. Clone the HolyBPF repository: 
    git clone https://github.com/pibleos/holyBPF-rust.git
cd holyBPF-rust
  2. Build the Pible compiler: 
    cargo build --release

    This creates the compiler at target/release/pible.

Code Walkthrough

Let’s examine the Hello World program step by step:

Source Code

<span class="filename">📁 examples/hello-world/src/main.hc</span>
<a href="https://github.com/pibleos/holyBPF-rust/blob/main/examples/hello-world/src/main.hc" class="github-link" target="_blank">View on GitHub</a>

// HolyC BPF Program - Divine Hello World
U0 main() {
    // Entry point for the BPF program
    PrintF("God's light shines upon BPF!\n");
    return 0;
}

Line-by-Line Explanation

Line 1: Comment Header

// HolyC BPF Program - Divine Hello World
  • Purpose: Documents the program’s divine mission
  • Style: Terry Davis inspired naming convention
  • Best Practice: Always include meaningful headers

Line 2: Main Function Declaration

U0 main() {
  • U0: HolyC type meaning “unsigned 0-bit” (equivalent to void)
  • main(): Entry point function for the BPF program
  • Opening brace: Begins the function body

Line 3-4: Divine Output

    // Entry point for the BPF program
    PrintF("God's light shines upon BPF!\n");
  • Comment: Explains the function’s purpose
  • PrintF: BPF-compatible output function for debugging/logging
  • Message: Divine greeting that will appear in BPF execution logs
  • \n: Newline character for proper formatting

Line 5-6: Function Return

    return 0;
}
  • return 0: Indicates successful execution
  • Closing brace: Ends the function body

Building the Program

Follow these steps to compile the Hello World program:

Step 1: Navigate to Project Directory

cd holyBPF-rust

Step 2: Compile with Pible

./target/release/pible examples/hello-world/src/main.hc

Expected Output

=== Pible - HolyC to BPF Compiler ===
Divine compilation initiated...
Source: examples/hello-world/src/main.hc
Target: LinuxBpf
Compiled successfully: examples/hello-world/src/main.hc -> examples/hello-world/src/main.bpf
Divine compilation completed! 🙏

Step 3: Verify Compilation

ls -la examples/hello-world/src/

You should see:

  • main.hc - Original HolyC source code
  • main.bpf - Compiled BPF bytecode
  • types.hc - Type definitions (if present)

Expected Results

Compilation Success

  • ✅ No errors during compilation
  • ✅ BPF file generated (main.bpf)
  • ✅ Divine blessing message displayed

BPF Bytecode

The generated main.bpf file contains:

  • Valid BPF instruction sequences
  • Proper entry point setup
  • Safe memory access patterns
  • BPF verifier compliance

Runtime Behavior

When executed in a BPF environment, the program will:

  1. Load successfully into the BPF virtual machine
  2. Execute the main() function
  3. Output: God's light shines upon BPF!
  4. Return successfully with exit code 0

Understanding BPF Output

The PrintF function in HolyC BPF programs:

  • Purpose: Debugging and logging in BPF programs
  • Output: Appears in BPF trace logs
  • Limitations: Text output only, no complex formatting
  • Security: All output is bounds-checked by BPF verifier

Troubleshooting

Common Issues

Compilation Errors

If you see compilation errors:

  1. Check syntax: Ensure proper HolyC syntax
  2. Verify file path: Confirm the source file exists
  3. Rebuild compiler: Run cargo build --release again

Missing Compiler

If pible command not found:

# Rebuild the compiler
cargo build --release

# Verify it exists
ls -la target/release/pible

Permission Issues

If you get permission errors:

# Make the compiler executable
chmod +x target/release/pible

Next Steps

Congratulations! You’ve successfully compiled your first HolyC BPF program. Here’s what to explore next:

Immediate Next Steps

  1. Escrow Tutorial - Learn multi-party contracts
  2. Token Tutorial - Explore token operations
  3. Code Snippets - Discover reusable patterns

Advanced Topics

<span class="nav-label">Previous Tutorial</span>
<span class="nav-disabled">← None (Start Here)</span>

<a href="/holyBPF-rust/docs/examples/tutorials/" class="nav-home">All Tutorials</a>

<span class="nav-label">Next Tutorial</span>
<a href="/holyBPF-rust/docs/examples/tutorials/escrow" class="nav-next">Escrow Contract →</a>

Divine Inspiration

“An idling CPU is the devil’s playground” - Terry A. Davis

This Hello World program embodies the divine simplicity that Terry Davis championed - clear, purposeful code that accomplishes its mission without unnecessary complexity.

Share This Tutorial

Tutorial completed successfully! You now understand the basics of HolyC BPF programming and can build your first divine programs.