FFPlatform Abstraction Layer in Fastfetch: Cross-Platform System Discovery

FFPlatform is the core cross-platform abstraction layer that centralizes all environment-specific discovery in Fastfetch, exposing a unified data structure containing user directories, system metadata, and executable paths across Linux, macOS, BSD, Windows, and Haiku.

The fastfetch-cli/fastfetch repository uses FFPlatform to decouple OS-specific logic from the presentation layer. Instead of scattering platform-dependent system calls throughout modules, the codebase relies on a single, well-tested initialization phase that populates a comprehensive struct with all necessary environment data.

What is FFPlatform?

FFPlatform is a unified data structure defined in src/common/FFPlatform.h that aggregates essential environment information required by Fastfetch modules. According to the source code, this struct holds:

• User directories: homeDir, cacheDir, configDir, and dataDir
• Process information: exePath, cwd, userId, and processId
• User context: userName, hostName, and shell
• System metadata: A nested FFPlatformSysinfo struct containing name, release, version, architecture, and pageSize

All string fields use Fastfetch’s own FFstrbuf type, while lists utilize FFlist, ensuring consistent memory management across the application.

Platform-Specific Implementation

The abstraction layer delegates actual data discovery to OS-specific implementations selected at compile time. This isolation ensures that modules remain portable, consuming only the populated struct rather than performing direct system calls.

Unix Implementation

The Unix-family implementation resides in src/common/impl/FFPlatform_unix.c and supports Linux, macOS, BSD, Haiku, and Solaris. It retrieves the executable path by reading /proc/self/exe on Linux or using sysctl on BSD systems, determines user directories via standard XDG variables or getpwuid, and gathers system information through uname.

Key helper functions like ffPlatformPathAddHome and ffPlatformPathAddAbsolute normalize path handling across these systems, ensuring consistent trailing slash behavior when constructing directory paths.

Windows Implementation

The Windows counterpart in src/common/impl/FFPlatform_windows.c utilizes WinAPI functions including GetModuleFileNameW for executable discovery and SHGetFolderPathW for retrieving standard folders like AppData and LocalAppData. This implementation handles wide-character string conversion to integrate with Fastfetch’s internal buffer types.

Lifecycle API

FFPlatform provides a strict lifecycle management API declared at lines 36-38 of src/common/FFPlatform.h:

• ffPlatformInit(FFPlatform* platform): Fully populates the struct with platform-specific data during application startup
• ffPlatformDestroy(FFPlatform* platform): Releases all allocated FFstrbuf and FFlist buffers to prevent memory leaks

The initialization function automatically dispatches to the appropriate Unix or Windows implementation through the thin wrapper in src/common/impl/FFPlatform.c.

Integration with Fastfetch Modules

All Fastfetch modules receive a pointer to the initialized FFPlatform instance, eliminating redundant system queries. For example, the OS module reads platform->sysinfo.name directly rather than invoking uname itself.

Basic Usage Example

#include "common/FFPlatform.h"
#include <stdio.h>

int main(void) {
    FFPlatform platform;
    ffPlatformInit(&platform);          // Populate all fields

    printf("User: %s\n", platform.userName.chars);
    printf("Home directory: %s\n", platform.homeDir.chars);
    printf("OS: %s %s (%s)\n",
           platform.sysinfo.name.chars,
           platform.sysinfo.release.chars,
           platform.sysinfo.architecture.chars);
    printf("Executable: %s\n", platform.exePath.chars);

    ffPlatformDestroy(&platform);       // Clean up allocated buffers
    return 0;
}

Module Integration

#include "modules/module.h"
#include "common/FFPlatform.h"

void ffPrintOS(FFPlatform* platform) {
    // The platform instance is passed in by the core.
    ffPrintLogoAndKey("OS", NULL);
    puts(platform->sysinfo.name.chars);
    puts(platform->sysinfo.release.chars);
    puts(platform->sysinfo.architecture.chars);
}

Key Source Files

• src/common/FFPlatform.h: Public struct definition and API declarations
• src/common/impl/FFPlatform.c: Dispatch wrapper for platform selection
• src/common/impl/FFPlatform_unix.c: Unix-family implementation (Linux, macOS, BSD, Haiku)
• src/common/impl/FFPlatform_windows.c: Windows implementation using WinAPI
• src/common/impl/FFPlatform_private.h: Internal helper macros and prototypes

Summary

• FFPlatform centralizes all OS-specific environment discovery into a single initialization phase.
• The abstraction supports Linux, macOS, BSD, Haiku, Solaris, and Windows through dedicated implementation files.
• Memory safety is enforced via ffPlatformInit() and ffPlatformDestroy() using Fastfetch’s internal buffer types.
• Modules consume pre-populated data from the struct, eliminating duplicate system calls and platform-specific code duplication.

Frequently Asked Questions

What information does FFPlatform store?

FFPlatform stores the current user’s home, cache, config, and data directories; the executable and current working paths; user ID, process ID, username, hostname, and shell; plus a nested FFPlatformSysinfo struct containing the operating system name, release, version, architecture, and page size. All data is collected once during initialization and cached for module access.

How does FFPlatform handle different operating systems?

The layer uses compile-time selection to include either src/common/impl/FFPlatform_unix.c or src/common/impl/FFPlatform_windows.c. Each implementation uses native APIs—such as /proc/self/exe and uname on Unix or GetModuleFileNameW on Windows—to fill the same struct fields, ensuring consistent data structures across platforms.

When is FFPlatform initialized during Fastfetch execution?

The main program calls ffPlatformInit(&platform) immediately during startup, before any modules execute. This ensures that all subsequent module calls have immediate access to valid environment data without triggering additional system discovery.

How does FFPlatform manage memory allocation?

The struct uses Fastfetch’s FFstrbuf and FFlist types for all dynamic data. The ffPlatformDestroy() function iterates through these fields to release allocated memory, providing a clean teardown mechanism that prevents leaks when the application exits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}