swiglib-mkiv.tex /size: 15 Kb    last modification: 2023-12-21 09:43
1% language=us
2
3% author    : Hans Hagen
4% copyright : ConTeXt Development Team
5% license   : Creative Commons Attribution ShareAlike 4.0 International
6% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
7% origin    : the ConTeXt distribution
8%
9% comment   : Because this manual is distributed with TeX distributions it comes with a rather
10%             liberal license. We try to adapt these documents to upgrades in the (sub)systems
11%             that they describe. Using parts of the content otherwise can therefore conflict
12%             with existing functionality and we cannot be held responsible for that. Many of
13%             the manuals contain characteristic graphics and personal notes or examples that
14%             make no sense when used out-of-context.
15%
16% comment   : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
17%             Group journal or otherwise. Thanks to the editors for corrections. Also thanks
18%             to users for testing, feedback and corrections.
19
20\usemodule[art-01,abr-02]
21
22\definecolor
23  [maincolor]
24  [r=.4]
25
26\definecolor
27  [extracolor]
28  [g=.4]
29
30\setupbodyfont
31  [11pt]
32
33\setuptype
34  [color=maincolor]
35
36\setuptyping
37  [color=maincolor]
38
39\definefontsynonym
40  [TitlePageMono]
41  [file:lmmonoproplt10-bold*default]
42
43\setuphead
44  [color=maincolor]
45
46\usesymbols
47  [cc]
48
49\setupinteraction
50  [hidden]
51
52\loadfontgoodies[lm]
53
54\startdocument
55  [metadata:author=Hans Hagen,
56   metadata:title=SwigLib basics,
57   author=Hans Hagen,
58   affiliation=PRAGMA ADE,
59   location=Hasselt NL,
60   title=SwigLib basics,
61   support=www.contextgarden.net,
62   website=www.pragma-ade.nl]
63
64\startluasetups[swiglib]
65    for i=1,640 do
66        context.definedfont { string.formatters["TitlePageMono at %p"](65536*(10+math.random(5))) }
67        context("SwigLib ")
68    end
69    context.removeunwantedspaces()
70\stopluasetups
71
72\startMPpage
73
74StartPage ;
75
76    fill Page enlarged 1cm withcolor \MPcolor{extracolor} ;
77
78    draw textext("\framed[loffset=2pt,roffset=2pt,frame=off,width=\paperwidth,align={normal,paragraph,verytolerant,stretch}]{\luasetup{swiglib}}")
79        xysized (PaperWidth,PaperHeight)
80        shifted center Page
81        withcolor .8white ;
82
83    draw textext.ulft("\definedfont[TitlePageMono]basics")
84        xsized .75PaperWidth
85        shifted lrcorner Page
86        shifted (-1cm,2cm)
87        withcolor \MPcolor{maincolor} ;
88
89  % draw textext.ulft("\definedfont[TitlePageMono]in context mkiv")
90  %     xsized .6PaperWidth
91  %     shifted lrcorner Page
92  %     shifted (-1cm,6cm)
93  %     withcolor \MPcolor{maincolor} ;
94
95StopPage ;
96
97\stopMPpage
98
99\dontcomplain
100
101\startsubject[title=Contents]
102
103\placelist[section][alternative=a]
104
105\stopsubject
106
107\startsection[title=Introduction]
108
109The \SWIGLIB\ project is related to \LUATEX\ and aims as adding portable library
110support to this \TEX\ engine without too much fixed binding. The project does not
111provide \LUA\ code, unless really needed, because it assumes that macro packages
112have different demands. It also fits in the spirit of \TEX\ and \LUA\ to minimize
113the core components.
114
115The technical setup is by Luigi Scarso and documentation about how to build the
116libraries is (will be) part of the \SWIGLIB\ repository. Testing happens with
117help of the \CONTEXT\ (garden) infrastructure. This short document only deals
118with usage in \CONTEXT\ but also covers rather plain usage.
119
120The set of supported libraries in the \SWIGLIB\ subversion trunk is just a subset
121of what is possible and we don't see it as the responsibility of the \LUATEX\
122team to support all that is around. The subset also serves as an example for
123other libraries. We also don't ship wrappers (other that those used in \CONTEXT)
124as this is delegated to the macro packages.
125
126\stopsection
127
128
129\startsection[title=Inside \CONTEXT]
130
131The recommended way to load a library in \CONTEXT\ is by using the
132\type {swiglib} function. This function lives in the global namespace.
133
134\starttyping
135local gm = swiglib("gmwand.core")
136\stoptyping
137
138After this call you have the functionality available in the \type {gm}
139namespace. This way of loading makes \CONTEXT\ aware that such a library
140has been loading and it will report the loaded libraries as part of the
141statistics.
142
143If you want, you can use the more ignorant \type {require} instead but in
144that case you need to be more explicit.
145
146\starttyping
147local gm = require("swiglib.gmwand.core")
148\stoptyping
149
150Here is an example of using such a library (by Luigi):
151
152\startbuffer
153\startluacode
154local gm       = swiglib("gmwand.core")
155local findfile = resolvers.findfile
156
157if not gm then
158    -- no big deal for this manual as we use a system in flux
159    logs.report("swiglib","no swiglib libraries loaded")
160    return
161end
162
163gm.InitializeMagick(".")
164
165local magick_wand  = gm.NewMagickWand()
166local drawing_wand = gm.NewDrawingWand()
167local pixel_wand   = gm.NewPixelWand();
168
169gm.MagickSetSize(magick_wand,800,600)
170gm.MagickReadImage(magick_wand,"xc:gray")
171
172gm.DrawPushGraphicContext(drawing_wand)
173
174gm.DrawSetFillColor(drawing_wand,pixel_wand)
175
176gm.DrawSetFont(drawing_wand,findfile("dejavuserifbold.ttf"))
177gm.DrawSetFontSize(drawing_wand,96)
178gm.DrawAnnotation(drawing_wand,200,200,"ConTeXt 1")
179
180gm.DrawSetFont(drawing_wand,findfile("texgyreschola-bold.otf"))
181gm.DrawSetFontSize(drawing_wand,78)
182gm.DrawAnnotation(drawing_wand,250,300,"ConTeXt 2")
183
184gm.DrawSetFont(drawing_wand,findfile("lmroman10-bold.otf"))
185gm.DrawSetFontSize(drawing_wand,48)
186gm.DrawAnnotation(drawing_wand,300,400,"ConTeXt 3")
187
188gm.DrawPopGraphicContext(drawing_wand)
189
190gm.MagickDrawImage(magick_wand,drawing_wand)
191
192gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.png",1)
193gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.jpg",1)
194gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.pdf",1)
195
196gm.DestroyDrawingWand(drawing_wand)
197gm.DestroyPixelWand(pixel_wand)
198gm.DestroyMagickWand(magick_wand)
199\stopluacode
200\stopbuffer
201
202\typebuffer
203
204\getbuffer
205
206In practice you will probably stay away from manipulating text this way, but it
207illustrates that you can use the regular \CONTEXT\ helpers to locate files.
208
209\startlinecorrection[big]
210    \startcombination[3*1]
211        {\externalfigure[swiglib-mkiv-gm-1.png][width=.3\textwidth]} {png}
212        {\externalfigure[swiglib-mkiv-gm-1.pdf][width=.3\textwidth]} {pdf}
213        {\externalfigure[swiglib-mkiv-gm-1.jpg][width=.3\textwidth]} {jpg}
214    \stopcombination
215\stoplinecorrection
216
217You'd better make sure to use unique filenames for such graphics. Of course a more
218clever mechanism would only run time consuming tasks once for each iteration of a
219document.
220
221\stopsection
222
223\startsection[title=Outside \CONTEXT]
224
225In the \CONTEXT\ distribution we ship some generic macros and code for usage in
226plain \TEX\ but there is no reason why they shouldn't work in other macro packages
227as well. A rather plain example is this:
228
229\starttyping
230\input luatex-swiglib.tex
231
232\directlua {
233    dofile("luatex-swiglib-test.lua")
234}
235
236\pdfximage {luatex-swiglib-test.jpg} \pdfrefximage\pdflastximage
237
238\end
239\stoptyping
240
241Assuming that you made the \type {luatex-plain} format, such a file can be processed using:
242
243\starttyping
244luatex --fmt=luatex=plain luatex-swiglib-test.tex
245\stoptyping
246
247The loaded \LUA\ file \type {luatex-swiglib-test.lua} liike like this:
248
249\starttyping
250local gm = swiglib("gmwand.core")
251
252gm.InitializeMagick(".")
253
254local magick_wand  = gm.NewMagickWand()
255local drawing_wand = gm.NewDrawingWand()
256
257gm.MagickSetSize(magick_wand,800,600)
258gm.MagickReadImage(magick_wand,"xc:red")
259gm.DrawPushGraphicContext(drawing_wand)
260gm.DrawSetFillColor(drawing_wand,gm.NewPixelWand())
261gm.DrawPopGraphicContext(drawing_wand)
262gm.MagickDrawImage(magick_wand,drawing_wand)
263gm.MagickWriteImages(magick_wand,"./luatex-swiglib-test.jpg",1)
264
265gm.DestroyDrawingWand(drawing_wand)
266gm.DestroyMagickWand(magick_wand)
267\stoptyping
268
269Instead of loading a library with the \type {swiglib} function, you can also
270use \type {require}:
271
272\starttyping
273local gm = require("swiglib.gmwand.core")
274\stoptyping
275
276Watch the explicit \type {swiglib} reference. Both methods are equivalent.
277
278\stopsection
279
280\startsection[title={The libraries}]
281
282Most libraries are small but some can be rather large and have additional files.
283This is why we keep them separated. On my system they are collected in the
284platform binary tree:
285
286\starttyping
287e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/gmwand
288e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql
289e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/....
290\stoptyping
291
292One can modulate on this:
293
294\starttyping
295...tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql/core.dll
296...tex/texmf-mswin/bin/lib/luajittex/lua/swiglib/mysql/core.dll
297...tex/texmf-mswin/bin/lib/luatex/context/lua/swiglib/mysql/core.dll
298\stoptyping
299
300are all valid. When versions are used you can provide an additional argument to the
301\type {swiglib} loader:
302
303\starttyping
304tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql/5.6/core.dll
305\stoptyping
306
307This works with:
308
309\starttyping
310local mysql = swiglib("mysql.core","5.6")
311\stoptyping
312
313as well as:
314
315\starttyping
316local mysql = swiglib("mysql.core")
317\stoptyping
318
319It is hard to predict how operating systems look up libraries and especially
320nested loads, but as long as the root of the \type {swiglib} path is known to the
321file search routine. We've kept the main conditions for success simple: the core
322library is called \type {core.dll} or \type {core.so}. Each library has an
323(automatically called) initialize function named \type {luaopen_core}. There is no
324reason why (sym)links from the \type {swiglib} path to someplace else shouldn't
325work.
326
327In \type {texmfcnf.lua} you will find an entry like:
328
329\starttyping
330CLUAINPUTS = ".;$SELFAUTOLOC/lib/{$engine/context,$engine}/lua//"
331\stoptyping
332
333Which in practice boils down to a search for \type {luatex} or \type {luajittex}
334specific libraries. When both binaries are compatible and there are no \type
335{luajittex} binaries, the regular \type {luatex} libraries will be used.
336
337The \type {swiglib} loader function mentioned in previous sections load libraries
338in a special way: it changes dir to the specific path and then loads the library
339in the usual way. After that it returns to the path where it started out. After
340this, when the library needs additional libraries (and for instance graphicmagick
341needs a lot of them) it will first look on its own path (which is remembered).
342
343The \MKIV\ lookups are somewhat more robust in the sense that they first check
344for matches on engine specific paths. This comes in handy when the search
345patterns are too generic and one can match on for instance \type {luajittex}
346while \type {luatex} is used.
347
348\stopsection
349
350\startsection[title=Compiling]
351
352Normally you will take the binaries from the \CONTEXT\ garden but if you ever want
353to compile yourself, it's not that hard to do. For \LINUX\ you need to install the
354compilers:
355
356\starttyping
357apt-get install gcc
358apt-get install g++
359\stoptyping
360
361Then you need to make sure you have a copy of the \LUATEX\ sources (you need to use
362your own paths):
363
364\starttyping
365cd /data
366svn checkout https://foundry.supelec.fr/svn/luatex/trunk luatex-trunk
367\stoptyping
368
369or update with:
370
371\starttyping
372cd /data
373svn update luatex-trunk
374\stoptyping
375
376and then export with:
377
378\starttyping
379cd /data
380svn export --force /data/luatex-trunk /data/luatex-trunk-export
381\stoptyping
382
383We go to the export directory and compile \LUATEX:
384
385\starttyping
386cd /data/luatex-trunk-export
387./build.sh --jit
388\stoptyping
389
390The binaries are already stripped (i.e.\ symbols get removed) which makes them
391much smaller.
392
393% strip -s /data/luatex-trunk-export/build/texk/web2c/luatex
394% strip -s /data/luatex-trunk-export/build/texk/web2c/luajittex
395
396\starttyping
397cp data/luatex/luatex-trunk-export/build/texk/web2c/luatex \
398    /data/context/tex/texmf-linux-64/bin
399cp data/luatex/luatex-trunk-export/build/texk/web2c/luajittex \
400    /data/context/tex/texmf-linux-64/bin
401\stoptyping
402
403The native windows binaries are kept very up|-|to|-|date but you can cross compile
404your own if needed. You need to make sure that the cross compiler is installed.
405
406\starttyping
407apt-get install gcc-mingw-w64-x86-64
408apt-get install g++-mingw-w64-x86-64
409apt-get install binutils-mingw-w64
410\stoptyping
411
412Given that you have exported the sources you can now run:
413
414\starttyping
415./build.sh --jit --mingw64
416\stoptyping
417
418Of course we assume a recent \LINUX\ installation here but on \WINDOWS\ you can
419the \quote {\LINUX\ subsystem for \WINDOWS} too. The files can be found in a dedicated
420build directory:
421
422% strip -s /data/luatex-trunk-export/build-windows64/texk/web2c/luatex.exe
423% strip -s /data/luatex-trunk-export/build-windows64/texk/web2c/luajittex.exe
424
425\starttyping
426cp data/luatex/luatex-trunk-export/build-windows64/texk/web2c/luatex.exe \
427    /data/context/tex/tex-context/tex/texmf-linux-64/bin
428cp data/luatex/luatex-trunk-export/build-windows64/texk/web2c/luajittex.exe \
429    /data/context/tex/tex-context/tex/texmf-linux-64/bin
430\stoptyping
431
432You need to wipe out old traces of binaries, because these can confuse the \type {mtxrun}
433stub that checks for them, so we do:
434
435\starttyping
436rm /data/context/tex/tex-context/tex/texmf-win64/bin/luajittex.dll
437rm /data/context/tex/tex-context/tex/texmf-win64/bin/luatex.dll
438\stoptyping
439
440The libraries are compiled in a similar way. This time we get the sources from another
441repository:
442
443\starttyping
444cd /data
445svn checkout https://foundry.supelec.fr/svn/swiglib/trunk swiglib-trunk
446\stoptyping
447
448or update with:
449
450\starttyping
451cd /data
452svn update swiglib-trunk
453\stoptyping
454
455and then export with:
456
457\starttyping
458cd /data
459svn export --force /data/swiglib-trunk /data/swiglib-trunk-export
460\stoptyping
461
462This time you need to be quite explicit with respect to the libraries you want to
463compile :
464
465\starttyping
466cd /data/swiglib-trunk-export
467./build.sh --library=helpers --version=1.0.3
468\stoptyping
469
470You can save yourself some work with:
471
472\starttyping
473mtxrun --script --svnroot=/data/swiglib-trunk-export --make
474\stoptyping
475
476which will create a shell script \type {swiglib-make.sh} with commands that make
477all available libraries. After running that script you can update your tree
478with:
479
480\starttyping
481mtxrun --script --svnroot=/data/swiglib-trunk-export --update
482\stoptyping
483
484For \WINDOWS\ a similar route is followed but first you need to make sure that
485your binaries are able to deal with shared libraries:
486
487\starttyping
488./build-shared.sh --jit --mingw64 --shared
489\stoptyping
490
491Compiling is done as with \LINUX\ but you need to provide the \type {--mingw64}
492flag. Copying is done with:
493
494\starttyping
495cp /data/luatex/luatex-trunk-export/build-windows64-shared\
496    /texk/web2c/.libs/luatex.exe /data/context/tex/texmf-win64/bin
497cp /data/luatex/luatex-trunk-export/build-windows64-shared\
498    /texk/web2c/.libs/luajittex.exe /data/context/tex/texmf-win64/bin
499
500cp /data/luatex/luatex-trunk-export/build-windows64-shared\
501    /libs/lua*/.libs/texlua*dll /data/context/tex/texmf-win64/bin
502cp /data/luatex/luatex-trunk-export/build-windows64-shared\
503    /libs/luajit/.libs/texluajit*dll /data/context/tex/texmf-win64/bin
504cp /data/luatex/luatex-trunk-export/build-windows64-shared\
505    /texk/kpathsea/.libs/libkpathsea*dll /data/context/tex/texmf-win64/bin
506
507rm /data/context/tex/texmf-win64/bin/luajittex.dll
508rm /data/context/tex/texmf-win64/bin/luatex.dll
509\stoptyping
510
511If you're recompiling \type {--make} can save you some time. If your machine can
512handle it \type {--parallel} can speed up the process.
513
514\stopsection
515
516\startsection[title=Colofon]
517
518\starttabulate[|B|p|]
519\NC author    \NC \documentvariable{author}, \documentvariable{affiliation}, \documentvariable{location} \NC \NR
520\NC version   \NC \currentdate \NC \NR
521\NC website   \NC \documentvariable{website} \endash\ \documentvariable{support} \NC \NR
522\NC comment   \NC the swiglib infrastructure is implemented by Luigi Scarso \NC \NR
523\stoptabulate
524
525\stopsection
526
527\stopdocument
528