Document how-to-build.md should add a troubleshooting of luasocket

[fukiki]

Improve Docs

Please describe which part of docs should be improved or typo fixed

When using the latest master branch code, apisix failed to run make init:

./bin/apisix init
lua: error loading module 'socket.core' from file '/Users/kiki/Documents/DevelopTools/src/github-apisix/deps/lib/lua/5.1/socket/core.so':
	dlopen(/Users/kiki/Documents/DevelopTools/src/github-apisix/deps/lib/lua/5.1/socket/core.so, 6): Symbol not found: _luaL_openlib
  Referenced from: /Users/kiki/Documents/DevelopTools/src/github-apisix/deps/lib/lua/5.1/socket/core.so
  Expected in: dynamic lookup
stack traceback:
	[C]: in ?
	[C]: in function 'require'
	...lopTools/src/github-apisix/deps/share/lua/5.1/socket.lua:12: in main chunk
	[C]: in function 'require'
	...ols/src/github-apisix/deps/share/lua/5.1/socket/http.lua:10: in main chunk
	[C]: in function 'require'
	./apisix/cli/etcd.lua:22: in main chunk
	[C]: in function 'require'
	./apisix/cli/ops.lua:18: in main chunk
	[C]: in function 'require'
	./bin/apisix:34: in main chunk
	[C]: in ?
make: *** [init] Error 1

Reason

LuaSocket uses the _luaL_openlib function from Lua 5.0. It should also be available on Lua 5.1 (and 5.2) if certain compatibility flags are defined in luaconf.h while building the Lua executable. Maybe, when installing luaSocket by executing make deps (luarocks install luasocket), the executable was built without compatibility flags.

Describe the solution you'd like

Download the source code to compile and install luasocket, then replace the executable file in deps for the project.

Document how-to-build.md should be improved, add the method and steps of compiling luasocket.

[spacewander]

@starsz

[starsz]

I think we can use luajit to interprets the bootstrap.
We can update the Shebang

apisix/bin/apisix

Line 1 in 1a1fe09

#!/usr/bin/env lua

.

What do you think about it? @spacewander

[spacewander]

I will vote for it.
What about @membphis's opinion?

[spacewander]

@fukiki
I think you made a mistake. As you mention in #3282 (comment), macosx Lua 5.3.5 Luarocks 3.4.0, it is not because the Lua is too old, it is because you compiled it with high Lua version but run it with low Lua version.

@starsz
Changed the code won't solve the problem if luasocket is built with Lua 5.3.

A better solution is to install luarocks with LuaJIT, and only allow running with LuaJIT.

[fukiki]

@spacewander
I understand the reason of the mistake and the solution, thanks for your explain.
I still wish that the document could add relevant content, to avoid subsequent people make the same mistake, if the mistake happens and kown how to fix it.
Hope the community could consider it.

[liuxiran]

Once I came to the same issue, and thanks to @spacewander, he told me that I have to use Lua5.1 instead, and then I tried to find Lua5.1 for fedora32(which is the os of my working machine), unfortunately there was not a suitable one. So recently, I still use the APSIX with commit: 7c5df5d343ef , which can worked well with lua-5.3.5.

It's just my personal clumsy opinion, if there is a doc to guide user to start the APISIX with different versions of Lua, it may reduce the user's starting cost, and at the same time it will expose more issues about APISIX's compatibility, and may also attract more partners to solve problems. Feels good, isn't it.

[spacewander]

@fukiki @liuxiran
The documentation need to be updated. I think we should mention that only LuaJIT is supported. Unless you know Lua well, it is not obvious to find the difference between Lua 5.1 and Lua 5.3. Since many platforms use Lua 5.3 by default, which is incompatible with Lua 5.1, switch to LuaJIT only can solve all the problem.

[membphis]

@fukiki
what is your OS name and version? what is the Luarocks version? what is the Lua version?

we need those information.

[spacewander]

By saying switch to LuaJIT only, I mean two things:

1. install Luarocks from source, and avoid installing Lua
2. change the #! in bin/apisix to use luajit.

[fukiki]

@fukiki
what is your OS name and version? what is the Luarocks version? what is the Lua version?

we need those information.

macOS Big Sur (11.1), install lua and luarocks by brew
lua 5.3.5
luarocks 3.4.0

[Fuchange]

• install Luarocks from source, and avoid installing Lua
• change the#!inbin/apisixto use luajit.

I found the change the#!inbin/apisixto use luajit method too and successfully verified that it can run in lua5.3 environment,

I agree this idea. This is a good start for APISIX to completely break away from system Lua.

By the way. I think this is a problem left over since ifeq ($(LUAROCKS_VER),luarocks 3.) was added to makefile .

If you don't want to have an impact on users using centos7, I can add a judgment on Lua version in a similar location

[membphis]

@fukiki
what is your OS name and version? what is the Luarocks version? what is the Lua version?
we need those information.

macOS Big Sur (11.1), install lua and luarocks by brew
lua 5.3.5
luarocks 3.4.0

many thx for your information, I have reproduced this bug with my Mac OS.

[membphis]

It works fine at my Mac OS. @fukiki I think you can make a try

so I think we can set the right luajit path in bin/apisix

[fukiki]

@spacewander @membphis
I set the right luajit path in bin/apisix, it also works well at my macos.

Changing the bin/apisix to use luajit is a good solution.

Thanks for your help again.

[membphis]

welcome PR to fix this issue