Using LuaTeX to run tools and utilities installed on Overleaf’s servers
Overleaf’s servers: running and executing software
Overleaf’s powerful servers compile your project in a sandbox based on Docker’s Linux container technology. Every project gets its own sandbox, which ensures that any code we execute as part of compiling the project is isolated from other projects—and this is the first of several layers of protection that we use to compile projects safely. For TeX users, this means you can safely access and use a wealth of tools and utilities contained on our servers—but how?
In this short post we show how to use a Lua script (via LuaTeX) to execute an external program and capture any text that would usually be output to a terminal window. For example, suppose you are interested to convert some DVI files into SVG using the dvisvgm
utility but you can’t recall the various command-line options? Wouldn’t it be nice to quickly typeset a list of them to refresh your memory? If so, read on—but if you prefer to see this in action, hop over to this gallery project example to see how it’s done.
Using LuaTeX to run an external program via a Lua script
Because LuaTeX has the Lua scripting language embedded into the TeX engine it becomes almost trivial to write a short script that not only executes an external program but also captures, and saves to a file, any text which that program would otherwise output to a terminal window. Once that text is saved to a file you can use the verbatim
package to import it into your main TeX document. Here is the entire code needed to do this with LuaTeX:
\documentclass{article} \usepackage{verbatim} \begin{document} \directlua{ function runcommand(cmd) local fout = assert(io.popen(cmd, 'r')) local str = assert(fout:read('*a')) fout:close() return str end local sout=runcommand("dvisvgm --help") local marg = assert(io.open("command.txt","w")) marg:write(sout) marg:flush() marg:close() } \verbatiminput{command.txt} \end{document}
The key line in the above code is local sout=runcommand("dvisvgm --help")
which executes dvisvgm
with the command-line option --help
to instruct dvisvgm
to list all of its command-line options. The help text is captured and saved to a text file called command.txt
.
After the Lua code within \directlua{...}
has finished executing, the content of command.txt
is inserted into the main TeX document using \verbatiminput{command.txt}
. It is important that you insert any captured text as verbatim material because characters such as $, #, \, _, ^
etc. might be present within the imported text.
Feel free to amend the code in runcommand("dvisvgm --help")
and explore executing other programs—such as GhostScript—or any TeX Live software you might be interested to use.