{"id":489,"date":"2011-01-20T23:07:15","date_gmt":"2011-01-20T23:07:15","guid":{"rendered":"http:\/\/www.readytext.co.uk\/?p=489"},"modified":"2013-11-28T08:59:31","modified_gmt":"2013-11-28T08:59:31","slug":"extending-luatex-on-windows-with-plugins-dlls","status":"publish","type":"post","link":"https:\/\/www.readytext.co.uk\/?p=489","title":{"rendered":"Extending LuaTeX on Windows with plugins (DLLs)"},"content":{"rendered":"

About 6 months ago I came across an article<\/a> and presentation<\/a> by Luigi Scarso called “LuaTEX lunatic”, with a subtitle And Now for Something Completely Different<\/em>. And different it was because, for me, it opened my eyes to some of the real<\/em> power of LuaTeX: extending it via C\/C++ libraries. Luigi’s truly excellent paper is Linux-centric but the general ideas hold true for any platform, including Windows. <\/p>\n

The power of Lua’s require(...)<\/code> function<\/h3>\n

The Lua language provides a function called require(...)<\/a><\/code> which allows you to load and run libraries – that can be written in pure Lua or the Lua C API<\/a>. Refer to the Libraries And Bindings<\/a> page on lua-users.org for more details. <\/p>\n

\nUsing require(...)<\/code> with LuaTeX: a primer<\/strong>
\nOnce again, the secret ingredient is the LuaTeX command \\directlua{...}<\/code> which, as discussed in previous posts, lets you run Lua code from within documents you process with LuaTeX. Suppose you have a DLL which you, or someone else, have written with a Lua binding and you want to use it with LuaTeX. How do you do it?<\/p>\n

Firstly, within texmf.cnf<\/code> you need to define a variable called CLUAINPUTS<\/code>, which tells Kpathsea where to search for files with extension .dll and .so (s<\/strong>hared o<\/strong>bject file, on Linux). For example, in my hand-rolled texmf.cnf<\/code> the setting is<\/p>\n

CLUAINPUTS=$TEXMF\/dlls<\/code><\/p>\n

The LuaTeX Reference Manual notes the default setting of<\/p>\n

CLUAINPUTS=.:$SELFAUTOLOC\/lib\/{$progname,$engine,}\/lua\/\/<\/code>\n<\/p><\/blockquote>\n

World’s most pointless DLL code?<\/h3>\n

Just for completeness, and by way of an ultra-minimal example, here is probably the world’s most pointless C code for a DLL that you can call from LuaTeX. To compile this you will, of course, need to ensure that you link to the Lua libraries (note that I use Microsoft’s Visual Studio for this)<\/p>\n

\r\n#include ‹windows.h›\r\n#include \"lauxlib.h\"\r\n#include \"lua.h\"\r\n\r\n#define LUA_LIB   int __declspec(dllexport) \r\n\r\nstatic int helloluatex_greetings(lua_State *L){\r\n\r\n\tprintf(\"Hello to LuaTeX from the world's smallest DLL!\");\r\n\treturn 0;\r\n}\r\n\r\n\r\nstatic const luaL_reg helloluatex[] = {\r\n{\"greetings\", helloluatex_greetings},\r\n\t{NULL, NULL}\r\n};\r\n\r\nLUA_LIB luaopen_helloluatex (lua_State *L) {\r\n  luaL_register(L, \"helloluatex\", helloluatex);\r\n  return 1;\r\n}\r\n<\/pre>\n
<\/code><\/p>\n
You need to compile the above C code into a DLL called helloluatex.dll<\/code> and copy it to the directory or path pointed to by CLUAINPUTS<\/code>.<\/p>\n
LuaTeX code to use our new DLL<\/h3>\n
Here is a minimal (LaTeX) file to load helloluatex.dll<\/code> and call the greetings<\/code> function we defined via the Lua C API. We'll call the file dlltest.tex<\/code>.<\/p>\n
\\documentclass[11pt,twoside]{article}\r\n\\begin{document}\r\n\\pagestyle{empty}\r\n\\directlua{\r\n\r\n\trequire(\"helloluatex\")\r\n\thelloluatex.greetings()\r\n}\r\n\\end{document}<\/code><\/pre>\n
Running this as luatex  --fmt=lualatex dlltest.tex<\/code> gives the output<\/p>\n
This is LuaTeX, Version beta-0.65.0-2010122301\r\n(c:\/...\/dlltest.tex\r\nLaTeX2e <2009\/09\/24>\r\n(c:\/...\/formats\/pdflatex\/base\/article.cls\r\nDocument Class: article 2007\/10\/19 v1.4h Standard LaTeX document class\r\n(c:\/...\/formats\/pdflatex\/base\/size11.clo))\r\nNo file dlltest.aux.\r\nHello to LuaTeX from the world's smallest DLL!<\/strong>(.\/dlltest.aux) )\r\n 262 words of node memory still in use:\r\n   2 hlist, 1 vlist, 1 rule, 2 glue, 39 glue_spec, 2 write nodes\r\n   avail lists: 2:12,3:1,6:3,7:1,9:1\r\nNo pages of output.\r\nTranscript written on dlltest.log.<\/code><\/pre>\n
Note that you see Hello to LuaTeX from the world's smallest DLL!<\/strong><\/code> printed out to the DOS window. <\/p>\n
This is, of course, a rather simple example so I'll try to provide more useful examples over the coming weeks and months. I have integrated a number of libraries into LuaTeX, including FreeType and GhostScript, and many others, so I'll try to cover some of these wonderful C libraries as time permits. Stay tuned!<\/p>\n","protected":false},"excerpt":{"rendered":"
About 6 months ago I came across an article and presentation by Luigi Scarso called “LuaTEX lunatic”, with a subtitle And Now for Something Completely Different. And different it was because, for me, it opened my eyes to some of the real power of LuaTeX: extending it via C\/C++ libraries. Luigi’s truly excellent paper is […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[28,9,3],"tags":[],"class_list":["post-489","post","type-post","status-publish","format-standard","hentry","category-c-programming-miscellaneous","category-luatex-c-code-windows-dlls","category-luatex"],"blocksy_meta":[],"_links":{"self":[{"href":"https:\/\/www.readytext.co.uk\/index.php?rest_route=\/wp\/v2\/posts\/489","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.readytext.co.uk\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.readytext.co.uk\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.readytext.co.uk\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.readytext.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=489"}],"version-history":[{"count":24,"href":"https:\/\/www.readytext.co.uk\/index.php?rest_route=\/wp\/v2\/posts\/489\/revisions"}],"predecessor-version":[{"id":3242,"href":"https:\/\/www.readytext.co.uk\/index.php?rest_route=\/wp\/v2\/posts\/489\/revisions\/3242"}],"wp:attachment":[{"href":"https:\/\/www.readytext.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=489"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.readytext.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=489"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.readytext.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=489"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}