Yocto: How to add NGINX module?

Yocto Project is a great project — you can use it to create your own Linux distribution. Yes! You can be a little bit like Ubuntu. :-)

Nginx is a web server which can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache.

A great feature of NGINX is that its functionality can be extended using third-party modules. Every NGINX module may be a separate project with its own git repository that contains some files. But NGINX module is not a stand-alone executable. Instead a module is compiled into NGINX using --add-module flag used at the ./configure step.

For example (see file meta-webserver/recipes-httpd/nginx/nginx.inc):

./configure \
    --crossbuild=Linux:${TUNE_ARCH} \
    --with-int=4 \
    ...
    --add-module=/path/to/my-module

But here the problem begins! Where to place the git repository of the NGINX module (/path/to/my-module)? NGINX package expects to find all its dependecy in recipe-sysroot directory before the NGINX compilation begins. That is the configuration step should look like below:

./configure \
    ...
    --add-module=${STAGING_DIR_TARGET}/my-module

Well, it means that my-module that is a separate git repository has somehow to be copied to STAGING_DIR_TARGET. But the only directories that are being copied to NGINX’s recipe-sysroot (during the creation of recipe-sysroot of NGINX) are SYSROOT_DIRS of all the build-time prerequite (see DEPENDS) packages. The SYSROOT_DIRS is defined as:

SYSROOT_DIRS="/usr/include /usr/lib /lib /usr/share"

That is, the only directories that are copied to NGINX’s recipe-sysroot from our NGINX module are empty, because the only directoty that has any meaning for NGINX module is the my-module directory that contains all the module source code files.

So, what’s the trick? How to do this?

After some grepping here and there, the trick is this…

First, to let bitbake copy all my-module source code files to /image directory we need to define do_install recipe function as below:

do_install () {
    cd ${S}
    git checkout-index -a --prefix=${D}/${PN}/
    cd -
}

Next, to package my-module directory we need to define FILES_ as below:

FILES_${PN} = "${PN}/*"

Third, we need to extend SYSROOT_DIRS or NGINX module to include the my-module directory:

SYSROOT_DIRS += "/${PN}"

Or, put together, the trick looks like:

Now, we can easily add any NGINX module to Yocto build in a Yocto-natural way!

—Kosta Z