source: general/prog/lua.xml@ 9ddc81e

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY lua-download-http "https://www.lua.org/ftp/lua-&lua-version;.tar.gz">
  <!ENTITY lua-download-ftp  " ">
  <!ENTITY lua-md5sum        "25a429319dff20dfbfb9956c2b5be911">
  <!ENTITY lua-size          "356 KB">
  <!ENTITY lua-buildsize     "3.8 MB (with Basic tests)">
  <!ENTITY lua-time          "less than 0.1 SBU (with Basic tests)">

  <!ENTITY lua-tests-download-http "https://www.lua.org/tests/lua-&lua-version;-tests.tar.gz">
  <!ENTITY lua-tests-download-ftp  " ">
  <!ENTITY lua-tests-md5sum        "e10a3da28b05d0e8d25ad08b7820c213">
  <!ENTITY lua-tests-size          "134 KB">
]>

<sect1 id="lua" xreflabel="Lua-&lua-version;">
  <?dbhtml filename="lua.html"?>


  <title>Lua-&lua-version;</title>

  <indexterm zone="lua">
    <primary sortas="a-Lua">Lua</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Lua</title>

    <para>
      <application>Lua</application> is a powerful light-weight programming
      language designed for extending applications. It is also frequently used
      as a general-purpose, stand-alone language. <application>Lua</application>
      is implemented as a small library of C functions, written in ANSI C, and
      compiles unmodified in all known platforms. The implementation goals are
      simplicity, efficiency, portability, and low embedding cost. The result is
      a fast language engine with small footprint, making it ideal in embedded
      systems too.
    </para>

    &lfs121_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&lua-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&lua-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &lua-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &lua-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &lua-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &lua-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/lua-&lua-version;-shared_library-1.patch"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Optional Test Suite Download (HTTP): <ulink url="&lua-tests-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Optional Test Suite Download (FTP): <ulink url="&lua-tests-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Optional Test Suite Download MD5 sum: &lua-tests-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Optional Test Suite Download size: &lua-tests-size;
        </para>
      </listitem>
    </itemizedlist>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Lua</title>

    <para>
      Some packages check for the <application>pkg-config</application> file
      for <application>Lua</application>, which is created with:
    </para>

<screen><userinput>cat &gt; lua.pc &lt;&lt; "EOF"
<literal>V=5.4
R=&lua-version;

prefix=/usr
INSTALL_BIN=${prefix}/bin
INSTALL_INC=${prefix}/include
INSTALL_LIB=${prefix}/lib
INSTALL_MAN=${prefix}/share/man/man1
INSTALL_LMOD=${prefix}/share/lua/${V}
INSTALL_CMOD=${prefix}/lib/lua/${V}
exec_prefix=${prefix}
libdir=${exec_prefix}/lib
includedir=${prefix}/include

Name: Lua
Description: An Extensible Extension Language
Version: ${R}
Requires:
Libs: -L${libdir} -llua -lm -ldl
Cflags: -I${includedir}</literal>
EOF</userinput></screen>

    <para>
      Install <application>Lua</application> by running the following
      commands:
    </para>

<screen><userinput>patch -Np1 -i ../lua-&lua-version;-shared_library-1.patch &amp;&amp;
make linux</userinput></screen>
<!-- make MYCFLAGS="-DLUA_COMPAT_5_2 -DLUA_COMPAT_5_1" linux
     The MYCFLAGS="" part was brought into the patch since optimization had to
     be turned off.
     The LUA_ROOT change also has been merged into the patch.-->

    <para>
      To test the results, issue: <command>make test</command>.
      <quote>This will run the interpreter and print its version</quote>.
      More comprehensive tests can be performed if you downloaded the "Test
      suite" tarball. Those tests need to be executed after the package is
      installed, thus we defer to the description below.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make INSTALL_TOP=/usr                \
     INSTALL_DATA="cp -d"            \
     INSTALL_MAN=/usr/share/man/man1 \
     TO_LIB="liblua.so liblua.so.5.4 liblua.so.&lua-version;" \
     install &amp;&amp;

mkdir -pv                      /usr/share/doc/lua-&lua-version; &amp;&amp;
cp -v doc/*.{html,css,gif,png} /usr/share/doc/lua-&lua-version; &amp;&amp;

install -v -m644 -D lua.pc /usr/lib/pkgconfig/lua.pc</userinput></screen>

    <para>
      Here we describe only the "Basic tests". Untar the tarball and
      change to the
      <filename class="directory">lua-&lua-version;-tests</filename> directory,
      then issue
      <command>lua -e "_U=true" all.lua</command>. If the tests finish without
      error, you will see a message containing the string "final OK".
    </para>

    <!-- The optimization problem fixed in the patch was identified by running
         the test suite, and ultimately culminated in a SIGBUS error. -->
  </sect2>

  <!-- Brought into the patch, unneeded
  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>sed -i ... src/luaconf.h</command>: This command changes the
      <application>Lua</application> search path to match the install path.
    </para>

    <para>
      <envar>MYCFLAGS="-DLUA_COMPAT_5_2 -DLUA_COMPAT_5_1"</envar>: This
      environment variable includes compatibility layers with Lua 5.1 and 5.2
      in the build.
    </para>

  </sect2>
  -->

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          lua and luac
        </seg>
        <seg>
          liblua.so
        </seg>
        <seg>
          /usr/{lib,share}/lua and
          /usr/share/doc/lua-&lua-version;
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="lua-prog">
        <term><command>lua</command></term>
        <listitem>
          <para>
            is the standalone Lua interpreter
          </para>
          <indexterm zone="lua lua-prog">
            <primary sortas="b-lua">lua</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="luac">
        <term><command>luac</command></term>
        <listitem>
          <para>
            is the Lua compiler
          </para>
          <indexterm zone="lua luac">
            <primary sortas="b-luac">luac</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="liblua">
        <term><filename class="libraryfile">liblua.so</filename></term>
        <listitem>
          <para>
            contains the <application>Lua</application> API functions
          </para>
          <indexterm zone="lua liblua">
            <primary sortas="c-liblua">liblua.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>