Executable notes: LuaRocks

[Eduardo Ochs <eduardoochs@...>]

Hi all,

Lua has been my favorite language since 2000 but I use it in a very
unix-ish way - I use pipes and io.popen() to call external programs
instead of loading existing libraries written in C or writing my own -
and I use luarocks very little because I feel that don't understand it
(them?) well enough... which means that I use Lua practically without
batteries.

A few months ago I gave a talk at the EmacsConf2019 about how I keep
"executable notes" of everything that I do, and I finished it with a
demo. It's here, and there is even a transcript of the demo part:

  http://angg.twu.net/emacsconf2019.html

I will use some of the tricks shown there in the demo part of the
video to explain why some things in LuaRocks are still mysterious to
me.



1. LuaRocks on Debian
=====================

I'm in a Debian box with lua5.1, lua5.2, lua5.3 and luarocks
installed, which means that I've done this:

  sudo apt-get install lua5.1 lua5.2 lua5.2 luarocks

I use a huge LUA_INIT file, but if I run this in a shell

  export LUA_INIT=
  lua5.1

I get a "pure" Lua5.1.

If I do

  luarocks
  luarocks search lpeg
  luarocks list
  luarocks --verbose --local install lpeg       2>&1 | tee /tmp/olrl
  luarocks --verbose --local install lpeglabel  2>&1 | tee /tmp/olrll
  luarocks list

I install lpeg and lpeglabel in ~/.luarocks/, and luarocks also puts
some files in ~/.cache/luarocks/. These sexp hyperlinks

  # (find-sh "cd ~/.luarocks/ && find * | sort")
  # (find-fline "~/.luarocks/")
  # (find-fline "~/.luarocks/share/lua/5.1/")
  # (find-fline "~/.luarocks/share/lua/5.1/" "re.lua")
  # (find-fline "~/.luarocks/share/lua/5.1/" "relabel.lua")
  # (find-fline "~/.luarocks/lib/lua/5.1/")
  # (find-fline "~/.luarocks/lib/lua/5.1/" "lpeg.so")
  # (find-fline "~/.luarocks/lib/lua/5.1/" "lpeglabel.so")

  # (find-sh "cd ~/.cache/luarocks/ && find * | sort")
  # (find-fline "~/.cache/luarocks/")
  # (find-fline "~/.cache/luarocks/https___luarocks.org/manifest-5.1")

help me inspect these directories and remember where the files are.

If I execute this in a shell

  export LUA_INIT=
  lua5.1
    require "lpeglabel"
    require "relabel"

I get errors, because neither "relabel.lua" nor "lpeglabel.so" are
found. If I run this in a shell,

  luarocks path
  luarocks path | tr "';" "\n\n"

I see that there are two ways to make Lua use these paths. One is:

  export LUA_INIT=
  eval $(luarocks path)
  echo $LUA_PATH
  echo $LUA_CPATH
  lua5.1
    require "lpeglabel"
    require "relabel"

and another is

  export LUA_INIT=
  lua5.1
    home = os.getenv "HOME"
    package.path  = home.."/.luarocks/share/lua/5.1/?.lua;"      .. package.path
    package.path  = home.."/.luarocks/share/lua/5.1/?/init.lua;" .. package.path
    package.cpath = home.."/.luarocks/lib/lua/5.1/?.so;"        .. package.cpath
    require "lpeglabel"
    require "relabel"

so far so good - but I confess that I didn't find easy to figure this
out when I started using rocks several years ago.



2. Understanding a rock
=======================

How do I get the documentation of a rock? Does that documentation
always come with examples? Does the source always come with
documentation and examples? How do I download and unpack the source of
a rock?

I found - by trial and error - that I can do this,

  luarocks
  luarocks list
  luarocks show lpeglabel

  rm -Rv /tmp/lpeglabel/
  mkdir  /tmp/lpeglabel/
  cd     /tmp/lpeglabel/
  luarocks download lpeglabel
  unzip lpeglabel-1.6.0-1.src.rock
  tar -xvzf      v1.6.0-1.tar.gz

  # (find-fline "/tmp/lpeglabel/")
  # (find-fline "/tmp/lpeglabel/lpeglabel-1.6.0-1/")
  # (find-fline "/tmp/lpeglabel/lpeglabel-1.6.0-1/README.md")
  # (find-fline "/tmp/lpeglabel/lpeglabel-1.6.0-1/relabel.lua")
  # (find-fline "/tmp/lpeglabel/lpeglabel-1.6.0-1/examples/")

but I don't have any idea if all rocks can be extracted in a similar
way... my video for the EmacsConf has a part that shows how I have
semi-automated the task of downloading the source of a Debian package
and unpacking and compiling it:

  http://angg.twu.net/emacsconf2019.html ->
    14:45 Demo: the `find-apt-get-source-links' ->
    https://www.youtube.com/watch?v=86yiRG8YJD0&t=885

Can something similar be done for rocks? I don't know - I've tried to
do something like this a few years ago, and 1) I ended up with the
impression that there are several different ways to pack and unpack
rocks, 2) I tried to follow what luarocks do - but telling it to run
in verbose mode didn't make it verbose enough, 3) I tried to add some
prints and calls to repls to luarocks's code and to call its functions
from Lua's default REPL but I didn't get very far, 4) I sent the
following e-mail to the luarocks mailing list,

  https://sourceforge.net/p/luarocks/mailman/message/34636407/

but soon after that I gave up...


  Cheers,
    Eduardo Ochs
    http://angg.twu.net/dednat6.html
    http://angg.twu.net/#eev
    http://angg.twu.net/emacsconf2019.html