Getting Started & Macros
Relevant source files
The following files were used as context for generating this wiki page:
HXLibs is a modern C++20 web framework and library collection. The system provides a set of pre-defined macros to simplify the definition of web endpoints and controllers, enforcing a structured approach to building networked applications. It relies on standard C++20 features and external dependencies like OpenSSL and SQLite3.
Sources: vcpkg.json:1-9, documents/CodingStandards/CppStyle.md:3-4
Environment Setup
The project uses CMake for build configuration and vcpkg for dependency management.
Dependencies
The following core dependencies are required for building HXLibs:
| Dependency | Purpose |
|---|---|
| openssl | Provides SSL/TLS support for secure networking. |
| sqlite3 | Provides local database storage capabilities. |
Sources: vcpkg.json:5-8
Build Configuration
The framework supports Release and Debug build types. In Debug mode, a specific macro __HX_UN_DEBUG__ is set to "ON" to control internal behaviors such as memory leak detection.
if (NOT CMAKE_BUILD_TYPE)
set(CMAKE_BUILD_TYPE Release)
else()
set(__HX_UN_DEBUG__ "ON")
endif()
Sources: CMakeLists.txt:23-31
Coding Standards & Naming Conventions
The project adheres to strict naming and inclusion rules to ensure cross-platform compatibility and code clarity.
- File Naming: Uses CamelCase.
.hppfiles contain templates, while.hfiles do not. - Namespaces: Follow the folder structure (e.g.,
HX::coroutinefor files in/HXLibs/coroutine/). - Macro Naming:
- Public macros:
HX_{NAME}. - Private/Internal macros:
_hx_MACRO_{NAME}__or_hx_{NAME}__.
- Public macros:
- Indentation: Always 4 spaces (no tabs).
- Header Guards: Uses
#pragma once.
Sources: documents/CodingStandards/CppStyle.md:6-14, documents/CodingStandards/CppStyle.md:33-47, documents/CodingStandards/CppStyle.md:62-62
Network Macros
The framework provides specific macros within the HX::net module to reduce boilerplate when defining HTTP servers and controllers.
Core Endpoint Macro
The ENDPOINT macro standardizes the signature for request handlers. It automatically provides access to req (HttpRequest) and res (HttpResponse) objects and ensures the function returns a coroutine::Task<>.
#define ENDPOINT ( \
[[maybe_unused]] HX::net::HttpRequest<HX::net::HttpIO>& req, \
[[maybe_unused]] HX::net::HttpResponse<HX::net::HttpIO>& res \
) -> HX::coroutine::Task<>
Sources: include/HXLibs/net/ApiMacro.hpp:28-32
Controller Definitions
Controllers are defined using a suite of macros that manage class inheritance and dependency injection.
| Macro | Description |
|---|---|
HX_CONTROLLER(Name) | Declares a controller class named Name inheriting from BaseController. |
HX_ENDPOINT_MAIN(...) | Sets up the main entry point for a controller and defines dependency injection parameters. |
HX_ENDPOINT_TEMPLATE_HEAD | Header for defining controller endpoints that use function templates. |
Sources: include/HXLibs/net/ApiMacro.hpp:37-61
Application Lifecycle
A typical HXLibs application involves initializing the server, adding endpoints with optional middleware (Aspect-Oriented Programming), and running the event loop.
Initialization Flow
The following diagram illustrates the startup sequence of a standard HTTP server using HXLibs:
The server is instantiated by providing a port. Endpoints are added using template parameters for HTTP methods (e.g., GET, POST).
Sources: examples/Server/01_http_server.cpp:52-54, examples/Server/01_http_server.cpp:89-89
Aspect-Oriented Programming (AOP)
HXLibs allows injecting logic "before" and "after" an endpoint execution by passing a struct/class to addEndpoint. This is used for tasks like timing requests or logging.
struct TimeLog {
auto before(Request&, Response&) {
t = std::chrono::steady_clock::now();
return ServerStatus::Ok;
}
auto after(Request& req, Response&) {
// Log duration logic
return true;
}
};
Sources: examples/Server/01_http_server.cpp:18-34
Macro Cleanup
To prevent macro pollution in large projects, the framework provides UnApiMacro.hpp. This file contains #undef directives for all primary networking macros, allowing developers to clean the global namespace when HXLibs macros are no longer needed in a translation unit.
Sources: include/HXLibs/net/UnApiMacro.hpp:24-29
Summary
Getting started with HXLibs requires a C++20 environment and CMake. By utilizing the provided macros in include/HXLibs/net/ApiMacro.hpp, developers can create asynchronous, coroutine-based web servers with minimal boilerplate while maintaining strict coding standards. The system's use of AOP and standardized naming facilitates the creation of maintainable and performant networked services.