From 0e90c184ef44dae80be747983e27c6940fbea3b9 Mon Sep 17 00:00:00 2001 From: Tobiasz Laskowski Date: Sun, 15 Feb 2026 14:53:13 +0000 Subject: docs: Fix LUA_LIBDIR handling in example Makefile See: #1257 On most platforms LUA_LIBDIR is empty, so you get: Warning: unmatched variable LUA_LIBDIR And the resulting empty -L flag in the example can cause issues like: ld: warning: search path '-lpthread' not found It's also not sufficient to pass the -L flag, you also have to provide the actual library to link. I've updated the example to only set LUA_LIBDIR for windows where it is used by default. However, as noted in it is possible to do: luarocks config link_lua_explicitly true It would be better to respect this setting rather than hard-coding windows only, but I'm not sure the best way to check that config in the rockspec, I wonder if anyone else has any suggestions? [docs] Use implicit rules in example makefile See: https://www.gnu.org/software/make/manual/html_node/Catalogue-of-Rules.html#index-C_002c-rule-to-compile https://www.gnu.org/software/make/manual/html_node/Catalogue-of-Rules.html#index-linking_002c-predefined-rule-for https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html#index-CPPFLAGS https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html#index-LDFLAGS [docs] Fix LUA_LIBDIR handling in makefile example The example setup given here gives this warning on most systems: ``` Warning: unmatched variable LUA_LIBDIR ``` Also, you get an empty `-L` flag, which one some compilers will eat the following flag, causing issues, e.g. ``` ld: warning: search path '-lpthread' not found ``` This is because most environments do not require explicit linking of LUALIB, so it LUA_LIBDIR not set. This patch fixes the sample by only setting `LUA_LIBDIR` when it is actually needed, i.e. on windows. [docs] Fix example makefile for windows On windows, LUALIB is set to e.g. `lua51.dll`, which is the full name and does not work with `-llua51.dll`. Passing the full path here allows it to be linked properly. Another option is `-l:$(LUALIB)` to specify the full file name, but some linkers do not support that syntax. [docs] Fix broken formatting due to unescaped $ [docs] Highlight makefile syntax [docs] Use consistent whitespace Fixes markdown warnings about hard tabs --- ...ing_a_makefile_that_plays_nice_with_luarocks.md | 124 +++++++++++---------- 1 file changed, 68 insertions(+), 56 deletions(-) diff --git a/docs/creating_a_makefile_that_plays_nice_with_luarocks.md b/docs/creating_a_makefile_that_plays_nice_with_luarocks.md index 0caeeacb..cb7e57a0 100644 --- a/docs/creating_a_makefile_that_plays_nice_with_luarocks.md +++ b/docs/creating_a_makefile_that_plays_nice_with_luarocks.md @@ -41,57 +41,65 @@ These variables are not readily available in the Makefile, you need to tell LuaRocks to pass them to make. A simple rockspec that will do this looks like this: -``` +```lua package = "lrtest" version = "1.0-1" source = { url = "http://..." } build = { - type = "make", - build_variables = { - CFLAGS="$(CFLAGS)", - LIBFLAG="$(LIBFLAG)", - LUA_LIBDIR="$(LUA_LIBDIR)", - LUA_BINDIR="$(LUA_BINDIR)", - LUA_INCDIR="$(LUA_INCDIR)", - LUA="$(LUA)", - }, - install_variables = { - INST_PREFIX="$(PREFIX)", - INST_BINDIR="$(BINDIR)", - INST_LIBDIR="$(LIBDIR)", - INST_LUADIR="$(LUADIR)", - INST_CONFDIR="$(CONFDIR)", - }, + type = "make", + build_variables = { + CFLAGS="$(CFLAGS)", + LIBFLAG="$(LIBFLAG)", + LUA_BINDIR="$(LUA_BINDIR)", + LUA_INCDIR="$(LUA_INCDIR)", + LUA="$(LUA)", + }, + install_variables = { + INST_PREFIX="$(PREFIX)", + INST_BINDIR="$(BINDIR)", + INST_LIBDIR="$(LIBDIR)", + INST_LUADIR="$(LUADIR)", + INST_CONFDIR="$(CONFDIR)", + }, + platforms = { + windows = { + build_variables = { + -- windows requires linking lua library explicitly + LUA_LIBDIR="$(LUA_LIBDIR)", + LUALIB="$(LUALIB)", + } + } + } } ``` The corresponding Makefile looks like this: -``` +```make all: - @echo --- build - @echo CFLAGS: $(CFLAGS) - @echo LIBFLAG: $(LIBFLAG) - @echo LUA_LIBDIR: $(LUA_LIBDIR) - @echo LUA_BINDIR: $(LUA_BINDIR) - @echo LUA_INCDIR: $(LUA_INCDIR) - @echo LUA: $(LUA) + @echo --- build + @echo CFLAGS: $(CFLAGS) + @echo LIBFLAG: $(LIBFLAG) + @echo LUA_LIBDIR: $(LUA_LIBDIR) + @echo LUA_BINDIR: $(LUA_BINDIR) + @echo LUA_INCDIR: $(LUA_INCDIR) + @echo LUA: $(LUA) install: - @echo --- install - @echo INST_PREFIX: $(INST_PREFIX) - @echo INST_BINDIR: $(INST_BINDIR) - @echo INST_LIBDIR: $(INST_LIBDIR) - @echo INST_LUADIR: $(INST_LUADIR) + @echo --- install + @echo INST_PREFIX: $(INST_PREFIX) + @echo INST_BINDIR: $(INST_BINDIR) + @echo INST_LIBDIR: $(INST_LIBDIR) + @echo INST_LUADIR: $(INST_LUADIR) @echo INST_CONFDIR: $(INST_CONFDIR) ``` Now, if you call `luarocks make`, the output will look something like this: -``` +```make -- build CFLAGS: -O2 -fPIC LIBFLAG: -shared @@ -116,8 +124,8 @@ The `CONFDIR` and `PREFIX` variables point to locations where you can store configuration or other data for your module. Your code must be made aware of these paths in order to use them. If you use the `copy_directories` entry in the build section of your rockspec, -then what is mentioned there is copied to $(PREFIX) (i.e. a directory doc -will be available under $(PREFIX)/doc). If you copy directories in your +then what is mentioned there is copied to `$(PREFIX)` (i.e. a directory doc +will be available under `$(PREFIX)/doc`). If you copy directories in your `install` Makefile rule, you should do the same. Now, if your Makefile is meant to be used standalone as well, which it @@ -129,54 +137,60 @@ the Makefile. With this, a Makefile that is usable both from LuaRocks and standalone might look like this: -``` +```make CFLAGS = -fPIC -O2 LIBFLAG = -shared LUA_LIBDIR = /usr/local/lib/lua/5.2 LUA_BINDIR = /usr/local/bin LUA_INCDIR = /usr/local/include LUA = lua - + INST_PREFIX = /usr/local INST_BINDIR = $(INST_PREFIX)/bin INST_LIBDIR = $(INST_PREFIX)/lib/lua/5.2 INST_LUADIR = $(INST_PREFIX)/share/lua/5.2 INST_CONFDIR = $(INST_PREFIX)/etc - + all: - @echo --- build - @echo CFLAGS: $(CFLAGS) - @echo LIBFLAG: $(LIBFLAG) - @echo LUA_LIBDIR: $(LUA_LIBDIR) - @echo LUA_BINDIR: $(LUA_BINDIR) - @echo LUA_INCDIR: $(LUA_INCDIR) + @echo --- build + @echo CFLAGS: $(CFLAGS) + @echo LIBFLAG: $(LIBFLAG) + @echo LUA_LIBDIR: $(LUA_LIBDIR) + @echo LUA_BINDIR: $(LUA_BINDIR) + @echo LUA_INCDIR: $(LUA_INCDIR) install: - @echo --- install - @echo INST_PREFIX: $(INST_PREFIX) - @echo INST_BINDIR: $(INST_BINDIR) - @echo INST_LIBDIR: $(INST_LIBDIR) - @echo INST_LUADIR: $(INST_LUADIR) - @echo INST_CONFDIR: $(INST_CONFDIR) + @echo --- install + @echo INST_PREFIX: $(INST_PREFIX) + @echo INST_BINDIR: $(INST_BINDIR) + @echo INST_LIBDIR: $(INST_LIBDIR) + @echo INST_LUADIR: $(INST_LUADIR) + @echo INST_CONFDIR: $(INST_CONFDIR) ``` You probably don't just want to echo stuff, so here's how to use the variables when actually building or installing something: -``` -... +```make +#... + +CPPFLAGS = -I$(LUA_INCDIR) +LDFLAGS = $(LIBFLAG) + +# handle platforms with explicit linking of lua +ifdef LUA_LIBDIR +LDLIBS += $(LUA_LIBDIR)/$(LUALIB) +endif all: lrtest.so lrtest.so: lrtest.o - $(CC) $(LIBFLAG) -o $@ -L$(LUA_LIBDIR) $< lrtest.o: lrtest.c - $(CC) -c $(CFLAGS) -I$(LUA_INCDIR) $< -o $@ install: lrtest.so lrtest.lua - cp lrtest.so $(INST_LIBDIR) - cp lrtest.lua $(INST_LUADIR) + cp lrtest.so $(INST_LIBDIR) + cp lrtest.lua $(INST_LUADIR) ``` There is of course a lot more to a proper Makefile and rockspec, this is only @@ -186,5 +200,3 @@ variables are created by LuaRocks, which have to be passed to the Makefile in the same way. Check the other documentation, especially [Rockspec format](rockspec_format.md) and [Recommended practices for Makefiles](recommended_practices_for_makefiles.md), for details. - - -- cgit v1.2.3-55-g6feb