Use prebuilt nginx tree if $NGX_OBJS is specified

Cargo.toml

@@ -21,6 +21,12 @@ keywords = ["nginx", "module", "sys"]
 [dependencies]
 nginx-sys = { path = "nginx-sys", version = "0.5.0"}
 
+[features]
+# Build our own copy of the NGINX by default.
+# This could be disabled with `--no-default-features` to minimize the dependency tree
+# when building against an existing copy of the NGINX with the NGX_OBJS variable.
+default = ["nginx-sys/vendored"]
+
 [badges]
 maintenance = { status = "experimental" }
 

README.md

@@ -75,6 +75,21 @@ Example modules are available in [examples](examples) folder. You can use `cargo
 For example (all examples plus linux specific):
 `cargo build --package=examples --examples --features=linux`
 
+### Build with external NGINX source tree
+
+If you require a customized NGINX configuration, you can build a module against an existing pre-configured source tree.
+To do that, you need to set the `NGX_OBJS` variable to an _absolute_ path of the NGINX build directory (`--builddir`, defaults to the `objs` in the source directory).
+Only the `./configure` step of the NGINX build is mandatory because bindings don't depend on any of the artifacts generated by `make`.
+
+
+```
+NGX_OBJS=$PWD/../nginx/objs cargo build --package=examples --examples
+
+```
+
+Furthermore, this approach can be leveraged to build a module as a part of the NGINX build process by adding the `--add-module`/`--add-dynamic-module` options to the configure script.
+See the following example integration scripts: [`examples/config`](examples/config) and [`examples/config.make`](examples/config.make).
+
 ### Docker
 
 We provide a multistage [Dockerfile](Dockerfile):

examples/Cargo.toml

@@ -42,4 +42,11 @@ crate-type = ["cdylib"]
 tokio = { version = "1.33.0", features = ["full"] }
 
 [features]
+default = ["export-modules"]
+# Generate `ngx_modules` table with module exports
+# The exports table is required for building loadable modules with --crate-type cdylib
+# outside of the NGINX buildsystem. However, cargo currently does not detect
+# this configuration automatically.
+# See https://github.com/rust-lang/rust/issues/20267
+export-modules = []
 linux = []

examples/async.rs

@@ -6,7 +6,7 @@ use ngx::ffi::{
 };
 use ngx::http::MergeConfigError;
 use ngx::{core, core::Status, http, http::HTTPModule};
-use ngx::{http_request_handler, ngx_log_debug_http, ngx_modules, ngx_null_command, ngx_string};
+use ngx::{http_request_handler, ngx_log_debug_http, ngx_null_command, ngx_string};
 use std::os::raw::{c_char, c_void};
 use std::ptr::{addr_of, addr_of_mut};
 use std::sync::atomic::AtomicBool;
@@ -78,9 +78,13 @@ static ngx_http_async_module_ctx: ngx_http_module_t = ngx_http_module_t {
     merge_loc_conf: Some(Module::merge_loc_conf),
 };
 
-ngx_modules!(ngx_http_async_module);
+// Generate the `ngx_modules` table with exported modules.
+// This feature is required to build a 'cdylib' dynamic module outside of the NGINX buildsystem.
+#[cfg(feature = "export-modules")]
+ngx::ngx_modules!(ngx_http_async_module);
 
 #[no_mangle]
+#[used]
 pub static mut ngx_http_async_module: ngx_module_t = ngx_module_t {
     ctx_index: ngx_uint_t::max_value(),
     index: ngx_uint_t::max_value(),

examples/awssig.rs

@@ -6,7 +6,7 @@ use ngx::ffi::{
     NGX_RS_HTTP_LOC_CONF_OFFSET, NGX_RS_MODULE_SIGNATURE,
 };
 use ngx::{core, core::Status, http::*};
-use ngx::{http_request_handler, ngx_log_debug_http, ngx_modules, ngx_null_command, ngx_string};
+use ngx::{http_request_handler, ngx_log_debug_http, ngx_null_command, ngx_string};
 use std::os::raw::{c_char, c_void};
 use std::ptr::addr_of;
 
@@ -97,9 +97,13 @@ static ngx_http_awssigv4_module_ctx: ngx_http_module_t = ngx_http_module_t {
     merge_loc_conf: Some(Module::merge_loc_conf),
 };
 
-ngx_modules!(ngx_http_awssigv4_module);
+// Generate the `ngx_modules` table with exported modules.
+// This feature is required to build a 'cdylib' dynamic module outside of the NGINX buildsystem.
+#[cfg(feature = "export-modules")]
+ngx::ngx_modules!(ngx_http_awssigv4_module);
 
 #[no_mangle]
+#[used]
 pub static mut ngx_http_awssigv4_module: ngx_module_t = ngx_module_t {
     ctx_index: ngx_uint_t::max_value(),
     index: ngx_uint_t::max_value(),

examples/config

@@ -0,0 +1,94 @@
+ngx_addon_name=ngx_rust_examples
+ngx_cargo_profile=ngx-module
+
+if [ $HTTP = YES ]; then
+    ngx_module_type=HTTP
+
+    if :; then
+        ngx_module_name=ngx_http_async_module
+        ngx_module_lib=async
+
+        ngx_module_lib=$NGX_OBJS/$ngx_addon_name/$ngx_cargo_profile/examples/lib$ngx_module_lib.a
+        ngx_module_deps=$ngx_module_lib
+        ngx_module_libs="$ngx_module_lib -lm"
+
+        # Module deps are usually added to the object file targets, but we don't have any
+        LINK_DEPS="$LINK_DEPS $ngx_module_lib"
+
+        . auto/module
+    fi
+
+    if :; then
+        ngx_module_name=ngx_http_awssigv4_module
+        ngx_module_lib=awssig
+
+        ngx_module_lib=$NGX_OBJS/$ngx_addon_name/$ngx_cargo_profile/examples/lib$ngx_module_lib.a
+        ngx_module_deps=$ngx_module_lib
+        ngx_module_libs=$ngx_module_lib
+
+        # Module deps are usually added to the object file targets, but we don't have any
+        LINK_DEPS="$LINK_DEPS $ngx_module_lib"
+
+        . auto/module
+    fi
+
+    if :; then
+        ngx_module_name=ngx_http_curl_module
+        ngx_module_lib=curl
+
+        ngx_module_lib=$NGX_OBJS/$ngx_addon_name/$ngx_cargo_profile/examples/lib$ngx_module_lib.a
+        ngx_module_deps=$ngx_module_lib
+        ngx_module_libs=$ngx_module_lib
+
+        # Module deps are usually added to the object file targets, but we don't have any
+        LINK_DEPS="$LINK_DEPS $ngx_module_lib"
+
+        . auto/module
+    fi
+
+    case "$NGX_PLATFORM" in
+        Linux:*)
+            ngx_module_name=ngx_http_orig_dst_module
+            ngx_module_lib=httporigdst
+
+            ngx_module_lib=$NGX_OBJS/$ngx_addon_name/$ngx_cargo_profile/examples/lib$ngx_module_lib.a
+            ngx_module_deps=$ngx_module_lib
+            ngx_module_libs=$ngx_module_lib
+
+            # Module deps are usually added to the object file targets, but we don't have any
+            LINK_DEPS="$LINK_DEPS $ngx_module_lib"
+
+            . auto/module
+            ;;
+    esac
+
+    if :; then
+        ngx_module_name=ngx_http_upstream_custom_module
+        ngx_module_lib=upstream
+
+        ngx_module_lib=$NGX_OBJS/$ngx_addon_name/$ngx_cargo_profile/examples/lib$ngx_module_lib.a
+        ngx_module_deps=$ngx_module_lib
+        ngx_module_libs=$ngx_module_lib
+
+        # Module deps are usually added to the object file targets, but we don't have any
+        LINK_DEPS="$LINK_DEPS $ngx_module_lib"
+
+        . auto/module
+    fi
+fi
+
+# Write a cargo config with the $ngx_cargo_profile definition (optional)
+
+if [ "$NGX_DEBUG" = YES ]; then
+    NGX_CARGO_PROFILE_BASE=dev
+else
+    NGX_CARGO_PROFILE_BASE=release
+fi
+
+mkdir -p "$NGX_OBJS/.cargo"
+cat > "$NGX_OBJS/.cargo/config.toml" << END
+
+[profile.$ngx_cargo_profile]
+inherits = "$NGX_CARGO_PROFILE_BASE"
+
+END

examples/config.make

@@ -0,0 +1,35 @@
+ngx_addon_name=ngx_rust_examples
+ngx_cargo_profile=ngx-module
+ngx_cargo_manifest=$(realpath $ngx_addon_dir/Cargo.toml)
+ngx_cargo_features=
+ngx_rust_examples="async awssig curl upstream"
+
+case "$NGX_PLATFORM" in
+    Linux:*)
+		ngx_cargo_features="$ngx_cargo_features linux"
+		ngx_rust_examples="$ngx_rust_examples httporigdst"
+        ;;
+esac
+
+for ngx_rust_example in $ngx_rust_examples
+do
+
+cat << END                                            >> $NGX_MAKEFILE
+
+# Always call cargo instead of tracking the source modifications
+.PHONY: $NGX_OBJS/$ngx_addon_name/$ngx_cargo_profile/examples/lib$ngx_rust_example.a
+
+$NGX_OBJS/$ngx_addon_name/$ngx_cargo_profile/examples/lib$ngx_rust_example.a:
+	cd $NGX_OBJS && \\
+	NGX_OBJS="\$\$PWD" cargo rustc \\
+		--crate-type staticlib \\
+		--example "$ngx_rust_example" \\
+		--no-default-features \\
+		--features "$ngx_cargo_features" \\
+		--profile $ngx_cargo_profile \\
+		--target-dir $ngx_addon_name \\
+		--manifest-path $ngx_cargo_manifest
+
+END
+
+done

examples/curl.rs

@@ -6,7 +6,7 @@ use ngx::ffi::{
 };
 use ngx::http::MergeConfigError;
 use ngx::{core, core::Status, http, http::HTTPModule};
-use ngx::{http_request_handler, ngx_log_debug_http, ngx_modules, ngx_null_command, ngx_string};
+use ngx::{http_request_handler, ngx_log_debug_http, ngx_null_command, ngx_string};
 use std::os::raw::{c_char, c_void};
 use std::ptr::addr_of;
 
@@ -61,9 +61,13 @@ static ngx_http_curl_module_ctx: ngx_http_module_t = ngx_http_module_t {
     merge_loc_conf: Some(Module::merge_loc_conf),
 };
 
-ngx_modules!(ngx_http_curl_module);
+// Generate the `ngx_modules` table with exported modules.
+// This feature is required to build a 'cdylib' dynamic module outside of the NGINX buildsystem.
+#[cfg(feature = "export-modules")]
+ngx::ngx_modules!(ngx_http_curl_module);
 
 #[no_mangle]
+#[used]
 pub static mut ngx_http_curl_module: ngx_module_t = ngx_module_t {
     ctx_index: ngx_uint_t::max_value(),
     index: ngx_uint_t::max_value(),

examples/httporigdst.rs

@@ -5,7 +5,7 @@ use ngx::ffi::{
     NGX_RS_MODULE_SIGNATURE,
 };
 use ngx::{core, core::Status, http, http::HTTPModule};
-use ngx::{http_variable_get, ngx_http_null_variable, ngx_log_debug_http, ngx_modules, ngx_null_string, ngx_string};
+use ngx::{http_variable_get, ngx_http_null_variable, ngx_log_debug_http, ngx_null_string, ngx_string};
 use std::os::raw::{c_char, c_int, c_void};
 
 const IPV4_STRLEN: usize = INET_ADDRSTRLEN as usize;
@@ -86,9 +86,13 @@ static ngx_http_orig_dst_module_ctx: ngx_http_module_t = ngx_http_module_t {
     merge_loc_conf: Some(Module::merge_loc_conf),
 };
 
-ngx_modules!(ngx_http_orig_dst_module);
+// Generate the `ngx_modules` table with exported modules.
+// This feature is required to build a 'cdylib' dynamic module outside of the NGINX buildsystem.
+#[cfg(feature = "export-modules")]
+ngx::ngx_modules!(ngx_http_orig_dst_module);
 
 #[no_mangle]
+#[used]
 pub static mut ngx_http_orig_dst_module: ngx_module_t = ngx_module_t {
     ctx_index: ngx_uint_t::max_value(),
     index: ngx_uint_t::max_value(),

examples/upstream.rs

@@ -22,7 +22,7 @@ use ngx::{
     },
     http_upstream_init_peer_pt,
     log::DebugMask,
-    ngx_log_debug_http, ngx_log_debug_mask, ngx_modules, ngx_null_command, ngx_string,
+    ngx_log_debug_http, ngx_log_debug_mask, ngx_null_command, ngx_string,
 };
 use std::{
     mem,
@@ -105,9 +105,13 @@ static mut ngx_http_upstream_custom_commands: [ngx_command_t; 2] = [
     ngx_null_command!(),
 ];
 
-ngx_modules!(ngx_http_upstream_custom_module);
+// Generate the `ngx_modules` table with exported modules.
+// This feature is required to build a 'cdylib' dynamic module outside of the NGINX buildsystem.
+#[cfg(feature = "export-modules")]
+ngx::ngx_modules!(ngx_http_upstream_custom_module);
 
 #[no_mangle]
+#[used]
 pub static mut ngx_http_upstream_custom_module: ngx_module_t = ngx_module_t {
     ctx_index: ngx_uint_t::max_value(),
     index: ngx_uint_t::max_value(),

nginx-sys/Cargo.toml

@@ -8,6 +8,7 @@ repository = "https://github.com/nginxinc/ngx-rust"
 homepage = "https://github.com/nginxinc/ngx-rust"
 license = "Apache-2.0"
 keywords = ["nginx", "ffi", "sys"]
+build = "build/main.rs"
 
 [lib]
 crate-type = ["staticlib", "rlib"]
@@ -16,8 +17,11 @@ crate-type = ["staticlib", "rlib"]
 
 [build-dependencies]
 bindgen = "0.69.4"
-which = "6.0.0"
-duct = "0.13.7"
-ureq = { version = "2.9.6", features = ["tls"] }
-flate2 = "1.0.28"
-tar = "0.4.40"
+duct = { version = "0.13.7", optional = true }
+flate2 = { version = "1.0.28", optional = true }
+tar =  { version = "0.4.40", optional = true }
+ureq = { version = "2.9.6", features = ["tls"], optional = true }
+which = { version = "6.0.0", optional = true }
+
+[features]
+vendored = ["dep:which", "dep:duct", "dep:ureq", "dep:flate2", "dep:tar"]