Write a How-to guide about loading modules in the Tarantool application

[andreyaksenov]

Product: Tarantool
Root document:

• https://www.tarantool.io/en/doc/latest/reference/reference_lua/other/
• https://www.tarantool.io/en/doc/latest/how-to/app/creating_app/modules_rocks_and_applications/

SME: @ Totktonada

Details

Currently, information about loading modules is placed mostly in the API descriptions and looks a bit fragmented.
It might be convenient to make the How-to guide (in Modules, rocks and applications?) that has the common context for all the API members and describes specifics of loading modules in the Tarantool app.

• RFC

• More info about loaders:

$ cat source/loaders.rst 
.. vim: ts=4 sw=4 et

Loaders
=======

Introduction
------------

This section describes a machinery that works behind the `require()` call in Lua.

It partially repeats Lua 5.1 Reference Manual
(https://www.lua.org/manual/5.1/manual.html#5.3), but adds LuaJIT and Tarantool
specifics and describes everything from a point of a developer (how things are
implemented rather than how they bevahe).

require()
---------

The source of the function is in ``third_party/luajit/src/lib_package.c``, the
function is called ``lj_cf_package_require``.

There is a ``_LOADED`` table in the Lua registry, it holds already loaded
modules. This table is also accessible as ``package.loaded``.

``require()`` works basically this way:

1. Look at ``_LOADED[module_name]``. If it exists, return it.
2. Otherwise, for each loader in ``package.loaders``:
   * Call ``package.loaders[i](module_name)`` XXX

package.loaders
---------------



``src/lua/init.lua``

.. code-block:: lua
    -- loader_preload 1
    table.insert(package.loaders, 2, gen_loader_func(search_lua, load_lua))
    table.insert(package.loaders, 3, gen_loader_func(search_lib, load_lib))
    table.insert(package.loaders, 4, gen_loader_func(search_rocks_lua, load_lua))
    table.insert(package.loaders, 5, gen_loader_func(search_rocks_lib, load_lib))
    -- package.path   6
    -- package.cpath  7
    -- croot          8

package.path and package.cpath
------------------------------

tarantool_lua_setpaths(), MODULE_LUAPATH, MODULE_LIBPATH

package.searchpath() and package.search()
-----------------------------------------

``package.searchpath`` comes from Lua 5.2 (implemented in LuaJIT 2.1).

https://www.lua.org/manual/5.2/manual.html#pdf-package.searchpath

``package.search`` is introduced by tarantool.

package.searchroot() and package.setsearchroot()
------------------------------------------------

https://github.com/tarantool/tarantool/pull/4193

debug.__file__ and debug.__dir__
--------------------------------

https://github.com/tarantool/tarantool/pull/4260

More insane
-----------

Moonscript sets ``package.loaders[2]`` when you call ``require "moonscript"``.

https://github.com/tarantool/tarantool/issues/3136

How luarocks usually works?