Installation guide
==================
This installation guide focuses on packaging for redistribution. For
the final user, it is recommended to install via LuaRocks or using the
self-installing script; see the [README](README.md) for details.
Digestif has the following dependencies:
* Lua version 5.3 or 5.4
* LPeg (
https://luarocks.org/modules/gvvaughan/lpeg)
* LuaFileSystem (
https://luarocks.org/modules/hisham/luafilesystem)
* cjson (optional,
https://luarocks.org/modules/openresty/lua-cjson)
* LuaZip (optional,
https://luarocks.org/modules/mpeterv/luazip)
If the cjson library is missing, Digestif uses its own LPeg-based JSON
serializer, which is slower but adequate. LuaZip is required only
when placing the data files in a zip archive.
All shell commands and file name references assume that the directory
containing this file is the current directory.
Standard packaging
------------------
For a regular installation of Digestif into, say, `PREFIX=/usr`, copy
the files as follows:
install -Dt $PREFIX/bin bin/digestif
install -Dt $PREFIX/share/lua/$LUA_VERSION digestif
install -Dt $PREFIX/share/digestif data/*.tags
Before doing so, however, consider the following:
1. In order for the tags files to be found, add the following at the
top of the `bin/digestif` script:
require "digestif.config".data_dirs = {"$PREFIX/share/digestif"}
2. Make sure the `package.path` Lua variable includes the directory
into which the `digestif` directory is installed.
3. It is recommended that the `package.path` and `package.cpath` Lua
variables do not include the default relative entries such as
`./?.lua`. This is especially important if any of the optional
dependencies are not installed.
4. If LuaZip is available, the tags files may also be placed in a zip
file:
zip -j data.zip data/*.tags
install -Dt $PREFIX/share/digestif data.zip
In this case, add the following line at the top of `bin/digestif`:
require "digestif.config".data_dirs = {"$PREFIX/share/digestif/data.zip"}
Packaging for a TeX distribution
--------------------------------
For an installation depending only on the `texlua` interpreter from
LuaTeX (which bundles all dependencies except the optional cjson),
create a zip file containing `digestif/*.lua` and `data/*.tags` (no
subdirectories), place it anywhere kpathsearch will find it and use
the `bin/digestif.texlua` executable script. For instance:
zip -j digestif.zip digestif/*.lua data/*.tags
install -Dt $TEXMF/scripts digestif.zip
install bin/digestif.texlua $PREFIX/bin/digestif
Unbundled installation
----------------------
To install Digestif on a directory of its own, say
`PREFIX=/opt/digestif`, copy the `bin`, `data` and `digestif` folders
and add a symlink of the executable script somewhere in the `PATH`.
For instance:
install -Dt $PREFIX bin data digestif
ln -s $PREFIX/bin/digestif /opt/bin/digestif
