os

Portable process and file-system APIs for Eiffel

os is a void-safe Eiffel library for portable process execution and common file-system operations. It provides the same public API to EiffelStudio and Gobo Eiffel on Linux, macOS, and Windows.

Use it when an application needs to:

• run a program without constructing a shell command;
• capture, stream, inherit, discard, or merge its standard streams;
• configure its environment, working directory, and execution deadline;
• compose paths and perform common file and directory operations.

Warning

The library is still being tested and its public API is being refined. Breaking changes should be expected.

Installation

Add the repository to an Eiffel project. A Git submodule keeps the selected library revision explicit:

git submodule add https://github.com/samedit66/os.git vendor/os
git submodule update --init

Reference the package from the consuming project's ECF file:

<library name="os" location="./vendor/os/os.ecf" readonly="true"/>

The library requires Eiffel thread support. Enable it in the consuming target:

<capability>
    <concurrency support="thread" use="thread"/>
</capability>

On Linux and macOS, ensure that make, a C11 compiler, and an archiver are on PATH, then build the native archive before compiling the Eiffel project:

make -C vendor/os native

This produces vendor/os/build/native/libos_native.a. Set CC or AR when the default cc and ar commands are not appropriate.

On Windows, run the native build from a regular Command Prompt. The script locates an installed Visual Studio C++ toolchain and produces vendor\os\build\native\os_native.lib:

vendor\os\build-native.cmd

Quick start

Create a command with an explicit argument vector, run it, and inspect its result:

local
    command: OS_COMMAND
do
    create command.make ("git", <<"--version">>)
    command.set_timeout_milliseconds (5_000)
    command.run

    if command.successful then
        io.put_string (command.stdout)
    else
        across command.failures as failure loop
            io.error.put_string (failure.description)
            io.error.put_new_line
        end
    end
end

OS_COMMAND.make passes its arguments directly to the child; they do not need shell escaping. Standard output and error are captured by default, and run waits until the result queries are available.

Continue with the getting-started tutorial, which covers installation, process results, timeouts, environments, and file paths. See the reference guide for lifecycle guarantees, stream modes, failure semantics, and platform-specific behavior. The process API comparison explains where OS_COMMAND is stronger than the EiffelStudio and Gobo alternatives and where it currently has fewer capabilities. The complete tutorial program is in examples/quick_start.

Public API

Class	Purpose
OS_COMMAND	Configure and execute a command
OS_ENVIRONMENT	Store an environment snapshot and resolve executables through PATH
OS_PROCESS_FAILURE	Inspect a structured process-library failure
OS_FILE_PATH	Compose paths and perform file and directory operations

The Eiffel classes and their contracts are the source of truth for individual feature signatures and preconditions. The reference guide explains how those features work together.

Scope

The process API focuses on common portable workflows. It deliberately does not provide incremental interactive input, PTYs, file-backed redirection, graceful signal protocols, or child-PID enumeration. Use a platform-specific process library when one of those capabilities is required.

Development

Building requires Gobo Eiffel 26.06, EiffelStudio 25.12 or later, and a C11 compiler with an archiver. The main development commands are:

make gobo       # build and run the quick-start example with Gobo Eiffel
make ise        # build and run the quick-start example with EiffelStudio
make test       # run the shared suite with both compilers
make check      # run gelint and the EiffelStudio Code Analyzer
make format     # format tracked Eiffel sources with gedoc
make ccheck     # analyze the handwritten C bridge with clang-tidy
make cformat    # format the handwritten C bridge with clang-format

CI runs the shared test suite on Ubuntu, macOS, and Windows.