diff options
Diffstat (limited to 'lualibs.dtx')
| -rw-r--r-- | lualibs.dtx | 63 |
1 files changed, 60 insertions, 3 deletions
diff --git a/lualibs.dtx b/lualibs.dtx index 2269f66..7393605 100644 --- a/lualibs.dtx +++ b/lualibs.dtx @@ -290,7 +290,8 @@ and the derived file lualibs.lua. % |l-|) together form something close to a standard libary. Most of these are % extensions of an existing namespace, like for instance |l-table.lua| which % adds full-fledged serialization capabilities to the \LUA table library. -% They were imported under the \identifier{lualibs}-prefix. +% They were imported under the \identifier{lualibs}-prefix and are contained +% in the \identifier{basic} collection. % (For a list see table~\ref{tab:basic}.) % % \begin{table}[t] @@ -322,9 +323,11 @@ and the derived file lualibs.lua. % \hrule % \end{table} % -% The second category comprises a selection of files mostly from the -% utilities namespace (|util-|; cf. table~\ref{tab:extended}). +% The \identifier{extended} category comprises a selection of files mostly from +% the utilities namespace (|util-|; cf. table~\ref{tab:extended}). % Their purpose is more specific and at times quite low-level. +% Additionally, the file \fileent{trac-inf.lua} has been included because it is +% essential to some of the code loaded subsequently. % % \begin{table}[t] % \hrule @@ -352,6 +355,60 @@ and the derived file lualibs.lua. % % \section{Packaging} % + By default, \identifier{lualibs} will not load the libraries individually. + Instead, it includes two \emphasis{merged packages} that have been compiled + from the original files. + This is achieved by means of \identifier{mtx-package}, a script for bundling + \LUA code shipped with \CONTEXT. + This concatenates the code of several \LUA files into a single file that is + both easier to distribute and loading (marginally) faster. + \identifier{mtx-package} ensures that the code from each file gets its + own closure and strips newlines and comments, resulting in a smaller payload. + Another package that relies on it heavily is the font loader as contained in + \identifier{luaotfload} and \identifier{luatex-fonts}. + + If \CONTEXT is installed on the system, the merge files can be created + by running: + + \begin{quote}\begin{verbatim} + mtxrun --script package --merge lualibs-basic.lua + mtxrun --script package --merge lualibs-extended.lua + \end{verbatim}\end{quote} + + \noindent + Of course there is a make target for that: + + \begin{quote}\begin{verbatim} + make merge + \end{verbatim}\end{quote} + \noindent + will take care of assembling the packages from the files distributed with + \identifier{lualibs}. + + For this to work, the syntax of the \LUA file needs to be well-formed: + files that should be merged must be included via a function + \verb|loadmodule()|. + It doesn’t matter if the function actually does something; a dummy will + suffice. + Also, the argument to \verb|loadmodule()| must be wrapped in parentheses. + This rule is quite convenient, actually, since it allows excluding files + from the merge while still using \verb|loadmodule()| consistently. + + \begin{quote}\begin{verbatim} + ... + loadmodule("my-lua-file.lua") -- <= will be merged + loadmodule('my-2nd-file.lua') -- <= will be merged + loadmodule "my-3rd-file.lua" -- <= will be ignored + ... + \end{verbatim}\end{quote} + + Note that there is one exception to the packaging: + \fileent{lualibs-util-jsn.lua} cannot be successfully packaged because + it follows a different coding convention, returning a \LUA table on exit. + Therefore, the file is loaded separately as part of the \identifier{extended} + set like any other \LUA module. + +% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % \part{\fileent{lualibs.lua}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |