docs/104909: [PATCH] Add Lua entry to PH
Alejandro Pulver
alepulver at FreeBSD.org
Sun Oct 29 14:50:15 UTC 2006
>Number: 104909
>Category: docs
>Synopsis: [PATCH] Add Lua entry to PH
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Sun Oct 29 14:50:13 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator: Alejandro Pulver
>Release: FreeBSD 6.1-RELEASE-p1 i386
>Organization:
>Environment:
System: FreeBSD 6.1-RELEASE-p1 #3: Mon Jun 19 14:49:35 ART 2006
root at phobos.mars.bsd:/usr/obj/usr/src/sys/ATHLON-PHOBOS
>Description:
- Add Lua entry to PH.
- Fix wrong comment in bsd.lua.mk.
Please review this patch since it is my first docs PR.
>How-To-Repeat:
>Fix:
--- patch.diff begins here ---
Index: doc/en_US.ISO8859-1/books/porters-handbook/book.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/porters-handbook/book.sgml,v
retrieving revision 1.759
diff -u -r1.759 book.sgml
--- doc/en_US.ISO8859-1/books/porters-handbook/book.sgml 7 Oct 2006 20:55:22 -0000 1.759
+++ doc/en_US.ISO8859-1/books/porters-handbook/book.sgml 29 Oct 2006 14:36:50 -0000
@@ -6263,6 +6263,550 @@
</sect1>
+ <sect1 id="using-lua">
+ <title>Using <application>Lua</application></title>
+
+ <para>This section describes the status of the
+ <application>Lua</application> libraries in the ports tree and its
+ integration with the ports system.</para>
+
+ <sect2 id="lua-introduction">
+ <title>Introduction</title>
+
+ <para>There are many versions of the <application>Lua</application>
+ libraries and corresponding interpreters, which conflict between
+ them (install files under the same name). In the ports tree this
+ problem has been solved by installing each version under a different
+ name using version number suffixes.</para>
+
+ <para>The obvious disadventage of this is that each application has to
+ be modified to found the expected version. But it can be solved by
+ adding some additional flags to the compiler and linker.</para>
+ </sect2>
+
+ <sect2 id="lua-version">
+ <title>Version selection</title>
+
+ <para>To make your port use a specific version of
+ <application>Lua</application> there are two variables available
+ for defining (if only one is defined the other will be set to a
+ default value):</para>
+
+ <table id="lua-ver-sel-table">
+ <title>Variables to select <application>Lua</application>
+ versions</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Variable</entry>
+
+ <entry>Description</entry>
+
+ <entry>Default value</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>USE_LUA</makevar></entry>
+
+ <entry>List of versions the port can use</entry>
+
+ <entry>All available versions</entry>
+ </row>
+
+ <row>
+ <entry><makevar>USE_LUA_NOT</makevar></entry>
+
+ <entry>List of versions the port can not use</entry>
+
+ <entry>None</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The following is a list of available
+ <application>Lua</application> versions and the corresponding port
+ in the tree:</para>
+
+ <table>
+ <title>Available <application>Lua</application> versions</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Version</entry>
+
+ <entry>Port</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>4.0</literal></entry>
+
+ <entry><filename role="package">lang/lua4</filename></entry>
+ </row>
+
+ <row>
+ <entry><literal>5.0</literal></entry>
+
+ <entry><filename role="package">lang/lua50</filename></entry>
+ </row>
+
+ <row>
+ <entry><literal>5.1</literal></entry>
+
+ <entry><filename role="package">lang/lua</filename></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The variables in <xref linkend="lua-ver-sel-table"> can be set
+ to one or more of the following combinations separated by
+ spaces:</para>
+
+ <table>
+ <title><application>Lua</application> version specifications</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Description</entry>
+
+ <entry>Example</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>Single version</entry>
+
+ <entry><literal>4.0</literal></entry>
+ </row>
+
+ <row>
+ <entry>Ascending range</entry>
+
+ <entry><literal>5.0+</literal></entry>
+ </row>
+
+ <row>
+ <entry>Descending range</entry>
+
+ <entry><literal>5.0-</literal></entry>
+ </row>
+
+ <row>
+ <entry>Full range (must be ascending)</entry>
+
+ <entry><literal>5.0-5.1</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>There are also some variables to select the preferred versions
+ from the available ones. They can be set to a list of versions, the
+ first ones will have higher priority.</para>
+
+ <table>
+ <title>Variables to select preferred <application>Lua</application>
+ versions</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Designed for</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>WANT_LUA_VER</makevar></entry>
+
+ <entry>the port</entry>
+ </row>
+
+ <row>
+ <entry><makevar>WITH_LUA_VER</makevar></entry>
+
+ <entry>the user</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <example id="lua-version-example">
+ <title>Selecting the <application>Lua</application> version</title>
+
+ <para>The following fragment is from a port which can use
+ <application>Lua</application> version <literal>5.0</literal> or
+ <literal>5.1</literal>, and uses <literal>5.0</literal> by
+ default. It can be overriden by the user using
+ <makevar>WITH_LUA_VER</makevar>.</para>
+
+ <programlisting>USE_LUA= 5.0-5.1
+WANT_LUA_VER= 5.0</programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="lua-components">
+ <title>Component selection</title>
+
+ <para>There are other applications that, while not being
+ <application>Lua</application> libraries, are related to them. These
+ applications can be specified in the <makevar>LUA_COMPS</makevar>
+ variable. The following components are available:</para>
+
+ <table>
+ <title>Available <application>Lua</application> components</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Description</entry>
+
+ <entry>Version restriction</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>lua</literal></entry>
+
+ <entry>main library</entry>
+
+ <entry>none</entry>
+ </row>
+
+ <row>
+ <entry><literal>tolua</literal></entry>
+
+ <entry>Library for accesing C/C++ code</entry>
+
+ <entry><literal>4.0-5.0</literal></entry>
+ </row>
+
+ <row>
+ <entry><literal>ruby</literal></entry>
+
+ <entry>Ruby bindings</entry>
+
+ <entry><literal>4.0-5.0</literal></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <note>
+ <para>There are more components but they are modules for the
+ interpreter, not used by applications (only by other
+ modules).</para>
+ </note>
+
+ <para>The dependency type added when you select each component can be
+ manually specified by adding a suffix separated by a
+ <literal>:</literal>, or a default value will be used. The available
+ dependency types are:</para>
+
+ <table>
+ <title>Available <application>Lua</application> dependency
+ types</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>build</literal></entry>
+
+ <entry>Component is required for building, equivalent to
+ <makevar>BUILD_DEPENDS</makevar></entry>
+ </row>
+
+ <row>
+ <entry><literal>run</literal></entry>
+
+ <entry>Component is required for running, equivalent to
+ <makevar>RUN_DEPENDS</makevar></entry>
+ </row>
+
+ <row>
+ <entry><literal>lib</literal></entry>
+
+ <entry>Component is required for building and running,
+ equivalent to <makevar>LIB_DEPENDS</makevar>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The default values for the components are detailed in the
+ following table:</para>
+
+ <table>
+ <title>Default <application>Lua</application> dependency
+ types</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Value</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><literal>lua</literal></entry>
+
+ <entry><literal>lib</literal> for <literal>4.0-5.0</literal>
+ (shared) and <literal>build</literal> for
+ <literal>5.1</literal> (static)</entry>
+ </row>
+
+ <row>
+ <entry><literal>tolua</literal></entry>
+
+ <entry><literal>build</literal> (static)</entry>
+ </row>
+
+ <row>
+ <entry><literal>ruby</literal></entry>
+
+ <entry><literal>lib</literal> (shared)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <example id="lua-components-example">
+ <title>Selecting <application>Lua</application> components</title>
+
+ <para>The following fragment corresponds to a port which uses
+ <application>Lua</application> version <literal>4.0</literal> and
+ its <application>Ruby</application> bindings.</para>
+
+ <programlisting>USE_LUA= 4.0
+LUA_COMPS= lua ruby</programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="lua-version-detection">
+ <title>Detecting installed versions</title>
+
+ <para>To detect an installed version you have to define
+ <makevar>WANT_LUA</makevar>. If you do not set it to a specific
+ version then the components will have a version suffix. The
+ <makevar>HAVE_LUA</makevar> variable will be filled after
+ detection.</para>
+
+ <example id="lua-ver-det-example">
+ <title>Detecting installed <application>Lua</application> versions
+ and components</title>
+
+ <para>The following fragment can be used in a port that uses
+ <application>Lua</application> if it is installed, or an option is
+ selected.</para>
+
+ <programlisting>WANT_LUA= yes
+
+.include <bsd.port.pre.mk>
+
+.if defined(WITH_LUA5) || ${HAVE_LUA:Mlua-5.[01]} != ""
+USE_LUA= 5.0-5.1
+CONFIGURE_ARGS+=--enable-lua5
+.endif</programlisting>
+
+ <para>The following fragment can be used in a port that enables
+ <application>tolua</application> support if it is installed or if
+ an option is selected, in addition to
+ <application>Lua</application>, both version
+ <literal>4.0</literal>.</para>
+
+ <programlisting>USE_LUA= 4.0
+LUA_COMPS= lua
+WANT_LUA= 4.0
+
+.include <bsd.port.pre.mk>
+
+.if defined(WITH_TOLUA) || ${HAVE_LUA:Mtolua} != ""
+LUA_COMPS+= tolua
+CONFIGURE_ARGS+=--enable-tolua
+.endif</programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="lua-defined-variables">
+ <title>Defined variables</title>
+
+ <para>The following variables are defined after defining one of the
+ variables from <xref linkend="lua-ver-sel-table">.</para>
+
+ <table>
+ <title>Variables defined for ports that use
+ <application>Lua</application></title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><makevar>LUA_VER</makevar></entry>
+
+ <entry>The <application>Lua</application> version that is
+ going to be used (e.g., <literal>5.1</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>LUA_VER_SH</makevar></entry>
+ <entry>The <application>Lua</application> shared library major
+ version (e.g., <literal>1</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>LUA_VER_STR</makevar></entry>
+
+ <entry>The <application>Lua</application> version without the
+ dots (e.g., <literal>51</literal>)</entry>
+ </row>
+
+ <row>
+ <entry><makevar>LUA_PREFIX</makevar></entry>
+
+ <entry>The prefix where <application>Lua</application> (and
+ components) is installed</entry>
+ </row>
+
+ <row>
+ <entry><makevar>LUA_SUBDIR</makevar></entry>
+
+ <entry>The directory under <filename>${PREFIX}/bin</filename>,
+ <filename>${PREFIX}/share</filename> and
+ <filename>${PREFIX}/lib</filename> where
+ <application>Lua</application> is installed</entry>
+ </row>
+
+ <row>
+ <entry><makevar>LUA_INCDIR</makevar></entry>
+
+ <entry>The directory where <application>Lua</application> and
+ <application>tolua</application> header files are
+ installed</entry>
+ </row>
+
+ <row>
+ <entry><makevar>LUA_LIBDIR</makevar></entry>
+
+ <entry>The directory where <application>Lua</application> and
+ <application>tolua</application> libraries are
+ installed</entry>
+ </row>
+
+ <row>
+ <entry><makevar>LUA_MODLIBDIR</makevar></entry>
+
+ <entry>The directory where <application>Lua</application>
+ module libraries (<filename>.so</filename>) are
+ installed</entry>
+ </row>
+
+ <row>
+ <entry><makevar>LUA_MODSHAREDIR</makevar></entry>
+
+ <entry>The directory where <application>Lua</application>
+ modules (<filename>.lua</filename>) are installed</entry>
+ </row>
+
+ <row>
+ <entry><makevar>LUA_PKGNAMEPREFIX</makevar></entry>
+
+ <entry>The package name prefix used by
+ <application>Lua</application> modules</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <example id="lua-variables-example">
+ <title>Telling the port where to find
+ <application>Lua</application></title>
+
+ <para>The following fragment shows how to tell a port that uses a
+ configure script where the <application>Lua</application> header
+ files and libraries are.</para>
+
+ <programlisting>
+USE_LUA= 4.0
+GNU_CONFIGURE= yes
+CONFIGURE_ENV= CPPFLAGS="-I${LUA_INCDIR}" LDFLAGS="-L${LUA_LIBDIR}"</programlisting>
+ </example>
+ </sect2>
+
+ <sect2 id="lua-premk">
+ <title>Processing in <filename>bsd.port.pre.mk</filename></title>
+
+ <para>If you need to use the variables for running commands right
+ after including <filename>bsd.port.pre.mk</filename> you need to
+ define <makevar>LUA_PREMK</makevar>.</para>
+
+ <important>
+ <para>If you define <makevar>LUA_PREMK</makevar>, then the version,
+ dependencies, components and defined variables will not change if
+ you modify the <application>Lua</application> port variables
+ <emphasis>after</emphasis> including
+ <filename>bsd.port.pre.mk</filename>.</para>
+ </important>
+
+ <example id="lua-premk-example">
+ <title>Using <application>Lua</application> variables in
+ commands</title>
+
+ <para>The following fragment illustrates the use of
+ <makevar>LUA_PREMK</makevar> by running the
+ <application>Lua</application> interpreter to obtain the full
+ version string, assign it to a variable and pass it to the
+ program.</para>
+
+ <programlisting>USE_LUA= 5.0
+LUA_PREMK= yes
+
+.include <bsd.port.pre.mk>
+
+VER_STR!= lua${LUA_VER} -v
+
+CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}"</programlisting>
+ </example>
+
+ <note>
+ <para>The <application>Lua</application> variables can be safely
+ used in commands when they are inside targets without the need of
+ <makevar>LUA_PREMK</makevar>.</para>
+ </note>
+ </sect2>
+ </sect1>
+
<sect1 id="rc-scripts">
<title>Starting and stopping services (rc scripts)</title>
--- patch.diff ends here ---
--- patch2.diff begins here ---
Index: ports/Mk/bsd.lua.mk
===================================================================
RCS file: /home/pcvs/ports/Mk/bsd.lua.mk,v
retrieving revision 1.2
diff -u -r1.2 bsd.lua.mk
--- ports/Mk/bsd.lua.mk 5 Oct 2006 18:17:25 -0000 1.2
+++ ports/Mk/bsd.lua.mk 28 Oct 2006 15:41:34 -0000
@@ -75,9 +75,9 @@
# LUA_SUBDIR - The directory under bin/share/lib where Lua is installed.
# LUA_INCDIR - The directory where Lua and tolua header files are installed.
# LUA_LIBDIR - The directory where Lua and tolua libraries are installed.
-# LUA_MODLIBDIR - The directory where Lua modules (.lua) are installed.
+# LUA_MODLIBDIR - The directory where Lua module libraries (.so) are installed.
# LUA_MODSHAREDIR
-# - The directory where Lua module libraries (.so) are installed.
+# - The directory where Lua modules (.lua) are installed.
# LUA_PKGNAMEPREFIX
# - The package name prefix used by Lua modules.
#
--- patch2.diff ends here ---
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list