Principle
texrocks is a lua library to provide a fake texlua/luatex. It does two things:
- set correct environment variables
- use correct command line arguments to call luahbtex
Introduction
For example, you create a virtual environment named my-thesis:
lx new my-thesis cd my-thesis lx add your-needed-luatex-package1 you-loved-luatex-package2 "$EDITOR" main.tex
If you build it directly:
luahbtex main.tex
It will fail, because luatex doesn't know where is
your-needed-luatex-package1.sty in \usepackage{your-needed-luatex-package1}
and your-needed-luatex-package1.lua in \directlua{require"your-needed-luatex-package1"}.
So you try:
lx lua --lua=luahbtex -- main.tex # or lx shell luahbtex main.tex
lx will add lua paths of your-needed-luatex-package1 and
you-loved-luatex-package2 to $LUA_PATH and $CLUA_PATH.
lua recognize these variables to set package.path and package.cpath.
Any require"package_name" will search package_name.lua in package.path and
package.cpath.
However, luahbtex is not a standard lua. It recognizes $LUAINPUTS and
$CLUAINPUTS for lua files. So we must modify package.path and
package.cpath to get them. And luatex recognize $TEXINPUTS for tex files.
Notice we install tex files in the same directory of lua files, so we also can
get them. Font files are similar.
So we create a lua wrapper named luatex to do this work. it calls
os.setenv() to set correct environment variables to make luahbtex work:
luatex main.tex
If you don't like virtual environment, just use lx install to replace lx add.
These packages will be installed to system globally.
lx install your-needed-luatex-package1 you-loved-luatex-package2
It is advised that add lux.lock to VCS to keep reproducible of your TeX
documents.
Related Projects
Except environment variables, TeX compilers also read a config file:
texmf.cnf:
% comment VAR = XXX
is equal to shell's:
VAR=XXX texlua
or lua's:
os.setenv("VAR", "XXX") io.popen("texlua")
Many TeX distributions, like TeX Live and MikTeX, don't use environment
variables. They use texmf.cnf to declare a fixed path, like
/usr/share/texmf. It is hard to support virtual environments.
And these huge TeX distributions usually provide many TeX compilers: pdfTeX, XeTeX, LuaTeX, ... and many TeX tools written in lua/perl/python/java/... We only provide luahbtex and those TeX tools written in lua.