bMETAL / DOS64

About / Application portability

Build once for each format

Write a freestanding C application against the DOS64 SDK. Compile it on Linux as an ELF binary for DOS64, or build a PE executable with MinGW-w64. The same PE executable can run in DOS64 and on Windows with the included bmetal.dll.

Build targetToolchainRun in DOS64Run on Windows
ELF64 .lnxLinux GCCYes, using the DOS64 entry point and ABINo, use the PE build instead
PE32+ .exeMinGW-w64 on Linux or WindowsYes, using DOS64 runtime importsYes, the same executable with matching bmetal.dll

Build host is not runtime target. Building on Linux does not make the result a normal Linux application. Both targets are freestanding: no host CRT startup, general-purpose libc, Linux syscalls, or arbitrary Windows API dependencies. Windows hosting is provided by the SDK DLL, not by turning DOS64 into a Windows-compatible OS.

Build ELF on Linux

Extract the standalone SDK and save this example as hello.c. The same application callback is used by both builds below.

#include <dos64_stdio.h>

int __attribute__((ms_abi)) start(const DOS64_API *Api)
{
    stdio_init(Api);
    puts("Hello from a freestanding application");
    printf("Arguments: %s\n", Api->Arguments);
    return 0;
}

From the extracted SDK directory, compile with Linux x86-64 GCC:

gcc -m64 -ffreestanding -nostdlib -nostartfiles -fPIC \
  -fno-stack-protector -mno-red-zone -fno-unwind-tables \
  -fno-asynchronous-unwind-tables -O2 -Wall -Wextra \
  -shared -Wl,-e,start,-Bsymbolic,--build-id=none,-z,defs,-z,max-page-size=4096 \
  -Iinclude hello.c -o hello.lnx

This creates a position-independent ELF64 image with entry point start. DOS64 passes the API table using the Microsoft x64 ABI even for ELF, so retain __attribute__((ms_abi)). The ELF build needs neither dos64_startup.o nor the PE import library or DLL.

Copy hello.lnx to a DOS64 data volume and run it from the DOS64 shell. The .lnx extension identifies this DOS64 ELF target; it does not mean you can launch it in a Linux shell.

Build PE for DOS64 and Windows

Use the same hello.c with MinGW-w64. On Linux, this is a cross-compile; on Windows, run the command in a MinGW-w64 shell (the compiler may be named gcc there). The headers, startup object, import library, and DLL are all in the standalone SDK.

x86_64-w64-mingw32-gcc -m64 -O2 -Wall -Wextra -Werror \
  -ffreestanding -nostdlib -nostartfiles -fno-stack-protector -mno-red-zone \
  -Iinclude -Wl,-e,dos64_entry -Wl,--subsystem,console -Wl,--dynamicbase \
  hello.c lib/dos64_startup.o -Llib -lbmetal -o hello.exe

dos64_startup.o provides the PE entry dos64_entry and negotiates the runtime before calling start(Api). libbmetal.dll.a links the Dos64Run import. DOS64 resolves this through its kernel; Windows resolves it through the matching bmetal.dll.

The application remains freestanding. The Windows DLL implements its host-side services using Windows facilities; that does not make the application itself dependent on a host CRT. PE is the Portable Executable format, not Windows Preinstallation Environment.

When a GUI-subsystem PE application starts on Windows, bmetal.dll briefly displays a bMETAL logo and Windows/runtime system summary before launching the application. The splash closes automatically after three seconds. DOS64 and console-subsystem startup are unchanged.

Run and distribute

EnvironmentFiles and invocation
DOS64 / ELFCopy hello.lnx; run C:\HELLO.LNX test in DOS64.
DOS64 / PECopy hello.exe; run C:\HELLO.EXE test. The Windows DLL is not required by DOS64.
Windows / PEPut the same hello.exe and SDK bin\bmetal.dll together in one directory; run .\hello.exe test in PowerShell.

Stop the VM before copying files into its image. Keep the executable and DLL built for compatible runtime/API versions. Check optional capabilities such as audio: Windows success does not guarantee that the same device service exists on a particular DOS64 machine.

Freestanding does not mean isolated. DOS64 programs execute in ring 0. Use trusted applications and disposable test data. Ordinary Linux executables and arbitrary Windows programs do not become DOS64-compatible simply by renaming them.

For detailed service contracts, version checks, and module examples, continue to the SDK documentation.