You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://www.repostatus.org/#wip)
The `ngx` crate provides a high-level Rust interface for the [NGINX] C APIs,
11
+
allowing creation of NGINX dynamic modules completely in Rust.
12
+
13
+
[NGINX]: https://nginx.org/
6
14
7
15
## Project status
8
16
9
17
This project is in active development. It is stable enough to be used in our
10
18
own products, but the APIs are not stabilized and breaking changes are expected.
11
19
12
-
#Description
20
+
## Build
13
21
14
-
This project provides Rust SDK interfaces to the [NGINX](https://nginx.com) proxy allowing the creation of NGINX
15
-
dynamic modules completely in Rust.
22
+
NGINX modules can be built against a particular version of NGINX. The following
23
+
environment variables can be used to specify the NGINX build to use:
16
24
17
-
In short, this SDK allows writing NGINX modules using the Rust language.
25
+
-`NGINX_BUILD_DIR` - absolute path to the NGINX build directory.
26
+
Usually it's `objs` under the source directory, but can be changed with the
27
+
`--builddir=` argument of the configure script.
18
28
19
-
## Build
29
+
-`NGINX_SOURCE_DIR` - absolute path to the NGINX source directory, configured
30
+
with the [`configure`](https://nginx.org/en/docs/configure.html) command.
20
31
21
-
NGINX modules can be built against a particular version of NGINX. The following environment variables can be used to specify a particular version of NGINX or an NGINX dependency:
32
+
Only the `./configure` step of the NGINX build is mandatory because bindings
33
+
generator don't depend on any of the artifacts generated by `make`.
22
34
23
-
*`ZLIB_VERSION` (default 1.3.1) - zlib version
24
-
*`PCRE2_VERSION` (default 10.45 for NGINX 1.22.0 and later, or 8.45 for earlier) - PCRE1 or PCRE2 version
25
-
*`OPENSSL_VERSION` (default 3.5.0 for NGINX 1.22.0 and later, or 1.1.1w for earlier) - OpenSSL version
26
-
*`NGX_VERSION` (default 1.28.0) - NGINX OSS version
27
-
*`NGX_DEBUG` (default to false) - if set to true, then will compile NGINX `--with-debug` option
35
+
For example, this is how you would compile the [examples](#examples) using a
36
+
specific version of NGINX:
28
37
29
-
For example, this is how you would compile the [examples](examples) using a specific version of NGINX and enabling
After compilation, the modules can be found in the path `target/release/examples/` ( with the `.so` file extension for
41
-
Linux or `.dylib` for MacOS).
44
+
You can build your Rust-based module as a part of the NGINX build process by
45
+
providing a `config` script implementation and passing the `--add-module`/
46
+
`--add-dynamic-module` options to the configure script.
42
47
43
-
Additionally, the folder `.cache/nginx/{NGX_VERSION}/{TARGET}` (`{TARGET}` means rustc's target triple string) will contain the compiled version of NGINX used to build
44
-
the SDK. You can start NGINX directly from this directory if you want to test the module.
48
+
See the following example integration scripts: [`examples/config`] and
49
+
[`examples/config.make`].
45
50
46
-
The following environment variables can be used to change locations of cache directory and NGINX directory:
*`CACHE_DIR` (default `[nginx-sys's root directory]/.cache`) - the directory containing cache files, means PGP keys, tarballs, PGP signatures, and unpacked source codes. It also contains compiled NGINX in default configuration.
49
-
*`NGINX_INSTALL_ROOT_DIR` (default `{CACHE_DIR}/nginx`) - the directory containing the series of compiled NGINX in its subdirectories
50
-
*`NGINX_INSTALL_DIR` (default `{NGINX_INSTALL_BASE_DIR}/{NGX_VERSION}/{TARGET}`) - the directory containing the NGINX compiled in the build
54
+
### Building with vendored NGINX sources
51
55
52
-
### Mac OS dependencies
56
+
It is possible to build module with a vendored copy of the NGINX sources
57
+
provided in the `nginx-src` crate by enabling feature `vendored`:
53
58
54
-
In order to use the optional GNU make build process on MacOS, you will need to install additional tools. This can be
55
-
done via [homebrew](https://brew.sh/) with the following command:
56
-
```
59
+
By default, this will use the latest stable release of NGINX and require
60
+
system-wide installation of build dependencies (OpenSSL, PCRE2, Zlib).
61
+
62
+
The behavior of vendored builds can be customized with environment variables,
63
+
as documented in the [nginx-src](./nginx-src/) crate README.
64
+
65
+
**NOTE**: We recommend to build the module binaries against the exact source and
66
+
configuration of the NGINX build that you are planning to use in production,
67
+
and that is unlikely to be possible with the vendored source.
68
+
69
+
`configure` arguments alter the APIs and the symbols visible to the Rust code,
70
+
and some OS distributions are known to ship nginx packages with API-breaking
71
+
patches applied.
72
+
73
+
### Dependencies
74
+
75
+
The following dependencies are required to build a Rust NGINX module on Linux
76
+
or BSD platform:
77
+
78
+
- NGINX build dependencies: C compiler, make, OpenSSL, PCRE2, and Zlib.
79
+
- Rust toolchain (1.81.0 or later)
80
+
-[libclang] for rust-bindgen
81
+
82
+
The installation process and the package names are system-dependent. Please,
83
+
consult the documentation for your distribution.
84
+
85
+
Note that on some systems you will need `-devel` or `-dev` versions of the
86
+
packages.
87
+
88
+
For example, [Dockerfile] contains the installation commands for Debian Linux.
In order to use the optional GNU make build process on macOS, you will need
96
+
to install additional tools. This can be done via [homebrew](https://brew.sh/)
97
+
with the following command:
98
+
99
+
```sh
57
100
brew install make openssl grep
58
101
```
59
102
60
-
Additionally, you may need to set up LLVM and clang. Typically, this is done as follows:
103
+
Additionally, you may need to set up LLVM and clang. Typically, this is done
104
+
as follows:
61
105
62
-
```
106
+
```sh
63
107
# make sure xcode tools are installed
64
108
xcode-select --install
65
109
# instal llvm
66
110
brew install --with-toolchain llvm
67
111
```
68
112
69
-
### Linux dependencies
113
+
<!-- cargo-sync-readme end -->
70
114
71
-
See the [Dockerfile](Dockerfile) for dependencies as an example of required packages on Debian Linux.
115
+
### Examples
72
116
73
-
### Build example
117
+
Example modules are available in [examples] folder.
118
+
You can use `cargo build --package=examples --examples` to build these examples.
119
+
After compilation, the modules can be found in the path `target/debug/examples/`
120
+
(with the `.so` file extension for Linux or `.dylib` for macOS).
121
+
Add `--features=linux` to build Linux specific modules.
74
122
75
-
Example modules are available in [examples](examples) folder. You can use `cargo build --package=examples --examples` to build these examples. After building, you can find the `.so` or `.dylib` in the `target/debug` folder. Add `--features=linux` to build linux specific modules. **NOTE**: adding the "linux" feature on MacOS will cause a build failure.
123
+
**NOTE**: adding the "linux" feature on macOS will cause a build failure.
If you require a customized NGINX configuration, you can build a module against an existing pre-configured source tree.
83
-
To do that, you need to set the `NGINX_BUILD_DIR` variable to an _absolute_ path of the NGINX build directory (`--builddir`, defaults to the `objs` in the source directory).
84
-
Only the `./configure` step of the NGINX build is mandatory because bindings don't depend on any of the artifacts generated by `make`.
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.
93
-
See the following example integration scripts: [`examples/config`](examples/config) and [`examples/config.make`](examples/config.make).
0 commit comments