Date: Sun, 29 Oct 2006 11:42:24 -0300 From: "Alejandro Pulver" <alepulver@FreeBSD.org> To: "FreeBSD gnats submit" <FreeBSD-gnats-submit@FreeBSD.org> Subject: docs/104909: [PATCH] Add Lua entry to PH Message-ID: <1162132944.19094@phobos.mars.bsd> Resent-Message-ID: <200610291450.k9TEoEuQ075535@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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@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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?1162132944.19094>