[Rpm-maint] [rpm-software-management/rpm] Add a rpm-lua(7) man page for the embedded Lua interpreter (PR #3809)

[Florian Festi]

@ffesti requested changes on this pull request.

While the lists of functions look good the explaining in between is still a bit thin. Yes, this isn't a tutorial but people need to be able to pick up on what this is about.

> @@ -0,0 +1,960 @@
+RPM-LUA(7)
+
+# NAME
+
+rpm-lua - RPM embedded Lua interpreter
+
+# SYNOPSIS
+
+%scriptlet -p <lua>
+
+%{lua:...}
+
+# DESCRIPTION
+RPM includes an embedded Lua interpreter for advanced *rpm-macroproc*(7) and
+special install-scriptlets needs.

Using *rpm-macroproc*(7) as a noun here is a bit much. "Special needs" does have (at least in my mind) connotations we probably don't want here. Also the tone is a bit too judgemental for my taste. What about something along the lines of:

RPM includes an embedded lua(1) interpreter. It can be used for both macros and scriptlets. Being a programming language made for embedding it makes complicated tasks easier than relying on RPM macros and shell alone. Being part of the RPM process allows doing things without external dependencies. This can become handy e.g. early during the initial installation of a system.

> +	v2 = rpm.ver(3, '5a', 1)
+	if v1 < v2 then
+	   ...
+	end
+
+	if v1.e then
+	   ...
+	end
+	```
+
+## posix extension
+
+Lua standard library offers fairly limited set of io operations.
+The *posix* extension greatly enhances what can be done from Lua.
+
+The following functions are available in *posix* namespace, ie to call

in THE *posix* namespace

> +```
+
+## Relocatable packages
+Scriptlets of relocatable packages additionally carry a global
+*RPM_INSTALL_PREFIX* table containing all the possible prefixes of the
+package.
+
+Added: 4.18.0
+
+## Exit status
+While scriptlets shouldn't be allowed to fail normally, you can signal
+scriptlet failure status by using Lua's *error(*_msg_, [_level_]*)*
+function if you need to.
+
+# SPEC FILES
+When invoked during *rpm-spec*(5) parsing, the RPM Lua environment has the

rpm-spec (5) doesn't seem to exist yet. This also deserves a bit more explicit explanation where exactly this applies instead of just a man page name.

> +	```
+
+*unsetenv(*_name_*)*
+	Remove a variable _name_ from environment. See also *unsetenv*(3).
+
+	Example:
+	```
+	posix.unsetenv('HOME')
+	```
+
+# Extending and customizing
+On initialization, RPM executes a global _init.lua_ Lua initialization script,
+typically located in _/usr/lib/rpm/init.lua_. This can be used for performing
+custom runtime configuration of RPM and adding global functions and variables
+to the RPM Lua environment without recompiling RPM.
+

There needs to be a discussion about the state of the interpreter. E.g. if variables and functions are kept between calls - especially between scriptlets but also during builds and %lua macros in general. 

-- 
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/3809#pullrequestreview-2938878234
You are receiving this because you are subscribed to this thread.

Message ID: <rpm-software-management/rpm/pull/3809/review/2938878234 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rpm.org/pipermail/rpm-maint/attachments/20250618/d5fb4efb/attachment.htm>