Update porters handbook for Lua changes
Submitted by: andrew_tao173.riddles.org.uk Approved by: mat@ Differential Revision: https://reviews.freebsd.org/D24430
This commit is contained in:
Sergio Carlavilla Delgado
parent
1fbd368d54
commit
b6d1ce8b50
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=54612
3 changed files with 306 additions and 32 deletions
|
|
@ -424,4 +424,28 @@ USE_PYTHON= distutils allflavors</programlisting>
|
|||
USES= python:3.5+</programlisting>
|
||||
</example>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="flavors-auto-lua">
|
||||
<title><literal>USES=lua</literal> and Flavors</title>
|
||||
<para>When using <link
|
||||
linkend="uses-lua"><literal>USES=lua:module</literal></link>
|
||||
or <link
|
||||
linkend="uses-lua"><literal>USES=lua:flavors</literal></link>,
|
||||
the port will automatically have <varname>FLAVORS</varname>
|
||||
filled in with the <application>Lua</application> versions it
|
||||
supports. However, it is not expected that ordinary
|
||||
applications (rather than <application>Lua</application>
|
||||
modules) should use this feature; most applications that embed
|
||||
or otherwise use <application>Lua</application> should simply
|
||||
use <literal>USES=lua</literal>.</para>
|
||||
|
||||
<para><varname>LUA_FLAVOR</varname> is available (and must be
|
||||
used) to depend on the correct version of dependencies
|
||||
regardless of whether the port used the
|
||||
<literal>flavors</literal> or <literal>module</literal>
|
||||
parameters.</para>
|
||||
|
||||
<para>See <xref linkend="using-lua" /> for further
|
||||
information.</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
|
|
|||
|
|
@ -6390,20 +6390,155 @@ PLIST_SUB+= VERSION="${VER_STR}"
|
|||
application has to be modified to find the expected version.
|
||||
But it can be solved by adding some additional flags to the
|
||||
compiler and linker.</para>
|
||||
|
||||
<para>Applications that use <application>Lua</application>
|
||||
should normally build for just one version. However, loadable
|
||||
modules for Lua are built in a separate flavor for each Lua
|
||||
version that they support, and dependencies on such modules
|
||||
should specify the flavor using the
|
||||
<literal>@${LUA_FLAVOR}</literal> suffix on the port
|
||||
origin.</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 xml:id="lua-version">
|
||||
<title>Version Selection</title>
|
||||
|
||||
<para>A port using <application>Lua</application> only needs to
|
||||
have this line:</para>
|
||||
<para>A port using <application>Lua</application> should
|
||||
have a line of this form:</para>
|
||||
|
||||
<programlisting>USES= lua</programlisting>
|
||||
|
||||
<para>If a specific version of Lua is needed, instructions on
|
||||
how to select it are given in the <link
|
||||
linkend="uses-lua"><literal>USES=lua</literal></link> part
|
||||
of <xref linkend="uses"/>.</para>
|
||||
<para>If a specific version of Lua, or range of versions, is
|
||||
needed, it can be specified as a parameter in the form
|
||||
<literal>XY</literal> (which may be used multiple times),
|
||||
<literal>XY+</literal>, <literal>-XY</literal>, or
|
||||
<literal>XY-ZA</literal>. The default version of
|
||||
<application>Lua</application> as set via
|
||||
<varname>DEFAULT_VERSIONS</varname> will be used if it falls
|
||||
in the requested range, otherwise the closest requested
|
||||
version to the default will be used. For example:</para>
|
||||
|
||||
<programlisting>USES= lua:52-53</programlisting>
|
||||
|
||||
<para>Note that no attempt is made to adjust the version
|
||||
selection based on the presence of any already-installed
|
||||
<application>Lua</application> version.</para>
|
||||
|
||||
<note>
|
||||
<para>The <literal>XY+</literal> form of version specification
|
||||
should not be used without careful consideration; the
|
||||
<application>Lua</application> API changes to some extent in
|
||||
every version, and configuration tools like
|
||||
<application>CMake</application> or
|
||||
<application>Autoconf</application> will often fail to work
|
||||
on future versions of <application>Lua</application> until
|
||||
updated to do so.</para>
|
||||
</note>
|
||||
</sect2>
|
||||
|
||||
<sect2 xml:id="lua-version-config">
|
||||
<title>Configuration and Compiler flags</title>
|
||||
|
||||
<para>Software that uses <application>Lua</application> may have
|
||||
been written to auto-detect the <application>Lua</application>
|
||||
version in use. In general ports should override this
|
||||
assumption, and force the use of the specific
|
||||
<application>Lua</application> version selected as described
|
||||
above. Depending on the sortware being ported, this might
|
||||
require any or all of:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Using <varname>LUA_VER</varname> as part of a parameter
|
||||
to the software's configuration script via
|
||||
<varname>CONFIGURE_ARGS</varname> or
|
||||
<varname>CONFIGURE_ENV</varname> (or equivalent for other
|
||||
build systems);
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Adding <literal>-I${LUA_INCDIR}</literal>,
|
||||
<literal>-L${LUA_LIBDIR}</literal>, and
|
||||
<literal>-llua-${LUA_VER}</literal> to <varname>CFLAGS</varname>,
|
||||
<varname>LDFLAGS</varname>, <varname>LIBS</varname> respectively
|
||||
as appropriate;
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Patch the software's configuration or build files to select
|
||||
the correct version.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 xml:id="lua-version-flavors">
|
||||
<title>Version Flavors</title>
|
||||
|
||||
<para>A port which installs a <application>Lua</application>
|
||||
module (rather than an application that simply makes use of
|
||||
<application>Lua</application>) should build a separate
|
||||
flavor for each supported <application>Lua</application>
|
||||
version. This is done by adding the <literal>module</literal>
|
||||
parameter:</para>
|
||||
|
||||
<programlisting>USES= lua:module</programlisting>
|
||||
|
||||
<para>A version number or range of versions can be specified as
|
||||
well; use a comma to separate parameters.</para>
|
||||
|
||||
<para>Since each flavor must have a different package name, the
|
||||
variable <varname>LUA_PKGNAMEPREFIX</varname> is provided which
|
||||
will be set to an appropriate value; the intended usage
|
||||
is:</para>
|
||||
|
||||
<programlisting>PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX}</programlisting>
|
||||
|
||||
<para>Module ports should normally install files only to
|
||||
<varname>LUA_MODLIBDIR</varname>,
|
||||
<varname>LUA_MODSHAREDIR</varname>,
|
||||
<varname>LUA_DOCSDIR</varname>, and
|
||||
<varname>LUA_EXAMPLESDIR</varname>, all of which are set up
|
||||
to refer to version-specific subdirectories. Installing any
|
||||
other files must be done with care to avoid conflicts between
|
||||
versions.</para>
|
||||
|
||||
<para>A port (other than a <application>Lua</application> module)
|
||||
which wishes to build a separate package for each
|
||||
<application>Lua</application> version should use the
|
||||
<literal>flavors</literal> parameter:</para>
|
||||
|
||||
<programlisting>USES= lua:flavors</programlisting>
|
||||
|
||||
<para>This operates the same way as the <literal>module</literal>
|
||||
parameter described above, but without the assumption that the
|
||||
package should be documented as a <application>Lua</application>
|
||||
module (so <varname>LUA_DOCSDIR</varname> and
|
||||
<varname>LUA_EXAMPLESDIR</varname> are not defined by
|
||||
default). However, the port may choose to define
|
||||
<varname>LUA_DOCSUBDIR</varname> as a suitable subdirectory name
|
||||
(usually the port's <varname>PORTNAME</varname> as long as this
|
||||
does not conflict with the <varname>PORTNAME</varname> of any
|
||||
module), in which case the framework will define both
|
||||
<varname>LUA_DOCSDIR</varname> and
|
||||
<varname>LUA_EXAMPLESDIR</varname>.
|
||||
</para>
|
||||
|
||||
<para>As with module ports, a flavored port should avoid installing
|
||||
files that would conflict between versions. Typically this is done
|
||||
by adding <varname>LUA_VER_STR</varname> as a suffix to program
|
||||
names (e.g. using
|
||||
<link linkend="uses-uniquefiles">USES=uniquefiles</link>), and
|
||||
otherwise using either <varname>LUA_VER</varname> or
|
||||
<varname>LUA_VER_STR</varname> as part of any other files or
|
||||
subdirectories used outside of <varname>LUA_MODLIBDIR</varname>
|
||||
and <varname>LUA_MODSHAREDIR</varname>.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 xml:id="lua-defined-variables">
|
||||
|
|
@ -6439,48 +6574,69 @@ PLIST_SUB+= VERSION="${VER_STR}"
|
|||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUA_PREFIX</varname></entry>
|
||||
<entry>The prefix where <application>Lua</application>
|
||||
(and components) is installed</entry>
|
||||
<entry><varname>LUA_FLAVOR</varname></entry>
|
||||
<entry>The flavor name corresponding to the selected
|
||||
<application>Lua</application> version, to be used
|
||||
for specifying dependencies</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUA_SUBDIR</varname></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>
|
||||
<entry><varname>LUA_BASE</varname></entry>
|
||||
<entry>The prefix that should be used to locate
|
||||
<application>Lua</application> (and components) that
|
||||
are already installed</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUA_PREFIX</varname></entry>
|
||||
<entry>The prefix where <application>Lua</application>
|
||||
(and components) are to be installed by this port</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUA_INCDIR</varname></entry>
|
||||
<entry>The directory where
|
||||
<application>Lua</application> and
|
||||
<application>tolua</application> header files are
|
||||
<application>Lua</application> header files are
|
||||
installed</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUA_LIBDIR</varname></entry>
|
||||
<entry>The directory where
|
||||
<application>Lua</application> and
|
||||
<application>tolua</application> libraries are
|
||||
<application>Lua</application> libraries are
|
||||
installed</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUA_REFMODLIBDIR</varname></entry>
|
||||
<entry>The directory where
|
||||
<application>Lua</application> module libraries
|
||||
(<filename>.so</filename>) that are already
|
||||
installed are to be found</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUA_REFMODSHAREDIR</varname></entry>
|
||||
<entry>The directory where
|
||||
<application>Lua</application> modules
|
||||
(<filename>.lua</filename>) that are already
|
||||
installed are to be found</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUA_MODLIBDIR</varname></entry>
|
||||
<entry>The directory where
|
||||
<application>Lua</application> module libraries
|
||||
(<filename>.so</filename>) are installed</entry>
|
||||
(<filename>.so</filename>) are to be installed
|
||||
by this port</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUA_MODSHAREDIR</varname></entry>
|
||||
<entry>The directory where
|
||||
<application>Lua</application> modules
|
||||
(<filename>.lua</filename>) are installed</entry>
|
||||
(<filename>.lua</filename>) are to be installed
|
||||
by this port</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
|
|
@ -6491,18 +6647,96 @@ PLIST_SUB+= VERSION="${VER_STR}"
|
|||
|
||||
<row>
|
||||
<entry><varname>LUA_CMD</varname></entry>
|
||||
<entry>The path to the <application>Lua</application>
|
||||
interpreter</entry>
|
||||
<entry>The name of the <application>Lua</application>
|
||||
interpreter (e.g. <literal>lua53</literal>)</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUAC_CMD</varname></entry>
|
||||
<entry>The path to the <application>Lua</application>
|
||||
compiler</entry>
|
||||
<entry>The name of the <application>Lua</application>
|
||||
compiler (e.g. <literal>luac53</literal>)</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<para>These additional variables are available for ports that
|
||||
specified the <literal>module</literal> parameter:</para>
|
||||
|
||||
<table frame="none" xml:id="using-lua-variables-modules">
|
||||
<title>Variables Defined for <application>Lua</application>
|
||||
Module Ports</title>
|
||||
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Name</entry>
|
||||
<entry>Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry><varname>LUA_DOCSDIR</varname></entry>
|
||||
<entry>the directory to which the module's
|
||||
documentation should be installed.</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
<entry><varname>LUA_EXAMPLESDIR</varname></entry>
|
||||
<entry>the directory to which the module's
|
||||
example files should be installed.</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2 xml:id="lua-examples">
|
||||
<title>Examples</title>
|
||||
|
||||
<example xml:id="lua-app-Makefile">
|
||||
<title>Makefile for an application using
|
||||
<application>Lua</application></title>
|
||||
|
||||
<para>This example shows how to reference a
|
||||
<application>Lua</application> module required at run
|
||||
time. Notice that the reference must specify a
|
||||
flavor.</para>
|
||||
|
||||
<programlisting>PORTNAME= sample
|
||||
DISTVERSION= 1.2.3
|
||||
CATEGORIES= whatever
|
||||
|
||||
MAINTAINER= john@doe.tld
|
||||
COMMENT= Sample
|
||||
|
||||
RUN_DEPENDS= ${LUA_REFMODLIBDIR}/lpeg.so:devel/lua-lpeg@${LUA_FLAVOR}
|
||||
|
||||
USES= lua
|
||||
|
||||
.include <bsd.port.mk></programlisting>
|
||||
</example>
|
||||
|
||||
<example xml:id="lua-mod-Makefile">
|
||||
<title>Makefile for a simple <application>Lua</application>
|
||||
module</title>
|
||||
|
||||
<programlisting>PORTNAME= sample
|
||||
DISTVERSION= 1.2.3
|
||||
CATEGORIES= whatever
|
||||
PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX}
|
||||
|
||||
MAINTAINER= john@doe.tld
|
||||
COMMENT= Sample
|
||||
|
||||
USES= lua:module
|
||||
|
||||
DOCSDIR= ${LUA_DOCSDIR}
|
||||
|
||||
.include <bsd.port.mk></programlisting>
|
||||
</example>
|
||||
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
|
|
|||
|
|
@ -1969,17 +1969,33 @@ GSSAPI_NONE_CONFIGURE_ON= --without-gssapi</programlisting>
|
|||
<title><literal>lua</literal></title>
|
||||
|
||||
<para>Possible arguments: (none),
|
||||
<literal><replaceable>XY</replaceable>+</literal>,
|
||||
<literal><replaceable>XY</replaceable></literal>,
|
||||
<literal>build</literal>, <literal>run</literal></para>
|
||||
<literal><replaceable>XY</replaceable>+</literal>,
|
||||
<literal>-<replaceable>XY</replaceable></literal>,
|
||||
<literal><replaceable>XY</replaceable>-<replaceable>ZA</replaceable></literal>,
|
||||
<literal>module</literal>, <literal>flavors</literal>,
|
||||
<literal>build</literal>, <literal>run</literal>,
|
||||
<literal>env</literal></para>
|
||||
|
||||
<para>Adds a dependency on <application>Lua</application>. By
|
||||
default this is a library dependency, unless overridden by the
|
||||
<literal>build</literal> or <literal>run</literal> option. The
|
||||
default version is 5.2, unless set by the
|
||||
<literal><replaceable>XY</replaceable></literal> parameter (for
|
||||
example, <literal>51</literal> or
|
||||
<literal>52+</literal>).</para>
|
||||
<literal>build</literal> and/or <literal>run</literal> option.
|
||||
The <literal>env</literal> option prevents the addition of any
|
||||
dependency, while still defining all the usual variables.</para>
|
||||
|
||||
<para>The default version is set by the usual
|
||||
<literal>DEFAULT_VERSIONS</literal> mechanism, unless a version or
|
||||
range of versions is specified as an argument, for
|
||||
example, <literal>51</literal> or <literal>51-53</literal>.</para>
|
||||
|
||||
<para>Applications using <application>Lua</application> are
|
||||
normally built for only a single <application>Lua</application>
|
||||
version. However, library modules intended to be loaded by
|
||||
<application>Lua</application> code should use the
|
||||
<literal>module</literal> option to build with multiple
|
||||
flavors.</para>
|
||||
|
||||
<para>For more information see <xref linkend="using-lua" />.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 xml:id="uses-lxqt">
|
||||
|
|
|
|||
Loading…
Reference in a new issue