herolib/lib/osal/readme.md

Operating System Abstraction Layer (OSAL)

A comprehensive operating system abstraction layer for V that provides platform-independent system operations, process management, and network utilities.

Features

• Platform detection and system information
• Process execution and management
• Network utilities (ping, TCP port testing)
• Environment variable handling
• File system operations
• SSH key management
• Profile path management

Platform Detection

import freeflowuniverse.herolib.osal

// Get platform type
platform := osal.platform()
if platform == .osx {
    // macOS specific code
}

// Platform-specific checks
if osal.is_linux() {
    // Linux specific code
}
if osal.is_osx_arm() {
    // Apple Silicon specific code
}

// CPU architecture
cpu := osal.cputype()
if cpu == .arm {
    // ARM specific code
}

// System information
hostname := osal.hostname()!
init_system := osal.initname()!  // e.g., systemd, bash, zinit

Process Execution

The module provides flexible process execution with extensive configuration options:

// Simple command execution
job := osal.exec(cmd: 'ls -la')!
println(job.output)

// Execute with error handling
job := osal.exec(Command{
    cmd: 'complex_command'
    timeout: 3600        // timeout in seconds
    retry: 3             // retry count
    work_folder: '/tmp'  // working directory
    environment: {       // environment variables
        'PATH': '/usr/local/bin'
    }
    stdout: true         // show output
    raise_error: true    // raise error on failure
})!

// Silent execution
output := osal.execute_silent('command')!

// Interactive shell execution
osal.execute_interactive('bash command')!

// Debug mode execution
output := osal.execute_debug('command')!

Job Status and Error Handling

// Check job status
if job.status == .done {
    println('Success!')
} else if job.status == .error_timeout {
    println('Command timed out')
}

// Error handling with specific error types
job := osal.exec(cmd: 'invalid_command') or {
    match err.error_type {
        .exec { println('Execution error') }
        .timeout { println('Command timed out') }
        .args { println('Invalid arguments') }
        else { println(err) }
    }
    return
}

Network Utilities

Ping

// Simple ping
result := osal.ping(address: '8.8.8.8')!
assert result == .ok

// Advanced ping configuration
result := osal.ping(PingArgs{
    address: '8.8.8.8'
    count: 3        // number of pings
    timeout: 2      // timeout in seconds
    retry: 1        // retry attempts
})!

match result {
    .ok { println('Host is reachable') }
    .timeout { println('Host timed out') }
    .unknownhost { println('Unknown host') }
}

TCP Port Testing

// Test if port is open
is_open := osal.tcp_port_test(TcpPortTestArgs{
    address: '192.168.1.1'
    port: 22
    timeout: 2000  // milliseconds
})

if is_open {
    println('Port is open')
}

// Get public IP address
pub_ip := osal.ipaddr_pub_get()!
println('Public IP: ${pub_ip}')

Profile Management

Manage system PATH and other profile settings:

// Add/remove paths from system PATH
osal.profile_path_add_remove(
    paths2delete: 'go/bin',
    paths2add: '~/hero/bin,~/usr/local/bin'
)!

Environment Variables

// Get environment variable
value := osal.env_get('PATH')!

// Set environment variable
osal.env_set('MY_VAR', 'value')!

// Check if environment variable exists
exists := osal.env_exists('MY_VAR')

Notes

• All commands are executed from temporary scripts in /tmp/execscripts
• Failed script executions are preserved for debugging
• Successful script executions are automatically cleaned up
• Platform-specific behavior is automatically handled
• Timeout and retry mechanisms are available for robust execution
• Environment variables and working directories can be specified per command
• Interactive and non-interactive modes are supported
• Debug mode provides additional execution information

Error Handling

The module provides detailed error information:

• Exit codes
• Standard output and error streams
• Execution time and duration
• Process status
• Retry counts
• Error types (execution, timeout, arguments)

Platform Support

• macOS (Intel and ARM)
• Ubuntu
• Alpine Linux
• Arch Linux
• SUSE (partial)

CPU architectures:

• Intel (x86_64)
• ARM (arm64/aarch64)
• 32-bit variants (intel32, arm32)