doc: documented how to link against a static library (or object file archive) consisting of (many) compiled Lua module files.

README.markdown

@@ -5923,10 +5923,10 @@ Then when building Nginx or OpenResty, pass the `--with-ld-opt="foo.o"` option t
 
 ```bash
 
-    ./configure --with-ld-opt="foo.o" ...
+    ./configure --with-ld-opt="/path/to/foo.o" ...
 ```
 
-assuming that the `foo.o` file has been copied to the current working directory. Finally, you can just do the following in any Lua code run by ngx_lua:
+Finally, you can just do the following in any Lua code run by ngx_lua:
 
 ```lua
 
@@ -5947,6 +5947,29 @@ then you need to rename the `foo.lua` file to `resty_foo.lua` before compiling i
 
 It is important to use exactly the same version of LuaJIT when compiling `.lua` files to `.o` files as building nginx + ngx_lua. This is because the LuaJIT bytecode format may be incompatible between different LuaJIT versions. When the bytecode format is incompatible, you will see a Lua runtime error saying that the Lua module is not found.
 
+When you have multiple `.lua` files to compile and link, then just specify their `.o` files at the same time in the value of the `--with-ld-opt` option. For instance,
+
+```bash
+
+    ./configure --with-ld-opt="/path/to/foo.o /path/to/bar.o" ...
+```
+
+If you have just too many `.o` files, then it might not be feasible to name them all in a single command. In this case, you can build a static library (or archive) for your `.o` files, as in
+
+```bash
+
+    ar rcus libmyluafiles.a *.o
+```
+
+then you can link the `myluafiles` archive as a whole to your nginx executable:
+
+```bash
+
+    ./configure --with-ld-opt="-L/path/to/lib -Wl,--whole-archive -lmyluafiles -Wl,--no-whole-archive"
+```
+
+where `/path/to/lib` is the path of the directory containing the `libmyluafiles.a` file. It should be noted that the linker option `--while-archive` is required here because otherwise our archive will be skipped because no symbols in our archive are mentioned in the main parts of the nginx executable.
+
 [Back to TOC](#table-of-contents)
 
 Data Sharing within an Nginx Worker

doc/HttpLuaModule.wiki

@@ -5024,10 +5024,10 @@ What matters here is the name of the <code>.lua</code> file, which determines ho
 Then when building Nginx or OpenResty, pass the <code>--with-ld-opt="foo.o"</code> option to the <code>./configure</code> script:
 
 <geshi lang="bash">
-    ./configure --with-ld-opt="foo.o" ...
+    ./configure --with-ld-opt="/path/to/foo.o" ...
 </geshi>
 
-assuming that the <code>foo.o</code> file has been copied to the current working directory. Finally, you can just do the following in any Lua code run by ngx_lua:
+Finally, you can just do the following in any Lua code run by ngx_lua:
 
 <geshi lang="lua">
     local foo = require "foo"
@@ -5046,6 +5046,26 @@ then you need to rename the <code>foo.lua</code> file to <code>resty_foo.lua</co
 
 It is important to use exactly the same version of LuaJIT when compiling <code>.lua</code> files to <code>.o</code> files as building nginx + ngx_lua. This is because the LuaJIT bytecode format may be incompatible between different LuaJIT versions. When the bytecode format is incompatible, you will see a Lua runtime error saying that the Lua module is not found.
 
+When you have multiple <code>.lua</code> files to compile and link, then just specify their <code>.o</code> files at the same time in the value of the <code>--with-ld-opt</code> option. For instance,
+
+<geshi lang="bash">
+    ./configure --with-ld-opt="/path/to/foo.o /path/to/bar.o" ...
+</geshi>
+
+If you have just too many <code>.o</code> files, then it might not be feasible to name them all in a single command. In this case, you can build a static library (or archive) for your <code>.o</code> files, as in
+
+<geshi lang="bash">
+    ar rcus libmyluafiles.a *.o
+</geshi>
+
+then you can link the <code>myluafiles</code> archive as a whole to your nginx executable:
+
+<geshi lang="bash">
+    ./configure --with-ld-opt="-L/path/to/lib -Wl,--whole-archive -lmyluafiles -Wl,--no-whole-archive"
+</geshi>
+
+where <code>/path/to/lib</code> is the path of the directory containing the <code>libmyluafiles.a</code> file. It should be noted that the linker option <code>--while-archive</code> is required here because otherwise our archive will be skipped because no symbols in our archive are mentioned in the main parts of the nginx executable.
+
 = Data Sharing within an Nginx Worker =
 
 To globally share data among all the requests handled by the same nginx worker process, encapsulate the shared data into a Lua module, use the Lua <code>require</code> builtin to import the module, and then manipulate the shared data in Lua. This works because required Lua modules are loaded only once and all coroutines will share the same copy of the module (both its code and data). Note however that Lua global variables (note, not module-level variables) WILL NOT persist between requests because of the one-coroutine-per-request isolation design.