path: root/doc/context/sources/general/manuals/swiglib/swiglib-mkiv.tex

% language=uk

% author    : Hans Hagen
% copyright : PRAGMA ADE & ConTeXt Development Team
% license   : Creative Commons Attribution ShareAlike 4.0 International
% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
% origin    : the ConTeXt distribution
%
% comment   : Because this manual is distributed with TeX distributions it comes with a rather
%             liberal license. We try to adapt these documents to upgrades in the (sub)systems
%             that they describe. Using parts of the content otherwise can therefore conflict
%             with existing functionality and we cannot be held responsible for that. Many of
%             the manuals contain characteristic graphics and personal notes or examples that
%             make no sense when used out-of-context.
%
% comment   : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
%             Group journal or otherwise. Thanks to the editors for corrections. Also thanks
%             to users for testing, feedback and corrections.

\usemodule[art-01,abr-02]

\definecolor
  [maincolor]
  [r=.4]

\definecolor
  [extracolor]
  [g=.4]

\setupbodyfont
  [11pt]

\setuptype
  [color=maincolor]

\setuptyping
  [color=maincolor]

\definefontsynonym
  [TitlePageMono]
  [file:lmmonoproplt10-bold*default]

\setuphead
  [color=maincolor]

\usesymbols
  [cc]

\setupinteraction
  [hidden]

\loadfontgoodies[lm]

\startdocument
  [metadata:author=Hans Hagen,
   metadata:title=SwigLib basics,
   author=Hans Hagen,
   affiliation=PRAGMA ADE,
   location=Hasselt NL,
   title=SwigLib basics,
   support=www.contextgarden.net,
   website=www.pragma-ade.nl]

\startluasetups[swiglib]
    for i=1,640 do
        context.definedfont { string.formatters["TitlePageMono at %p"](65536*(10+math.random(5))) }
        context("SwigLib ")
    end
    context.removeunwantedspaces()
\stopluasetups

\startMPpage

StartPage ;

    fill Page enlarged 1cm withcolor \MPcolor{extracolor} ;

    draw textext("\framed[loffset=2pt,roffset=2pt,frame=off,width=\paperwidth,align={normal,paragraph,verytolerant,stretch}]{\luasetup{swiglib}}")
        xysized (PaperWidth,PaperHeight)
        shifted center Page
        withcolor .8white ;

    draw textext.ulft("\definedfont[TitlePageMono]basics")
        xsized .75PaperWidth
        shifted lrcorner Page
        shifted (-1cm,2cm)
        withcolor \MPcolor{maincolor} ;

  % draw textext.ulft("\definedfont[TitlePageMono]in context mkiv")
  %     xsized .6PaperWidth
  %     shifted lrcorner Page
  %     shifted (-1cm,6cm)
  %     withcolor \MPcolor{maincolor} ;

StopPage ;

\stopMPpage

\dontcomplain

\startsubject[title=Contents]

\placelist[section][alternative=a]

\stopsubject

\startsection[title=Introduction]

The \SWIGLIB\ project is related to \LUATEX\ and aims as adding portable library
support to this \TEX\ engine without too much fixed binding. The project does not
provide \LUA\ code, unless really needed, because it assumes that macro packages
have different demands. It also fits in the spirit of \TEX\ and \LUA\ to minimize
the core components.

The technical setup is by Luigi Scarso and documentation about how to build the
libraries is (will be) part of the \SWIGLIB\ repository. Testing happens with
help of the \CONTEXT\ (garden) infrastructure. This short document only deals
with usage in \CONTEXT\ but also covers rather plain usage.

The set of supported libraries in the \SWIGLIB\ subversion trunk is just a subset
of what is possible and we don't see it as the responsibility of the \LUATEX\
team to support all that is around. The subset also serves as an example for
other libraries. We also don't ship wrappers (other that those used in \CONTEXT)
as this is delegated to the macro packages.

\stopsection


\startsection[title=Inside \CONTEXT]

The recommended way to load a library in \CONTEXT\ is by using the
\type {swiglib} function. This function lives in the global namespace.

\starttyping
local gm = swiglib("gmwand.core")
\stoptyping

After this call you have the functionality available in the \type {gm}
namespace. This way of loading makes \CONTEXT\ aware that such a library
has been loading and it will report the loaded libraries as part of the
statistics.

If you want, you can use the more ignorant \type {require} instead but in
that case you need to be more explicit.

\starttyping
local gm = require("swiglib.gmwand.core")
\stoptyping

Here is an example of using such a library (by Luigi):

\startbuffer
\startluacode
local gm       = swiglib("gmwand.core")
local findfile = resolvers.findfile

if not gm then
    -- no big deal for this manual as we use a system in flux
    logs.report("swiglib","no swiglib libraries loaded")
    return
end

gm.InitializeMagick(".")

local magick_wand  = gm.NewMagickWand()
local drawing_wand = gm.NewDrawingWand()
local pixel_wand   = gm.NewPixelWand();

gm.MagickSetSize(magick_wand,800,600)
gm.MagickReadImage(magick_wand,"xc:gray")

gm.DrawPushGraphicContext(drawing_wand)

gm.DrawSetFillColor(drawing_wand,pixel_wand)

gm.DrawSetFont(drawing_wand,findfile("dejavuserifbold.ttf"))
gm.DrawSetFontSize(drawing_wand,96)
gm.DrawAnnotation(drawing_wand,200,200,"ConTeXt 1")

gm.DrawSetFont(drawing_wand,findfile("texgyreschola-bold.otf"))
gm.DrawSetFontSize(drawing_wand,78)
gm.DrawAnnotation(drawing_wand,250,300,"ConTeXt 2")

gm.DrawSetFont(drawing_wand,findfile("lmroman10-bold.otf"))
gm.DrawSetFontSize(drawing_wand,48)
gm.DrawAnnotation(drawing_wand,300,400,"ConTeXt 3")

gm.DrawPopGraphicContext(drawing_wand)

gm.MagickDrawImage(magick_wand,drawing_wand)

gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.png",1)
gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.jpg",1)
gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.pdf",1)

gm.DestroyDrawingWand(drawing_wand)
gm.DestroyPixelWand(pixel_wand)
gm.DestroyMagickWand(magick_wand)
\stopluacode
\stopbuffer

\typebuffer

\getbuffer

In practice you will probably stay away from manipulating text this way, but it
illustrates that you can use the regular \CONTEXT\ helpers to locate files.

\startlinecorrection[big]
    \startcombination[3*1]
        {\externalfigure[swiglib-mkiv-gm-1.png][width=.3\textwidth]} {png}
        {\externalfigure[swiglib-mkiv-gm-1.pdf][width=.3\textwidth]} {pdf}
        {\externalfigure[swiglib-mkiv-gm-1.jpg][width=.3\textwidth]} {jpg}
    \stopcombination
\stoplinecorrection

You'd better make sure to use unique filenames for such graphics. Of course a more
clever mechanism would only run time consuming tasks once for each iteration of a
document.

\stopsection

\startsection[title=Outside \CONTEXT]

In the \CONTEXT\ distribution we ship some generic macros and code for usage in
plain \TEX\ but there is no reason why they shouldn't work in other macro packages
as well. A rather plain example is this:

\starttyping
\input luatex-swiglib.tex

\directlua {
    dofile("luatex-swiglib-test.lua")
}

\pdfximage {luatex-swiglib-test.jpg} \pdfrefximage\pdflastximage

\end
\stoptyping

Assuming that you made the \type {luatex-plain} format, such a file can be processed using:

\starttyping
luatex --fmt=luatex=plain luatex-swiglib-test.tex
\stoptyping

The loaded \LUA\ file \type {luatex-swiglib-test.lua} liike like this:

\starttyping
local gm = swiglib("gmwand.core")

gm.InitializeMagick(".")

local magick_wand  = gm.NewMagickWand()
local drawing_wand = gm.NewDrawingWand()

gm.MagickSetSize(magick_wand,800,600)
gm.MagickReadImage(magick_wand,"xc:red")
gm.DrawPushGraphicContext(drawing_wand)
gm.DrawSetFillColor(drawing_wand,gm.NewPixelWand())
gm.DrawPopGraphicContext(drawing_wand)
gm.MagickDrawImage(magick_wand,drawing_wand)
gm.MagickWriteImages(magick_wand,"./luatex-swiglib-test.jpg",1)

gm.DestroyDrawingWand(drawing_wand)
gm.DestroyMagickWand(magick_wand)
\stoptyping

Instead of loading a library with the \type {swiglib} function, you can also
use \type {require}:

\starttyping
local gm = require("swiglib.gmwand.core")
\stoptyping

Watch the explicit \type {swiglib} reference. Both methods are equivalent.

\stopsection

\startsection[title={The libraries}]

Most libraries are small but some can be rather large and have additional files.
This is why we keep them separated. On my system they are collected in the
platform binary tree:

\starttyping
e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/gmwand
e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql
e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/....
\stoptyping

One can modulate on this:

\starttyping
...tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql/core.dll
...tex/texmf-mswin/bin/lib/luajittex/lua/swiglib/mysql/core.dll
...tex/texmf-mswin/bin/lib/luatex/context/lua/swiglib/mysql/core.dll
\stoptyping

are all valid. When versions are used you can provide an additional argument to the
\type {swiglib} loader:

\starttyping
tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql/5.6/core.dll
\stoptyping

This works with:

\starttyping
local mysql = swiglib("mysql.core","5.6")
\stoptyping

as well as:

\starttyping
local mysql = swiglib("mysql.core")
\stoptyping

It is hard to predict how operating systems look up libraries and especially
nested loads, but as long as the root of the \type {swiglib} path is known to the
file search routine. We've kept the main conditions for success simple: the core
library is called \type {core.dll} or \type {core.so}. Each library has an
(automatically called) initialize function named \type {luaopen_core}. There is no
reason why (sym)links from the \type {swiglib} path to someplace else shouldn't
work.

In \type {texmfcnf.lua} you will find an entry like:

\starttyping
CLUAINPUTS = ".;$SELFAUTOLOC/lib/{$engine/context,$engine}/lua//"
\stoptyping

Which in practice boils down to a search for \type {luatex} or \type {luajittex}
specific libraries. When both binaries are compatible and there are no \type
{luajittex} binaries, the regular \type {luatex} libraries will be used.

The \type {swiglib} loader function mentioned in previous sections load libraries
in a special way: it changes dir to the specific path and then loads the library
in the usual way. After that it returns to the path where it started out. After
this, when the library needs additional libraries (and for instance graphicmagick
needs a lot of them) it will first look on its own path (which is remembered).

The \MKIV\ lookups are somewhat more robust in the sense that they first check
for matches on engine specific paths. This comes in handy when the search
patterns are too generic and one can match on for instance \type {luajittex}
while \type {luatex} is used.

\stopsection

\startsection[title=Compiling]

Normally you will take the binaries from the \CONTEXT\ garden but if you ever want
to compile yourself, it's not that hard to do. For \LINUX\ you need to install the
compilers:

\starttyping
apt-get install gcc
apt-get install g++
\stoptyping

Then you need to make sure you have a copy of the \LUATEX\ sources (you need to use
your own paths):

\starttyping
cd /data
svn checkout https://foundry.supelec.fr/svn/luatex/trunk luatex-trunk
\stoptyping

or update with:

\starttyping
cd /data
svn update luatex-trunk
\stoptyping

and then export with:

\starttyping
cd /data
svn export --force /data/luatex-trunk /data/luatex-trunk-export
\stoptyping

We go to the export directory and compile \LUATEX:

\starttyping
cd /data/luatex-trunk-export
./build.sh --jit
\stoptyping

The binaries are already stripped (i.e.\ symbols get removed) which makes them
much smaller.

% strip -s /data/luatex-trunk-export/build/texk/web2c/luatex
% strip -s /data/luatex-trunk-export/build/texk/web2c/luajittex

\starttyping
cp data/luatex/luatex-trunk-export/build/texk/web2c/luatex \
    /data/context/tex/texmf-linux-64/bin
cp data/luatex/luatex-trunk-export/build/texk/web2c/luajittex \
    /data/context/tex/texmf-linux-64/bin
\stoptyping

The native windows binaries are kept very up|-|to|-|date but you can cross compile
your own if needed. You need to make sure that the cross compiler is installed.

\starttyping
apt-get install gcc-mingw-w64-x86-64
apt-get install g++-mingw-w64-x86-64
apt-get install binutils-mingw-w64
\stoptyping

Given that you have exported the sources you can now run:

\starttyping
./build.sh --jit --mingw64
\stoptyping

Of course we assume a recent \LINUX\ installation here but on \WINDOWS\ you can
the \quote {\LINUX\ subsystem for \WINDOWS} too. The files can be found in a dedicated
build directory:

% strip -s /data/luatex-trunk-export/build-windows64/texk/web2c/luatex.exe
% strip -s /data/luatex-trunk-export/build-windows64/texk/web2c/luajittex.exe

\starttyping
cp data/luatex/luatex-trunk-export/build-windows64/texk/web2c/luatex.exe \
    /data/context/tex/tex-context/tex/texmf-linux-64/bin
cp data/luatex/luatex-trunk-export/build-windows64/texk/web2c/luajittex.exe \
    /data/context/tex/tex-context/tex/texmf-linux-64/bin
\stoptyping

You need to wipe out old traces of binaries, because these can confuse the \type {mtxrun}
stub that checks for them, so we do:

\starttyping
rm /data/context/tex/tex-context/tex/texmf-win64/bin/luajittex.dll
rm /data/context/tex/tex-context/tex/texmf-win64/bin/luatex.dll
\stoptyping

The libraries are compiled in a similar way. This time we get the sources from another
repository:

\starttyping
cd /data
svn checkout https://foundry.supelec.fr/svn/swiglib/trunk swiglib-trunk
\stoptyping

or update with:

\starttyping
cd /data
svn update swiglib-trunk
\stoptyping

and then export with:

\starttyping
cd /data
svn export --force /data/swiglib-trunk /data/swiglib-trunk-export
\stoptyping

This time you need to be quite explicit with respect to the libraries you want to
compile :

\starttyping
cd /data/swiglib-trunk-export
./build.sh --library=helpers --version=1.0.3
\stoptyping

You can save yourself some work with:

\starttyping
mtxrun --script --svnroot=/data/swiglib-trunk-export --make
\stoptyping

which will create a shell script \type {swiglib-make.sh} with commands that make
all available libraries. After running that script you can update your tree
with:

\starttyping
mtxrun --script --svnroot=/data/swiglib-trunk-export --update
\stoptyping

For \WINDOWS\ a similar route is followed but first you need to make sure that
your binaries are able to deal with shared libraries:

\starttyping
./build-shared.sh --jit --mingw64 --shared
\stoptyping

Compiling is done as with \LINUX\ but you need to provide the \type {--mingw64}
flag. Copying is done with:

\starttyping
cp /data/luatex/luatex-trunk-export/build-windows64-shared\
    /texk/web2c/.libs/luatex.exe /data/context/tex/texmf-win64/bin
cp /data/luatex/luatex-trunk-export/build-windows64-shared\
    /texk/web2c/.libs/luajittex.exe /data/context/tex/texmf-win64/bin

cp /data/luatex/luatex-trunk-export/build-windows64-shared\
    /libs/lua*/.libs/texlua*dll /data/context/tex/texmf-win64/bin
cp /data/luatex/luatex-trunk-export/build-windows64-shared\
    /libs/luajit/.libs/texluajit*dll /data/context/tex/texmf-win64/bin
cp /data/luatex/luatex-trunk-export/build-windows64-shared\
    /texk/kpathsea/.libs/libkpathsea*dll /data/context/tex/texmf-win64/bin

rm /data/context/tex/texmf-win64/bin/luajittex.dll
rm /data/context/tex/texmf-win64/bin/luatex.dll
\stoptyping

If you're recompiling \type {--make} can save you some time. If your machine can
handle it \type {--parallel} can speed up the process.

\stopsection

\startsection[title=Colofon]

\starttabulate[|B|p|]
\NC author    \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR
\NC version   \NC \currentdate \NC \NR
\NC website   \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR
\NC comment   \NC the swiglib infrastructure is implemented by Luigi Scarso \NC \NR
\stoptabulate

\stopsection

\stopdocument