Warp

Warp Native Architecture and Standards

/

File Naming Conventions

  • Namespace headers are written in lowercase (e.g., warp.h, api.h) and primarily serve to define or extend namespaces.
  • Class headers use PascalCase (e.g., Win.h, Web.h) and contain concrete class definitions.

OS-Specific Implementation

For platform-dependent code:

  • Each operating system must have its own implementation file.
  • All OS-specific implementations must be stored in a folder named after the base header file (e.g., Win → src/warp/Win/).
  • OS-specific headers must use platform-identifying suffixes:
    • _MS for Windows
    • _Linux for Linux
    • _OSX for macOS

If a class or module supports multiple platforms:

  • A general header (e.g., Win.h) is placed in the same folder alongside platform-specific headers.
  • The general header includes the appropriate OS-specific header at compile time.

This simplifies git management.

Example: Win class layout

src/warp/Win/
           ├── Win.h
           ├── Win_MS.h
           ├── Win_Linux.h
           └── Win_OSX.h

Namespace Hierarchy and Initialization

  • All code is encapsulated under the top-level namespace warp, defined in src/warp/warp.h.
  • This file is included in main.cpp to initialize the environment.
  • warp.h includes:
    • api/api.h: adds the warp::api namespace and several endpoints under it
    • structs.h: common data structures
    • Win.h, Web.h: core classes for windowing and HTML rendering

Namespace Overview After Initialization

This is a simple view of an app instance hierarchy after everything is loaded

A closeup of messaging between engine.js in the webview/Win and warp::api on the Native side

API Method Structure

All functions exposed to the Warp engine (e.g., frontend/web layer) must follow this async signature:

These functions should be:

  • Async
  • OS-agnostic
  • Portable C++17, suitable for all supported platforms

Platform-specific logic must not be placed inside warp::api::... namespaces.!!!

Folder Structure Reflects Namespace Layout

The project “src” directory structure mirrors the logical namespace hierarchy in an instance.
This alignment ensures clarity and maintainability.

 ├── vendor/                   # Drivers, distributed files  
 └── src/
      │
      ├── deps/                    # External libraries
      │   ├── webview/
      │   ├── CEF/
      │   ├── CivetServer.h
      │   ├── POCO/
      │   └── json.hpp
      │
      ├── warp/                    # Core Warp codebase
      │   ├── structs.h            # Shared data types
      │   ├── warp.h               # Root namespace definition and general header
      │   ├── Web.h                # Web class ( a page )
      │   ├── Win/                 # Native window with a web GUI based on webview.h and warp.js 
      │   │   ├── Win.h
      │   │   ├── Win_Linux.h
      │   │   ├── Win_MS.h
      │   │   └── Win_OSX.h
      │   │
      │   └── api/                 # Exposed API endpoints
      │       ├── api.h
      │       ├── api.drives.h
      │       ├── api.gui/
      │       │       ├── api.gui.h
      │       │       ├── api.gui_Linux.h
      │       │       ├── api.gui_MS.h
      │       │       └── api.gui_OSX.h
      │       ├── api.installation.h
      │       ├── api.instance.h
      │       ├── api.network.h
      │       ├── api.webs.h
      │       └── api.windows.h
      │
      └── main.cpp                 # Application entry point

Stack

  • Language: C++17
  • Build: CMake for configuration and compilation; CPack for packaging

Libraries and Dependencies

  • POCO: Application lifecycle, configuration, filesystem
  • nlohmann::json: Serialization
  • CEF: Embedded web rendering, we also leave webview.h
  • CivetWeb: Embedded HTTP server
  • Web.h: In-house developed wrapper using CEF and, optionaly, CivetWeb for Virtual Hosts
  • Win.h: In-house developed cross-platform windowing abstraction based on Web.h
  • Api.h: In-house developed static async API endpoints organized by namespace, compiled into dynamic libraries in modules folder of the binary distribution, per platform.

Packaging

CPack is used to generate native installers for each platform:

  • Windows: NSIS or WiX
  • macOS: .dmg or .pkg
  • Linux: .deb, .rpm, or .tar.gz

Build and Packaging Process

The project source tree is structured under src/warp/, which includes core headers, platform abstractions, and modular API endpoints.
API endpoints ( *.h files ) are compiled as dynamic libraries (.dll, .dylib, .so) and stored in application directories under modules. These are loaded at runtime, supporting silent and incremental updates via download and replacement.

# a simplified view of project "src" folder structure
src/warp/
       ├── structs.h
       ├── warp.h
       ├── Web.h
       ├── Win/
       │   ├── Win.h
       │   ├── Win_Linux.h
       │   ...etc
       │   
       └── api/
           ├── api.h
           ├── api.gui.h
           ..etc

Build System

CMake is used to configure and build platform-specific binaries. Each API namespace (now, when compiled we can call it a module) (e.g. windows, gui, network) is defined in its own header file and compiled as a standalone dynamic library. OS-specific logic is isolated via _Linux.h, _MS.h, and _OSX.h files where needed.

Output Structure

The resulting application is organized into a consistent installation layout by CPack, with platform-appropriate dynamic libraries:

/Warp/ {.app }                 # App folder, abbreviated ".app" for OSX 
├── warp {.exe }               # Main binary, abbreviated ".exe" for MS, core dependencies like POCO, JSON, webview...
├── vendor/                    # External data, drivers, support files
├── modules/                   # Dynamically loaded API modules (same as items in src/warp/api folder in project)
│   ├── windows.{dll|dylib|so}
│   ├── webs.{dll|dylib|so}
│   ├── network.{dll|dylib|so}
│   ├── gui.{dll|dylib|so}
│   ├── instance.{dll|dylib|so}
│   ├── installation.{dll|dylib|so}
│   └── drives.{dll|dylib|so}
├── config/
│   └── appsettings.json
└── resources/
    └── app.ico

Each dynamic module is compiled per platform:

  • Windows: .dll
  • macOS: .dylib
  • Linux: .so

These are loaded at runtime via the Warp runtime loader.

*.warp – proposed CrossPlatform WASM Module Format

In the future, API modules could optionally be compiled to WebAssembly using Emscripten. These .warp files will conform to the warp::api interface (namespaced, async methods) and serve as a cross-platform dynamic plugin format:

  • Filename: module.warp (WASM binary)
  • Compiled once, usable across all desktop platforms and also the JavaScript runtime (warp.js)
  • Advantages:
    • Uniform distribution format
    • Runtime safety (sandboxed)
    • Easy update mechanism (download/replace .warp files)
    • Plugin compatibility between native and web environments

Custom loading logic would be implemented to handle .warp runtime integration and dependency wiring. At present, this is a proposal and not yet part of the build.