From 6a4e2958fa931b28eb50025a81cc88df463ae19a Mon Sep 17 00:00:00 2001 From: Thibault Charbonnier Date: Thu, 10 Oct 2024 14:13:47 -0700 Subject: [PATCH] docs(*) clarify differences between INSTALL.md and DEVELOPER.md --- docs/DEVELOPER.md | 15 ++++++++------- docs/INSTALL.md | 26 +++++++++++--------------- 2 files changed, 19 insertions(+), 22 deletions(-) diff --git a/docs/DEVELOPER.md b/docs/DEVELOPER.md index 9e955b113..4a8234595 100644 --- a/docs/DEVELOPER.md +++ b/docs/DEVELOPER.md @@ -1,11 +1,11 @@ -# 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 @@ -302,7 +302,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/): @@ -800,3 +800,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 index 62cf112f7..fd4982028 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -1,21 +1,16 @@ -# 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 process 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 @@ -34,9 +29,9 @@ provided below. 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. +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 @@ -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