docs(*) clarify differences between INSTALL.md and DEVELOPER.md

Kong · Oct 10, 2024 · ea1475c · ea1475c
1 parent 353f73d
commit ea1475c
Show file tree

Hide file tree

Showing 2 changed files with 65 additions and 83 deletions.
diff --git a/docs/DEVELOPER.md b/docs/DEVELOPER.md
@@ -1,22 +1,21 @@
-# Developer documentation
+# Developer Documentation
 
-The building process for ngx_wasm_module is inherent to that of Nginx and
-therefore relies on `make`.
+This document describes the **development environment and idiomatic workflow for
+ngx_wasm_module**. For instructions on how to build an Nginx/OpenResty release
+with ngx_wasm_module, consult [INSTALL.md].
 
-The below instructions will guide you through the development environment and
-idiomatic workflow for ngx_wasm_module. It has not been tested in many
-environments yet and may still need refinements; reports are very much welcome.
+The building process for ngx_wasm_module is encapsulated by the project's
+`Makefile`.
 
 ## Table of Contents
 
-- [Requirements](#requirements)
-    - [WebAssembly runtime](#webassembly-runtime)
+- [1. Requirements](#1-requirements)
     - [Dependencies](#dependencies)
     - [Optional dependencies](#optional-dependencies)
-- [Setup the build environment](#setup-the-build-environment)
-- [Makefile targets](#makefile-targets)
-- [Build from source](#build-from-source)
+- [2. Setup the build environment](#2-setup-the-build-environment)
+- [3. Build from source](#3-build-from-source)
     - [Build options](#build-options)
+- [Makefile targets](#makefile-targets)
 - [Tests suites](#tests)
     - [Run integration tests](#run-integration-tests)
     - [Run building tests](#run-building-tests)
@@ -33,7 +32,7 @@ environments yet and may still need refinements; reports are very much welcome.
 - [FAQ](#faq)
     - [How to quickly test a filter or some bytecode?](#how-to-quickly-test-a-filter-or-some-bytecode)
 
-## Requirements
+## 1. Requirements
 
 Most of the development of this project currently relies on testing WebAssembly
 modules produced from Rust crates. Hence, while not technically a requirement to
@@ -48,20 +47,6 @@ the system will quickly become necessary for development:
 
 [Back to TOC](#table-of-contents)
 
-### WebAssembly runtime
-
-Several runtimes are supported:
-
-- [Wasmtime](https://docs.wasmtime.dev/c-api/)
-- [Wasmer](https://github.com/wasmerio/wasmer)
-- [V8](https://v8.dev)
-
-All of them can be automatically installed in the build environment via the
-`make setup` command described below. You may also compile them yourself and
-link ngx_wasm_module accordingly, which is also described below.
-
-[Back to TOC](#table-of-contents)
-
 ### Dependencies
 
 To build Nginx from source and run the test suite, some dependencies must be
@@ -121,7 +106,7 @@ testing during `make test`.
 
 [Back to TOC](#table-of-contents)
 
-## Setup the build environment
+## 2. Setup the build environment
 
 Setup a `work/` directory which will bundle the Wasm runtimes plus all of the
 extra building and testing dependencies:
@@ -163,27 +148,7 @@ release artifacts).
 
 [Back to TOC](#table-of-contents)
 
-## Makefile targets
-
-| Target             | Description                                            |
-| ------------------:| -------------------------------------------------------|
-| `setup`            | Setup the build environment
-| `build` (default)  | Build Nginx with ngx_wasm_module (static)
-| `test`             | Run the tests
-| `test-build`       | Run the build options test suite
-| `lint`             | Lint the sources and test cases
-| `reindex`          | Automatically format the `.t` test files
-| `update`           | Run `cargo update` in all workspaces
-| `todo`             | Search the project for "TODOs" (source, tests, scripts)
-| `act`              | Build and run the CI environment
-| `changelog`        | Print all changelog-worthy commits since the last release
-| `clean`            | Clean the latest build
-| `cleanup`          | Does `clean` and also cleans some more of the build environment to free-up disk space
-| `cleanall`         | Destroy the build environment
-
-[Back to TOC](#table-of-contents)
-
-## Build from source
+## 3. Build from source
 
 The build process will try to find a Wasm runtime in the following locations
 (in order):
@@ -302,7 +267,7 @@ To build with
 [AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html):
 
 ```sh
-CC=clang NGX_BUILD_FSANITIZE=address make
+CC=clang NGX_BUILD_FSANITIZE=address NGX_BUILD_CC_OPT='-O0' NGX_BUILD_NOPOOL=1 make
 ```
 
 To build with [Clang's Static Analyzer](https://clang-analyzer.llvm.org/):
@@ -336,6 +301,26 @@ NGX_BUILD_NOPOOL=1 NGX_BUILD_DEBUG=1 NGX_WASM_RUNTIME=wasmtime NGX_BUILD_CC_OPT=
 
 [Back to TOC](#table-of-contents)
 
+## Makefile targets
+
+| Target             | Description                                            |
+| ------------------:| -------------------------------------------------------|
+| `setup`            | Setup the build environment
+| `build` (default)  | Build Nginx with ngx_wasm_module (static)
+| `test`             | Run the tests
+| `test-build`       | Run the build options test suite
+| `lint`             | Lint the sources and test cases
+| `reindex`          | Automatically format the `.t` test files
+| `update`           | Run `cargo update` in all workspaces
+| `todo`             | Search the project for "TODOs" (source, tests, scripts)
+| `act`              | Build and run the CI environment
+| `changelog`        | Print all changelog-worthy commits since the last release
+| `clean`            | Clean the latest build
+| `cleanup`          | Does `clean` and also cleans some more of the build environment to free-up disk space
+| `cleanall`         | Destroy the build environment
+
+[Back to TOC](#table-of-contents)
+
 ## Test suites
 
 ### Run integration tests
@@ -800,3 +785,4 @@ You will find error and access logs to inspect at `t/servroot/logs`.
 [proxy-wasm-go-sdk]: https://github.com/tetratelabs/proxy-wasm-go-sdk
 [proxy-wasm-assemblyscript-sdk]: https://github.com/Kong/proxy-wasm-assemblyscript-sdk
 [DIRECTIVES.md]: DIRECTIVES.md
+[INSTALL.md]: INSTALL.md
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
@@ -1,50 +1,45 @@
-# Install
+# Installation Instructions
 
-This document describes the building process to **compile an Nginx release with
-ngx_wasm_module as an addon**.
-
-ngx_wasm_module source releases are available as
-`ngx_wasm_module-*.tar.gz` assets at:
-https://github.com/Kong/ngx_wasm_module/releases.
+This document describes the steps to **compile an Nginx/OpenResty release with
+ngx_wasm_module as an addon**. For instructions on the development environment
+of the module, consult [DEVELOPER.md].
 
 **Note:** the `wasmx-*.tar.gz` releases are pre-compiled, self-contained
 binaries of Nginx built with this module and as such, do not necessitate any
 particular installation steps. Download these releases and instantly use the
-`nginx` binary.
-
-If you wish however to use other Nginx compilation flags (e.g. add/disable other
-modules, configure default options, non-default platform/architecture
-support...) you will then need to compile Nginx yourself following the steps
-provided below.
+`nginx` binary. However, if you wish to use other Nginx compilation flags (e.g.
+add/disable other modules, configure default options, non-default
+platform/architecture support...) you will then need to compile Nginx yourself
+following the steps provided below.
 
 ## Table of Contents
 
 - [Requirements](#requirements)
-    - [Nginx](#nginx)
-    - [WebAssembly runtime](#webassembly-runtime)
-    - [ngx_wasm_module release](#ngx-wasm-module-release)
-    - [Rust (optional)](#rust-optional)
+    - [1. Nginx](#1-nginx)
+    - [2. WebAssembly runtime](#2-webassembly-runtime)
+    - [3. ngx_wasm_module release](#3-ngx_wasm_module-release)
+    - [4. Rust (optional)](#4-rust-optional)
 - [Build](#build)
 - [Build Examples](#build-examples)
 - [Build ngx-wasm-rs separately]
 
 ## Requirements
 
-### Nginx
+### 1. Nginx
 
 Ensure that you have all the necessary dependencies to build Nginx on your
-system. See [DEVELOPER.md](DEVELOPER.md) for a list of platform-specific
-dependencies.
+system. See [DEVELOPER.md] for a list of platform-specific dependencies (i.e.
+OpenSSL, PCRE, zlib, and a compiler).
 
-Download Nginx at https://nginx.org/en/download.html and extract it:
+Download an Nginx release at https://nginx.org/en/download.html and extract it:
 
 ```
 tar -xvf nginx-*.tar.gz
 ```
 
 [Back to TOC](#table-of-contents)
 
-### WebAssembly runtime
+### 2. WebAssembly runtime
 
 Several runtimes are supported, and at least one of them must be specified:
 
@@ -57,11 +52,11 @@ Several runtimes are supported, and at least one of them must be specified:
 - [V8](https://v8.dev) (not pre-built for embedding; but can be compiled locally
   by this module's build environment: run `NGX_WASM_RUNTIME=v8 make setup`
   *without* having set `NGX_WASM_RUNTIME_LIB` or `NGX_WASM_RUNTIME_INC`. See
-  [DEVELOPER.md](docs/DEVELOPER.md) for more details).
+  [DEVELOPER.md] for more details).
 
 [Back to TOC](#table-of-contents)
 
-### ngx_wasm_module release
+### 3. ngx_wasm_module release
 
 Download any of the source code releases at
 https://github.com/Kong/ngx_wasm_module/releases and extract the archive:
@@ -70,9 +65,11 @@ https://github.com/Kong/ngx_wasm_module/releases and extract the archive:
 tar -xvf ngx_wasmx_module-*.tar.gz
 ```
 
+Or use a local copy of this repository.
+
 [Back to TOC](#table-of-contents)
 
-### Rust (optional)
+### 4. Rust (optional)
 
 The module configuration process (i.e. Nginx `./configure` step) automatically
 builds a Rust library ([lib/ngx-wasm-rs]) as a bundled dependency when using
@@ -93,20 +90,19 @@ this module.
 
 ## Build
 
-Configure Nginx with ngx_wasm_module and any other flags typically given to your
-Nginx builds:
+Configure Nginx with ngx_wasm_module and link the Wasm runtime:
 
 ```
 cd nginx-*
 ./configure \
   --add-module=/path/to/ngx_wasm_module \
-  --with-cc-opt='-O3 -I/path/to/wasmtime/include' \
+  --with-cc-opt='-I/path/to/wasmtime/include' \
   --with-ld-opt='-L/path/to/wasmtime/lib -lwasmtime -Wl,-rpath,/path/to/wasmtime/lib'
 ```
 
 > Note: to compile with Wasmer, export the `NGX_WASM_RUNTIME=wasmer` environment
-> variable. See [Build Examples](#build-examples) for a list of supported environment
-> variables.
+> variable. See [Build Examples](#build-examples) for a list of supported
+> environment variables.
 
 Then, build and install Nginx:
 
@@ -178,7 +174,7 @@ export NGX_WASM_RUNTIME=v8
 ```
 
 You may also export the following environment variables and avoid having to
-specify `--with-cc-opt` and `--with-ld-opt`:
+specify the Wasm runtime through `--with-cc-opt` and `--with-ld-opt`:
 
 ```
 export NGX_WASM_RUNTIME={wasmtime,wasmer,v8} # defaults to wasmtime if unspecified
@@ -187,13 +183,12 @@ export NGX_WASM_RUNTIME_LIB=/path/to/runtime/lib
 ./configure --add-module=/path/to/ngx_wasm_module
 ```
 
-The following examples assume the above environment variables are still set.
+**For brevity, the following examples assume the above environment variables are
+still set.**
 
 Configure Nginx and ngx_wasm_module with a prefix and a few compiler options:
 
 ```
-export NGX_WASM_RUNTIME={wasmtime,wasmer,v8}
-
 ./configure \
   --add-module=/path/to/ngx_wasm_module \
   --prefix=/usr/local/nginx \
@@ -267,3 +262,4 @@ combine the static Wasmer library with a dynamic ngx-wasm-rs library.
 
 [Build ngx-wasm-rs separately]: #build-ngx-wasm-rs-separately
 [lib/ngx-wasm-rs]: ../lib/ngx-wasm-rs
+[DEVELOPER.md]: DEVELOPER.md