Improve Unix install instructions

[TangentFoxy]

When running ./configure while following the instructions listed on the homepage, I get a cryptic error:

Checking Lua includes... lua.h not found (looked in /usr/include, /usr/include/lua/5.1, /usr/include/lua5.1)
You may want to use the flag --with-lua or --with-lua-include. See --help.

Personally, I know for this specific case I need to install libdev5.1-dev (using Ubuntu 18.04 so that's the package name), but for new users this takes a bit of searching before you figure out what you need (I remember I almost gave up on a lot of stuff because of how much difficulty I encountered with this the first time).

Additionally, when you click install at the top of the page, and follow through to the wiki's Unix instructions, it tells you to use different commands to install.

Now I see while running ./configure and it completing successfully that the difference in these is whether LuaRocks is itself installed as a rock. What's the difference? What are advantages/disadvantages to each?

[hishamhm]

Personally, I know for this specific case I need to install libdev5.1-dev (using Ubuntu 18.04 so that's the package name)

Indeed, this is the solution for Ubuntu 18.04, but that's the solution for a specific distro. For Fedora it would be something else, etc. So it's hard for us to give a better error message than to say something to the effect of "we looked for these file in these places and could not find it, if the file is somewhere else, use a flag to explicitly tell us where" (which is what the message is trying to say). Would adding the sentence You may want to install the package for your system that provides lua.h help?

Additionally, when you click install at the top of the page, and follow through to the wiki's Unix instructions, it tells you to use different commands to install.

Where exactly? It tells you this:

• Run "./configure". (This will attempt to detect your installation of Lua. If you get any error messages, see the section "Customizing your settings", below.)
• Run "make build".
• As superuser, run "make install".

The flags given in the error message above are also listed in the "Customizing your settings" section.

What's the difference? What are advantages/disadvantages to each?

• Linux distribution mantainers will usually package them as not-a-rock, so that the system package manager manages the installed files, and LuaRocks doesn't modify files that are being tracked by the system database.
• End-users installing LuaRocks from sources can benefit from installing it as-a-rock, so that they can upgrade to new versions later by running luarocks install luarocks.

We are working on overhauling the overall installation process, so this kind of feedback is definitely welcome. Thank you!

[TangentFoxy]

Indeed, this is the solution for Ubuntu 18.04, but that's the solution for a specific distro. [...]

I understand that, my complaint is not about the error message, but that nowhere does LuaRocks indicate it needs Lua's headers. If there was a brief message stating you need to install those, that alone would reduce confusion (start googling "how to install lua headers [os]" instead of the error message..although doing this just now doesn't immediately lead to a beginner-friendly result). Or even better, state that and give examples for common OSes.

Additionally, when you click install at the top of the page, and follow through to the wiki's Unix instructions, it tells you to use different commands to install.

Where exactly?

The LuaRocks homepage differs in that it tells you to run sudo make bootstrap where the linked wiki says to run make build and make install as a superuser. (Which I now understand the difference, but didn't for a long time and just sort of hoped whichever instructions I used worked).

Thank you for explaining the difference between bootstrap and install, I had not read through the entire document previously.

[hishamhm]

I understand that, my complaint is not about the error message, but that nowhere does LuaRocks indicate it needs Lua's headers.

The message used "Lua includes" as a synonym to "Lua headers". Noted: we'll use "headers" in the future.

The LuaRocks homepage differs in that it tells you to run sudo make bootstrap where the linked wiki says to run make build and make install as a superuser.

Ahh, thanks for the heads-up. We'll improve the wiki.