summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPhilipp Gesang <phg42.2a@gmail.com>2013-05-05 13:39:41 +0200
committerPhilipp Gesang <phg42.2a@gmail.com>2013-05-05 13:39:41 +0200
commit8dfefeb13e526992d90673be89cadc733712c1c5 (patch)
tree7634dce888ae97682925985236f13ee355de8bdb
parentc468e4d4933e23565412a982b0b971daf3ef8e39 (diff)
downloadlualibs-8dfefeb13e526992d90673be89cadc733712c1c5.tar.gz
[doc] describe the packaging
-rw-r--r--lualibs.dtx63
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}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%