Build
This page describes how the build of ngx_mruby fits together, the options
of ./configure and build.sh, the mrbgems of the default build, and the
versions that CI builds and tests. Install has the
steps.
How the build fits together
Section titled “How the build fits together”./configure writes config and Makefile from config.in and Makefile.inmake runs mruby's rake with build_config.rb and its lock: libmruby.a with the mrbgemsmake writes mrbgems_config (mrbgems_config_dynamic) from the flags of that mruby buildconfigure with ngx_mruby by --add-module (--add-dynamic-module after --enable-dynamic-module) and ngx_devel_kit; config reads mrbgems_configmake: nginx with ngx_mruby built in, or a module file that nginx loadsngx_http_mruby_module, ngx_stream_mruby_module with nginx's stream module, and the upstream keepalive module of ngx_mruby./configure and make run them.Drawn from these lines of ngx_mruby at c35606b0e (2026-10-19):configure.inlines 53 to 62 and 190 to 194Makefile.inlines 27 to 28, 87 and 98 to 119config.inlines 48 to 81build_config.rblines 81 to 153build.shlines 103 and 107
./configurewritesconfigandMakefilefromconfig.inandMakefile.in.--enable-dynamic-modulemakes theMakefilepass ngx_mruby to nginx’sconfigurewith--add-dynamic-moduleinstead of--add-module. It always passesdependence/ngx_devel_kitwith--add-module;mruby_setuses itsset_varpart.makefirst builds mruby: inmruby/,rakereadsbuild_config.rb, which names the core gems and the third-party mrbgems, andbuild_config.rb.lock, which pins the commit of each third-party mrbgem. The result is the librarylibmruby.awith the gems in it, andlibmruby.flags.makwith the compiler and linker flags that the gems need, from whichmakewritesmrbgems_config(mrbgems_config_dynamicfor a dynamic build).makethen runs nginx’sconfigureandmakein the nginx source tree.configreadsmrbgems_configand linkslibmruby.ainto nginx, or into the module file of a dynamic build. The module holdsngx_http_mruby_module, the upstream keepalive module of ngx_mruby (mruby_upstream_keepalive) and, in a build with nginx’s stream module,ngx_stream_mruby_module.build.shruns./configurewith the nginx source that it downloads, and thenmake.
Options of configure
Section titled “Options of configure”| Option | What it sets | Default |
|---|---|---|
--with-ngx-src-root=DIR |
the nginx source tree | none: configure stops without it |
--with-ngx-config-opt=OPT |
the options that make passes to nginx’s configure |
none |
--enable-dynamic-module |
builds ngx_mruby as a dynamic module | a static module |
--with-build-dir=DIR |
the directory that make clobber removes; build.sh passes build or build_dynamic, where it puts the nginx source |
build |
--with-openssl-src=DIR |
OpenSSL sources that nginx builds with (--with-openssl of nginx) |
the system’s OpenSSL |
--with-openssl-opt=OPTIONS |
more options for the build of OpenSSL (--with-openssl-opt of nginx) |
none |
--with-mruby-root=DIR |
the mruby tree to build | mruby/ of this repository |
--with-mruby-incdir=DIR |
the include directories of mruby | src, include and build/host/include of the mruby tree |
--with-mruby-libdir=DIR |
the directory of libmruby.a |
build/host/lib of the mruby tree |
--with-ndk-root=DIR |
the ngx_devel_kit tree |
dependence/ngx_devel_kit |
Environment of the build
Section titled “Environment of the build”| Variable | Read by | What it does |
|---|---|---|
NGINX_CONFIG_OPT_ENV |
build.sh |
all the options of nginx’s configure, in place of the default set: the prefix build/nginx (build_dynamic/nginx for a dynamic build), --with-http_stub_status_module, --with-stream, --without-stream_access_module and --with-cc-opt=-fno-common |
NGINX_SRC_ENV |
build.sh |
an nginx source tree to use instead of the download of the version in nginx_version |
BUILD_DYNAMIC_MODULE |
build.sh |
any value builds a dynamic module in build_dynamic/ |
NUM_THREADS_ENV |
build.sh |
the number of jobs of make; by default half the processors |
OPENSSL_SRC_VERSION |
build.sh |
downloads that version of OpenSSL and builds nginx with it |
NGX_MRUBY_ALLOW_MISSING_CORE_GEMS=1 |
build_config.rb |
skips, with a notice, the names of NGX_MRUBY_CORE_GEMS that the mruby being built does not have |
NGX_MRUBY_CFLAGS, NGX_MRUBY_LDFLAGS, NGX_MRUBY_LIBS |
build_config.rb |
more compiler flags, linker flags and libraries for the mruby build |
Default mrbgems
Section titled “Default mrbgems”The default build_config.rb builds these mrbgems into libmruby.a,
besides the mruby core gems that NGX_MRUBY_CORE_GEMS lists
(Core gems). build_config.rb.lock pins
the commit of each third-party gem
(Gem commits).
mattn/mruby-json(repository):JSONmattn/mruby-onig-regexp(repository):OnigRegexpmatsumotory/mruby-redis(repository):Redis, a client that waits for each answer of the Redis server in the worker. Its build clones the hiredis library at the tag v1.5.0, checks its commit and links it statically, and clones matsumotory/mruby-pointer, which the gem depends on. A script that calls it needs a running Redis servermatsumotory/mruby-userdata(repository):Userdatamatsumotory/mruby-uname(repository):Unamematsumotory/mruby-mutex(repository):Mutexmrbgems/ngx_mruby_mrblib(source): the Ruby part of the classes of ngx_mrubymrbgems/rack-based-api(source): the Rack compatible API (run)mrbgems/digest(source):Digest, the hashes MD5, RMD160, SHA1, SHA256, SHA384 and SHA512 andDigest::HMAC, on the EVP andEVP_MACAPIs of OpenSSL 3. The classes and methods are those of iij/mruby-digest, which the default build of 2.x has (Digest)mrbgems/secure-random(source):SecureRandom, whose bytes come fromRAND_bytesof OpenSSL. The methods are those of monochromegane/mruby-secure-random, which the default build of 2.x has (SecureRandom)
ENV, Process and Signal come from the core gems mruby-env,
mruby-process and mruby-signal, not from iij/mruby-env and
iij/mruby-process as in 2.x. Digest and SecureRandom come from the two gems of this repository above, not from iij/mruby-digest and monochromegane/mruby-secure-random as in 2.x; both gems need OpenSSL 3.0 or later. matsumotory/mruby-vedis (Vedis) and
matsumotory/mruby-localmemcache (Cache), which the default build of 2.x
has, are comments in build_config.rb since 3.0.0
(the release notes).
The check site/scripts/check-reference.mjs compares this list with the
lines conf.gem of the host build in build_config.rb that are not
comments and have no condition. The lines that are comments name gems that the default build
leaves out, such as mruby-discount and mruby-memcached: to build with one,
uncomment its line and remove mruby/build.
Supported nginx versions
Section titled “Supported nginx versions”v3 supports nginx 1.30 (stable) and 1.31 (mainline), which CI builds and tests (the table below). The oldest supported versions move up every April, when nginx starts a new stable line. The build does not check the version of nginx: Install says what happens with an older nginx. With nginx 1.28 or 1.26, use 2.x. With nginx 1.24, 2.x builds only without the stream module (the same page has the measurement).
Versions that CI builds and tests
Section titled “Versions that CI builds and tests”The workflow .github/workflows/test.yml builds ngx_mruby and runs
test.sh in each of these combinations in its full matrix: the nightly
run, the push of a tag, a pull request with the label full-matrix and
“Run workflow” without the input base. A ready pull request that changes
the code or the tests runs four of them (Which jobs a run
starts).
| nginx | Module | OpenSSL | nginx runs |
|---|---|---|---|
| 1.31.8, 1.30.6 | static and dynamic | 3.5.9, installed, or built into nginx with --with-openssl-src |
directly or under valgrind |
| 1.31.8 | static | 3.5.9, installed | directly |
- The nightly run runs nginx under valgrind in every cell except the sanitizer cell. The other runs run it under valgrind only in the cell of 1.31.8 with the static module and the installed OpenSSL.
- The sanitizer cell builds ngx_mruby, mruby and nginx with AddressSanitizer and UndefinedBehaviorSanitizer.
- The runner is Ubuntu 22.04 with GCC 11 and Ruby 3.0. The bundled mruby is
4.1.0-rc2 (
build_config.rb.lockrecords its version as 4.1.0). nginx_versionnames the version thatbuild.shandtest.shdownload, 1.31.8.