doc: improve 'how-to-build'

Signed-off-by: fukiki <one.fhh@163.com>
apache · Jan 14, 2021 · 9324b79 · 9324b79
1 parent 9ccdc29
commit 9324b79
Show file tree

Hide file tree

Showing 2 changed files with 87 additions and 0 deletions.
diff --git a/doc/how-to-build.md b/doc/how-to-build.md
@@ -109,6 +109,49 @@ Makefile rules:
 Environment variable can be used to configure APISIX. Please take a look at `conf/config.yaml` to
 see how to do it.
 
+### Troubleshooting
+**Compile and install luasocket**
+
+If you run `make init` or `make run` after `make deps`, get an issue `Symbol not found: _luaL_openlib`. Maybe it's due to Lua compatibility settings when building luasocket. You can use LuaJIT or Lua 5.1, if it still doesn't work, you can manually compile and install luasocket.
+
+- Download the source code to compile and install luasocket.
+
+```sh
+git clone https://github.com/diegonehab/luasocket.git
+make
+make install
+```
+
+If you get error as below:
+
+```
+/Applications/Xcode.app/Contents/Developer/usr/bin/make -C src linux
+/Applications/Xcode.app/Contents/Developer/usr/bin/make all-unix PLAT=linux
+gcc  -I/usr/include/lua/5.1 -I/usr/include/lua5.1 -DLUASOCKET_NODEBUG -Wall -Wshadow -Wextra -Wimplicit -O2 -ggdb3 -fpic   -c -o luasocket.o luasocket.c
+In file included from luasocket.c:15:
+./luasocket.h:27:10: fatal error: 'lua.h' file not found
+#include "lua.h"
+         ^~~~~~~
+1 error generated.
+make[2]: *** [luasocket.o] Error 1
+make[1]: *** [linux] Error 2
+make: *** [linux] Error 2
+```
+
+Lua.h file was not found at compile time, installed in the system is lua 5.3.5_1, modify the compiler parameters:
+
+```sh
+make LUAINC=/usr/local/Cellar/lua/5.3.5_1/include/lua macosx
+make LUAINC=/usr/local/Cellar/lua/5.3.5_1/include/lua macosx install
+```
+
+- Copy the compiled and installed files to the deps of apisix.
+
+```
+cp /usr/local/lib/lua/5.1/socket/* your-path/apisix/deps/lib/lua/5.1/socket/
+cp /usr/local/lib/lua/5.1/mime/* your-path/apisix/deps/lib/lua/5.1/mime/
+```
+
 ## 4. Test
 
 1. Install perl's package manager `cpanminus` first

diff --git a/doc/zh-cn/how-to-build.md b/doc/zh-cn/how-to-build.md
@@ -105,6 +105,50 @@ Makefile rules:
     license-check:    Check Lua source code for Apache License
 ```
 
+### 疑难问题解答
+**编译并安装 luasocket**
+
+在执行完`make deps`之后，执行`make init`或`make run`时遇到问题`Symbol not found: _luaL_openlib`，可能是在编译  luasocket 时的 lua 兼容性设置导致，推荐使用 LuaJIT 或 lua 5.1 版本。若更改 lua 版本后问题任然存在，可使用源码重新编译安装 luasocket。
+
+- 下载 luasocket 的源码编译并安装
+
+```sh
+git clone https://github.com/diegonehab/luasocket.git
+make
+make install
+```
+
+编译及安装过程中可能遇到以下错误：
+
+```
+/Applications/Xcode.app/Contents/Developer/usr/bin/make -C src linux
+/Applications/Xcode.app/Contents/Developer/usr/bin/make all-unix PLAT=linux
+gcc  -I/usr/include/lua/5.1 -I/usr/include/lua5.1 -DLUASOCKET_NODEBUG -Wall -Wshadow -Wextra -Wimplicit -O2 -ggdb3 -fpic   -c -o luasocket.o luasocket.c
+In file included from luasocket.c:15:
+./luasocket.h:27:10: fatal error: 'lua.h' file not found
+#include "lua.h"
+         ^~~~~~~
+1 error generated.
+make[2]: *** [luasocket.o] Error 1
+make[1]: *** [linux] Error 2
+make: *** [linux] Error 2
+
+```
+
+编译时无法找到 lua.h 文件, 查询本地环境 lua 版本及安装位置，修改编译参数:
+
+```sh
+make LUAINC=/usr/local/Cellar/lua/5.3.5_1/include/lua macosx
+make LUAINC=/usr/local/Cellar/lua/5.3.5_1/include/lua macosx install
+```
+
+- 将编译安装好的 luasocket 相关文件拷贝到项目的 `deps` 目录下：
+
+```
+cp /usr/local/lib/lua/5.1/socket/* your-path/apisix/deps/lib/lua/5.1/socket/
+cp /usr/local/lib/lua/5.1/mime/* your-path/apisix/deps/lib/lua/5.1/mime/
+```
+
 ## 4. 运行测试案例
 
 1. 先安装 perl 的包管理器 cpanminus