fedora-llm-docs/Documents/pages/Lua.txt

= Lua Packaging Guidelines
:toc:

== What is Lua?

As described on the https://www.lua.org/[Lua website], Lua is

"Lua is a powerful, efficient, lightweight, embeddable scripting language.
It supports procedural programming, object-oriented programming, functional
programming, data-driven programming, and data description."

To learn Lua, read https://www.lua.org/pil/contents.html[Programming in Lua].

== Spec Template for a Lua Package

Many Lua packages use http://luarocks.org/[Lua-rocks] for packaging. It is helpful
to examine the `+.rockspec+` specification as a guide in writing your spec file.
Some packages require compilation of C programs, but others may be pure Lua. Both
will have very similar install locations.

....
Summary:        Lua integration with libev
Name:           lua-ev
License:        MIT

Version:        1.5
Release:        2%{?dist}

URL:            https://github.com/brimworks/lua-ev
Source0:        %{url}/archive/v%{version}/%{name}-%{version}.tar.gz

BuildRequires:  cmake
BuildRequires:  gcc
BuildRequires:  libev-devel
BuildRequires:  lua-devel

%description
Event loop programming with Lua.

%prep
%autosetup -n %{name}-%{version} 

%build
%cmake -DINSTALL_CMOD=%{lua_libdir}
%cmake_build

%install
%cmake_install 

%check
#packaged tests do not work directly
#Use example program as a smoke test
LUA_CPATH=%{buildroot}%{lua_libdir}/?.so \
lua example.lua
LUA_CPATH=%{buildroot}%{lua_libdir}/?.so \
lua -e 'ev = require "ev"; print(ev.version())'

%files
%license README
%doc example.lua
%{lua_libdir}/ev.so

%changelog
* Thu Dec 08 2022 Benson Muite <benson_muite@emailplus.org> - 1.5-1
- Use README as license

* Sat Nov 19 2022 Benson Muite <benson_muite@emailplus.org> - 1.5-2
- Fix install location based on review
- Add further smoke test

* Wed Nov 16 2022 Benson Muite <benson_muite@emailplus.org> - 1.5-1
- Initial release
....

== Naming

Lua add-on packages generally follow the naming scheme of `+lua-modulename+`
-- e.g. `+lua-filesystem+`, `+lua-lpeg+`, `+lua-moonscript+`. If the module name
makes it clear that it is an add-on for Lua, though, the module name
itself is sufficient. e.g. `+lutok+`.

Use your judgement -- e.g. the second `+l+` in `+lua-lpeg+` already stands for Lua,
but it might not be seen as unambiguous enough.

== Macros

The following macros for packaging lua extensions are provided by the
`+lua-devel+` package:

[%header,cols=2*]
|===
| Macro             | Description
| `+%lua_version+`  | version of system installed lua
| `+%lua_libdir+`   | installation directory for compiled modules
| `+%lua_pkgdir+`   | installation directory for arch-independent modules
| `+%lua_requires+` | declares the needed runtime dependencies for the binary package
|===

For EPEL, define the following macros at the top of your spec file:

....
%{!?lua_version: %global lua_version %{lua: print(string.sub(_VERSION, 5))}}
# for compiled modules
%{!?lua_libdir: %global lua_libdir %{_libdir}/lua/%{lua_version}}
# for arch-independent modules
%{!?lua_pkgdir: %global lua_pkgdir %{_datadir}/lua/%{lua_version}}
....

To make the package pull the correct runtime dependencies, declare them like this:

....
Requires: lua >= %{lua_version}
Requires: lua <  %{lua: os.setlocale('C'); print(string.sub(_VERSION, 5) + 0.1)}
....