Skip to content

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.

The steps of the build of ngx_mruby, in the order in which ./configure and make run them.Drawn from these lines of ngx_mruby at c35606b0e (2026-10-19):
  • configure.in lines 53 to 62 and 190 to 194
  • Makefile.in lines 27 to 28, 87 and 98 to 119
  • config.in lines 48 to 81
  • build_config.rb lines 81 to 153
  • build.sh lines 103 and 107
  • ./configure writes config and Makefile from config.in and Makefile.in. --enable-dynamic-module makes the Makefile pass ngx_mruby to nginx’s configure with --add-dynamic-module instead of --add-module. It always passes dependence/ngx_devel_kit with --add-module; mruby_set uses its set_var part.
  • make first builds mruby: in mruby/, rake reads build_config.rb, which names the core gems and the third-party mrbgems, and build_config.rb.lock, which pins the commit of each third-party mrbgem. The result is the library libmruby.a with the gems in it, and libmruby.flags.mak with the compiler and linker flags that the gems need, from which make writes mrbgems_config (mrbgems_config_dynamic for a dynamic build).
  • make then runs nginx’s configure and make in the nginx source tree. config reads mrbgems_config and links libmruby.a into nginx, or into the module file of a dynamic build. The module holds ngx_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.sh runs ./configure with the nginx source that it downloads, and then make.
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
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

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): JSON
  • mattn/mruby-onig-regexp (repository): OnigRegexp
  • matsumotory/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 server
  • matsumotory/mruby-userdata (repository): Userdata
  • matsumotory/mruby-uname (repository): Uname
  • matsumotory/mruby-mutex (repository): Mutex
  • mrbgems/ngx_mruby_mrblib (source): the Ruby part of the classes of ngx_mruby
  • mrbgems/rack-based-api (source): the Rack compatible API (run)
  • mrbgems/digest (source): Digest, the hashes MD5, RMD160, SHA1, SHA256, SHA384 and SHA512 and Digest::HMAC, on the EVP and EVP_MAC APIs 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 from RAND_bytes of 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.

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).

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.lock records its version as 4.1.0).
  • nginx_version names the version that build.sh and test.sh download, 1.31.8.