Where to Find Hyprland's Configuration Parsing Logic: A Complete Guide to the Config System

Hyprland parses its configuration files through a Lua-based interpreter system implemented across src/config/ConfigManager.cpp, src/config/lua/CConfigManager.cpp, and src/config/ConfigValue.cpp.

Navigating the Hyprland codebase to understand how user settings are loaded requires tracing the configuration parsing logic through several architectural layers. Unlike traditional window managers that use static config files, Hyprland bootstraps a Lua interpreter to evaluate configuration directives as executable scripts. This article maps the precise file locations and function call chains within the hyprwm/Hyprland repository that handle config discovery, parsing, and value conversion.

Entry Point and Config File Discovery

The configuration parsing logic begins in src/config/ConfigManager.cpp with the Config::initConfigManager() function. This entry point determines which configuration file to load and instantiates the appropriate manager implementation.

When Hyprland starts, this function resolves the config file path through supplementary utilities, checks for file existence, and generates a default configuration if none is found. It then creates a unique pointer to the Lua-based config manager to handle the actual parsing.

// src/config/ConfigManager.cpp – entry point
bool Config::initConfigManager() {
    const auto CFG_PATH = Supplementary::Jeremy::getMainConfigPath();
    std::filesystem::path filePath = CFG_PATH->path;

    // Create the Lua‑based config manager
    g_mgr = makeUnique<Lua::CConfigManager>();
    // …generate default config if needed…
}

Lua-Based Parsing Implementation

The actual script evaluation occurs in src/config/lua/CConfigManager.cpp within the CConfigManager::init() method. This class implements the configuration parsing logic by initializing a Lua state, registering Hyprland-specific functions, and executing the user's config file as a Lua script.

The Lua::CConfigManager creates a new interpreter instance with luaL_newstate(), opens standard libraries, and registers configuration directives such as monitor, workspace, and bind as Lua functions. It then calls luaL_dofile() to evaluate the script, capturing any runtime errors for logging.

// src/config/lua/CConfigManager.cpp – parsing implementation
void CConfigManager::init() {
    // create a new Lua state
    lua_State* L = luaL_newstate();
    luaL_openlibs(L);

    // register Hyprland‑specific functions (e.g., monitor, workspace)
    registerHyprlandFunctions(L);

    // finally load the user’s config file
    if (luaL_dofile(L, configPath.c_str()) != LUA_OK) {
        const char* err = lua_tostring(L, -1);
        Log::logger->log(Log::CRIT, "[cfg] Lua error: {}", err);
    }
}

Value Conversion and Internal Structures

Once Lua executes the configuration script, src/config/ConfigValue.cpp handles the conversion of parsed values into C++ structures. This module defines how Lua values map to internal Hyprland types such as int, float, Vector2D, and custom option objects.

The Config::IConfigManager::getConfigValue() method retrieves stored configuration values by name, returning type information and pointers that the rest of the compositor uses to query settings. This separation of concerns keeps the configuration parsing logic distinct from the value storage and retrieval mechanisms.

// src/config/ConfigValue.cpp – converting Lua values
SConfigOptionReply Config::IConfigManager::getConfigValue(const std::string& name) {
    // Look up the stored value, return a pointer and type information
    // (used by the rest of the compositor to query config options)
}

Step-by-Step Configuration Flow

Understanding the complete configuration parsing logic requires following the execution sequence across these three components:

1. Config::initConfigManager() in src/config/ConfigManager.cpp — Discovers the config file path and instantiates the Lua manager.
2. Lua::CConfigManager::init() in src/config/lua/CConfigManager.cpp — Sets up the Lua environment, registers config functions, and executes the script via luaL_dofile.
3. Value handling in src/config/ConfigValue.cpp — Converts Lua values into Hyprland's internal Config::Values hierarchy for runtime access.

Summary

• Configuration discovery happens in src/config/ConfigManager.cpp, where Config::initConfigManager() determines the file path and creates the manager.
• Script execution is handled by Lua::CConfigManager in src/config/lua/CConfigManager.cpp, which runs the Lua interpreter and evaluates user configs.
• Type conversion is managed by src/config/ConfigValue.cpp, mapping Lua values to C++ structures like Vector2D and int.
• The system uses luaL_dofile() to evaluate configuration files, with error handling that logs critical failures during startup.

Frequently Asked Questions

Where is the main configuration file path determined in Hyprland?

The path resolution occurs in src/config/ConfigManager.cpp within the Config::initConfigManager() function. It calls Supplementary::Jeremy::getMainConfigPath() to determine the location, then checks if the file exists before initializing the Lua parser.

How does Hyprland handle Lua errors during config parsing?

Errors are caught in src/config/lua/CConfigManager.cpp immediately after calling luaL_dofile(). If the function returns anything other than LUA_OK, the error message is retrieved from the Lua stack using lua_tostring() and logged at the critical level, allowing the compositor to report specific syntax or runtime errors to the user.

What types of values can be parsed from the Hyprland configuration?

According to the source code in src/config/ConfigValue.cpp, the system supports converting Lua values to standard C++ types including int, float, and custom structures like Vector2D. The getConfigValue() method returns a SConfigOptionReply containing the type information and pointer to the stored value.

Is the configuration parsing logic in Hyprland written entirely in Lua?

No, the configuration parsing logic is primarily implemented in C++. While the configuration files themselves are written in Lua and evaluated by the interpreter, the parser, value conversions, and function registrations are all native C++ code found in src/config/lua/CConfigManager.cpp and related files.

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