RedPanda-CPP/docs/addon.md

Add-on Interface (Unstable)

Basic

• Add-on is a Lua script.
• Values passed or returned to Red Panda C++ must be JSON compatible, i.e.,
  • nil (maps to null)
  • boolean
  • number
  • string
  • empty table (maps to null)
  • table with only array part (maps to array)
  • table with only hash part (maps to object)
• Red Panda C++ APIs exposed to add-on are organized by groups.
  • Each group is a Lua table.
  • Each API is a function in the table.
  • Available API groups vary by add-on type.
• Localization is handled by add-on. e.g.

  local lang = C_Desktop.language()
  local localizedName = {
      en_US = "System",
      pt_BR = "Sistema",
      zh_CN = "系统",
      zh_TW = "系統",
  }
  return {
      name = localizedName[lang] or localizedName.en_US,
      -- ...
  }
  

Simple Add-on

A simple add-on is a Lua script that returns a single value.

Compiler Hint Add-on

If $appLibexecDir/compiler_hint.lua exists, it will be executed as compiler hint add-on when searching for compiler.

Available API groups:

• C_Debug
• C_Desktop
• C_FileSystem
• C_System
• C_Util

Return value schema:

{
    // found compiler sets
    compilerList: [compilerSet],

    // do not search in these directories anymore
    noSearch: [string],

    // prefer compiler set index (in Lua, 1-based) in compilerList
    // 0 for no preference
    preferCompiler: number,
}

compilerSet schema:

{
    name: string,

    // internal
    dumpMachine: string, // e.g. "x86_64-linux-gnu", "x86_64-w64-mingw32"
    version: string, // e.g. "13.2.1", "17.0.6"
    type: string, // e.g. "TDM-GCC", "MinGW"
    target: string, // e.g. "x86_64", "aarch64"
    compilerType: string, // "GCC" or "Clang"

    // general
    staticLink: boolean,
    customCompileParams: [string], // automatically sets useCustomCompileParams
    customLinkParams: [string], // automatically sets useCustomLinkParams
    execCharset: string, // automatically sets autoAddCharsetParams

    // setting
    // - code generation
    ccCmdOptOptimize: string,
    ccCmdOptStd: string,
    cCmdOptStd: string,
    ccCmdOptInstruction: string,
    ccCmdOptPointerSize: string,
    ccCmdOptDebugInfo: string,
    ccCmdOptProfileInfo: string,
    ccCmdOptSyntaxOnly: string,
    // - warnings
    ccCmdOptInhibitAllWarning: string,
    ccCmdOptWarningAll: string,
    ccCmdOptWarningExtra: string,
    ccCmdOptCheckIsoConformance: string,
    ccCmdOptWarningAsError: string,
    ccCmdOptAbortOnError: string,
    ccCmdOptStackProtector: string,
    ccCmdOptAddressSanitizer: string,
    // - linker
    ccCmdOptUsePipe: string,
    linkCmdOptNoLinkStdlib: string,
    linkCmdOptNoConsole: string,
    linkCmdOptStripExe: string,

    // directory
    binDirs: [string],
    cIncludeDirs: [string],
    cxxIncludeDirs: [string],
    libDirs: [string],
    defaultLibDirs: [string],
    defaultCIncludeDirs: [string],
    defaultCxxIncludeDirs: [string],

    // program
    cCompiler: string,
    cxxCompiler: string,
    make: string,
    debugger: string,
    debugServer: string,
    resourceCompiler: string,

    // output
    preprocessingSuffix: string,
    compilationProperSuffix: string,
    assemblingSuffix: string,
    executableSuffix: string,
    compilationStage: number,
}

API Groups

C_Debug

C_Debug is available to all add-on types.

• C_Debug.debug: (message: string) -> (), print message to console (via qDebug()).

C_Desktop

• C_Desktop.desktopEnvironment: () -> string, return desktop environment name.
  • windows: Windows (Win32 only)
  • macos: macOS
  • xdg: XDG-compliant desktop environment (e.g. GNOME, KDE Plasma)
  • unknown: other desktops or non-desktop environments (e.g. Windows UWP, Android)
• C_Desktop.language: () -> string, return language code.
  • e.g. en_US, zh_CN
• C_Desktop.qtStyleList: () -> [string], return available Qt styles.
  • e.g. {"breeze", "fusion", "windows"}
• C_Desktop.systemAppMode: () -> string, return system app mode.
  • light: light mode
  • dark: dark mode
• C_Desktop.systemStyle: () -> string, return default Qt style.
  • e.g. fusion

C_FileSystem

• C_FileSystem.exists: (path: string) -> boolean, return whether the path exists.
• C_FileSystem.isExecutable: (path: string) -> boolean, return whether the path is executable.

C_System

• C_System.appArch: () -> string, return the architecture of Red Panda C++, name following QSysInfo.
  • e.g. i386, x86_64, arm, arm64, riscv64, loongarch64
  • Though unsupprted, MSVC arm64ec is handled correctly (returns arm64ec)
• C_System.appDir: () -> string, return the directory of Red Panda C++.
  • e.g. /usr/bin, C:/Program Files/RedPanda-Cpp
• C_System.appLibexecDir: () -> string, return the libexec directory of Red Panda C++.
  • e.g. /usr/libexec/RedPandaCPP, C:/Program Files/RedPanda-Cpp
• C_System.appResourceDir: () -> string, return the resource directory of Red Panda C++.
  • e.g. /usr/share/RedPandaCPP, C:/Program Files/RedPanda-Cpp
• C_System.osArch: () -> string, return the architecture of the OS, name following QSysInfo.
  • e.g. i386, x86_64, arm, arm64
  • Windows arm64 is handled correctly even if Red Panda C++ runs under emulation
• C_System.supportedAppArchList: () -> [string], return supported application architectures by OS, name following QSysInfo.
  • e.g. {"i386", "x86_64", "arm64"}
  • Windows 10 1709 or later: accurate result
  • Legacy Windows: hardcoded
    • {"i386", "x86_64"} for x86_64 even though WoW64 is not available
  • macOS: accurate result supposed, but not tested
  • Linux: osArch + appArch + QEMU user mode emulation
    • No multilib detection. It’s packager’s responsibility to detect multilib support in compiler_hint.lua
  • other (BSD): osArch + appArch (no multilib)

Windows specific:

• C_System.readRegistry: (subKey: string, name: string) -> string | nil, read subKey\name from HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE in order.
  • name can be empty string for default value

C_Util

• C_Util.format: (format: string, ...) -> string, Qt-style string format, replace %1, %2, etc. with arguments.