Mongoose
Build options
Mongoose build options control which networking features are compiled into your firmware. The library is delivered as a small two-file C library (mongoose.c and mongoose.h), and its behaviour is configured at compile time using a configuration file called mongoose_config.h.
By defining simple macros in that file, you can enable or disable components such as the embedded TCP/IP stack, TLS security, or hardware drivers. This makes it easy to tailor Mongoose for a specific device, whether you are building a minimal HTTP server on a microcontroller or a full-featured connected device with secure cloud connectivity.
In this section you will learn how to configure Mongoose build options, how mongoose_config.h works, and how to select the right configuration for platforms like STM32, ESP32, RP2040, NXP, or embedded Linux systems.
The simple project strucuture may look like this:
src/
Makefile
main.c <-- your application code
mongoose.h <-- public Mongoose API
mongoose.c <-- Mongoose implementation
mongoose_config.h <-- build options
The mongoose_config.h file is mandatory if you're building
for embedded system, cause it is included automatically by mongoose.h.
On Mac, Windows, or Linux, the environment is auto-detected and
mongoose_config.h is not included and therefore is ignored. Use -D MG_ARCH=MG_ARCH_CUSTOM
compiler flag to make it mandatory, or specify build options via
compiler flags like -D OPTION_NAME=OPTION_VALUE.
Note - defining build options in
mongoose_config.his the recommended approach. This file serves as the single place where all Mongoose configuration macros are documented and maintained. Keeping options inmongoose_config.hmakes the configuration explicit, easy to review, and independent from a specific build system, instead of hiding compile-time flags inside Makefiles or IDE settings.
Most commonly changed options
These are the options most projects change first.
| Option | What it does |
|---|---|
| MG_ARCH | Selects the target architecture or RTOS |
| MG_IO_SIZE | Sets network I/O buffer size |
| MG_TLS | Enables or disables TLS support |
Example mongoose_config.h on the STM32 firmware that uses Cube framework:
#define MG_ARCH MG_ARCH_CUBE // Build environment is Cube
#define MG_IO_SIZE 1024 // IO buffer growth granularity is 1Kb
#define MG_TLS MG_TLS_BUILTIN // Use built-in TLS 1.3 stack
#define MG_ENABLE_TCPIP 1 // Use built-in TCP/IP stack
#define MG_ENABLE_DRIVER_STM32H5 1 // With STM32H5 ethernet driver
#define MG_OTA MG_OTA_STM32H5 // Use built-in OTA for STM32H5
Full list of options
| Name | Default | Description |
|---|---|---|
| MG_ARCH | Autodetected | See arch.h |
| MG_TLS | MG_TLS_NONE | TLS implementation to use. Valid options: MG_TLS_NONE MG_TLS_BUILTIN MG_TLS_MBED MG_TLS_OPENSSL MG_TLS_WOLFSSL |
| MG_ENABLE_IPV6 | 0 | Enable IPv6 |
| MG_ENABLE_MD5 | 1 | Enable MD5 implementation |
| MG_ENABLE_SSI | 1 | Enable serving SSI files by `mg_http_serve_dir() |
| MG_ENABLE_CUSTOM_CALLOC | 0 | Provide custom mg_calloc() and mg_free() |
| MG_ENABLE_CUSTOM_RANDOM | 0 | Provide custom RNG function mg_random() |
| MG_ENABLE_CUSTOM_MILLIS | 0 | Enable custom mg_millis() function |
| MG_ENABLE_POSIX_FS | Autodetected | Enable POSIX fopen/fread/.. functions. Valid options: 0 or 1 |
| MG_ENABLE_PACKED_FS | 0 | Enable embedded FS support |
| MG_ENABLE_FATFS | 0 | Enable embedded FAT FS support |
| MG_ENABLE_LINES | undefined | If defined, show source file names in logs |
| MG_IO_SIZE | 2048 | Granularity of the send/recv IO buffer growth. Set to 256 on the smallest system with tiny RAM, and 32768 on the big systems like OSes - Linux, Mac, Windows. NOTE: the MG_IO_SIZE constant also sets the maximum UDP message size. |
| MG_MAX_RECV_SIZE | 3145728 | Maximum recv buffer size. If a connection's receive buffer grows more, the connection gets closed automatically |
| MG_MAX_HTTP_HEADERS | 40 | Maximum number of HTTP headers |
| MG_HTTP_INDEX | "index.html" | Index file for HTML directory |
| MG_FATFS_ROOT | "/" | FAT FS root directory |
| MG_ENABLE_SOCKET | 1 | Use BSD socket low-level API |
| MG_ENABLE_LWIP | 0 | lwIP network stack |
| MG_ENABLE_FREERTOS_TCP | 0 | Amazon FreeRTOS-Plus-TCP network stack |
| MG_ENABLE_RL | 0 | Keil MDK network stack |
| MG_ENABLE_TCPIP | 0 | Built-in Mongoose TCP/IP stack |
| MG_ENABLE_TCPIP_PRINT_DEBUG_STATS | 0 | Print built-in Mongoose TCP/IP stack stats every second |
| MG_ENABLE_DRIVER_* | undefined | Enable specific Mongoose TCP/IP stack driver. Available options: MG_ENABLE_DRIVER_STM32F MG_ENABLE_DRIVER_STM32H MG_ENABLE_DRIVER_STM32N MG_ENABLE_DRIVER_IMXRT10 MG_ENABLE_DRIVER_IMXRT11 MG_ENABLE_DRIVER_MCXE MG_ENABLE_DRIVER_MCXN MG_ENABLE_DRIVER_RW612 MG_ENABLE_DRIVER_CMSIS MG_ENABLE_DRIVER_RA6 MG_ENABLE_DRIVER_RA8 MG_ENABLE_DRIVER_SAME54 MG_ENABLE_DRIVER_TM4C MG_ENABLE_DRIVER_TMS570 MG_ENABLE_DRIVER_XMC7 MG_ENABLE_DRIVER_XMC MG_ENABLE_DRIVER_W5100 MG_ENABLE_DRIVER_W5500 MG_ENABLE_DRIVER_PICO_W MG_ENABLE_DRIVER_CYW MG_ENABLE_DRIVER_CYW_SDIO MG_ENABLE_DRIVER_NXP_WIFI MG_ENABLE_DRIVER_PPP |
| MG_TCPIP_PHY_ADDR | 0 | PHY address (for built-in stack only) |
| MG_DRIVER_MDC_CR | 4 | MDC CR divider for Ethernet MAC (for built-in stack only) |
| MG_SET_MAC_ADDRESS(mac) | Set MAC address (for built-in stack only) |
NOTE: most build constants are defined in src/config.h
Unknown architecture
If your architecture is not listed in the arch.h, then set your architecture as MG_ARCH_CUSTOM and specify all necessary includes for your build environment. For custom architecture, Mongoose does not include any headers by default, so your mongoose_config.h should include all necessary system headers as well as setting build options:
#include <stdint.h>
#include <stdbool.h>
#include <stdarg.h>
// ... other includes ...
#define MG_ARCH MG_ARCH_CUSTOM
// ... other options ...