Changeset View
Changeset View
Standalone View
Standalone View
head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
Show First 20 Lines • Show All 6,384 Lines • ▼ Show 20 Lines | .endif</programlisting> | ||||
under the same name). In the ports tree this problem has | under the same name). In the ports tree this problem has | ||||
been solved by installing each version under a different | been solved by installing each version under a different | ||||
name using version number suffixes.</para> | name using version number suffixes.</para> | ||||
<para>The obvious disadvantage of this is that each | <para>The obvious disadvantage of this is that each | ||||
application has to be modified to find the expected version. | application has to be modified to find the expected version. | ||||
But it can be solved by adding some additional flags to the | But it can be solved by adding some additional flags to the | ||||
compiler and linker.</para> | 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> | ||||
<sect2 xml:id="lua-version"> | <sect2 xml:id="lua-version"> | ||||
<title>Version Selection</title> | <title>Version Selection</title> | ||||
<para>A port using <application>Lua</application> only needs to | <para>A port using <application>Lua</application> should | ||||
have this line:</para> | have a line of this form:</para> | ||||
<programlisting>USES= lua</programlisting> | <programlisting>USES= lua</programlisting> | ||||
<para>If a specific version of Lua is needed, instructions on | <para>If a specific version of Lua, or range of versions, is | ||||
how to select it are given in the <link | needed, it can be specified as a parameter in the form | ||||
linkend="uses-lua"><literal>USES=lua</literal></link> part | <literal>XY</literal> (which may be used multiple times), | ||||
of <xref linkend="uses"/>.</para> | <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> | ||||
<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"> | <sect2 xml:id="lua-defined-variables"> | ||||
<title>Defined Variables</title> | <title>Defined Variables</title> | ||||
<para>These variables are available in the port.</para> | <para>These variables are available in the port.</para> | ||||
<table frame="none" xml:id="using-lua-variables-ports"> | <table frame="none" xml:id="using-lua-variables-ports"> | ||||
<title>Variables Defined for Ports That Use | <title>Variables Defined for Ports That Use | ||||
<application>Lua</application></title> | <application>Lua</application></title> | ||||
Show All 17 Lines | <literal>5.1</literal>)</entry> | ||||
<row> | <row> | ||||
<entry><varname>LUA_VER_STR</varname></entry> | <entry><varname>LUA_VER_STR</varname></entry> | ||||
<entry>The <application>Lua</application> version | <entry>The <application>Lua</application> version | ||||
without the dots (for example, | without the dots (for example, | ||||
<literal>51</literal>)</entry> | <literal>51</literal>)</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>LUA_PREFIX</varname></entry> | <entry><varname>LUA_FLAVOR</varname></entry> | ||||
<entry>The prefix where <application>Lua</application> | <entry>The flavor name corresponding to the selected | ||||
(and components) is installed</entry> | <application>Lua</application> version, to be used | ||||
for specifying dependencies</entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>LUA_SUBDIR</varname></entry> | <entry><varname>LUA_BASE</varname></entry> | ||||
<entry>The directory under | <entry>The prefix that should be used to locate | ||||
<filename>${PREFIX}/bin</filename>, | <application>Lua</application> (and components) that | ||||
<filename>${PREFIX}/share</filename> and | are already installed</entry> | ||||
<filename>${PREFIX}/lib</filename> where | |||||
<application>Lua</application> is installed</entry> | |||||
</row> | </row> | ||||
<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><varname>LUA_INCDIR</varname></entry> | ||||
<entry>The directory where | <entry>The directory where | ||||
<application>Lua</application> and | <application>Lua</application> header files are | ||||
<application>tolua</application> header files are | |||||
installed</entry> | installed</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>LUA_LIBDIR</varname></entry> | <entry><varname>LUA_LIBDIR</varname></entry> | ||||
<entry>The directory where | <entry>The directory where | ||||
<application>Lua</application> and | <application>Lua</application> libraries are | ||||
<application>tolua</application> libraries are | |||||
installed</entry> | installed</entry> | ||||
</row> | </row> | ||||
<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><varname>LUA_MODLIBDIR</varname></entry> | ||||
<entry>The directory where | <entry>The directory where | ||||
<application>Lua</application> module libraries | <application>Lua</application> module libraries | ||||
(<filename>.so</filename>) are installed</entry> | (<filename>.so</filename>) are to be installed | ||||
by this port</entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>LUA_MODSHAREDIR</varname></entry> | <entry><varname>LUA_MODSHAREDIR</varname></entry> | ||||
<entry>The directory where | <entry>The directory where | ||||
<application>Lua</application> modules | <application>Lua</application> modules | ||||
(<filename>.lua</filename>) are installed</entry> | (<filename>.lua</filename>) are to be installed | ||||
by this port</entry> | |||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>LUA_PKGNAMEPREFIX</varname></entry> | <entry><varname>LUA_PKGNAMEPREFIX</varname></entry> | ||||
<entry>The package name prefix used by | <entry>The package name prefix used by | ||||
<application>Lua</application> modules</entry> | <application>Lua</application> modules</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>LUA_CMD</varname></entry> | <entry><varname>LUA_CMD</varname></entry> | ||||
<entry>The path to the <application>Lua</application> | <entry>The name of the <application>Lua</application> | ||||
interpreter</entry> | interpreter (e.g. <literal>lua53</literal>)</entry> | ||||
</row> | </row> | ||||
<row> | <row> | ||||
<entry><varname>LUAC_CMD</varname></entry> | <entry><varname>LUAC_CMD</varname></entry> | ||||
<entry>The path to the <application>Lua</application> | <entry>The name of the <application>Lua</application> | ||||
compiler</entry> | compiler (e.g. <literal>luac53</literal>)</entry> | ||||
</row> | </row> | ||||
</tbody> | </tbody> | ||||
</tgroup> | </tgroup> | ||||
</table> | </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> | </sect2> | ||||
</sect1> | </sect1> | ||||
<sect1 xml:id="using-iconv"> | <sect1 xml:id="using-iconv"> | ||||
<title>Using <command>iconv</command></title> | <title>Using <command>iconv</command></title> | ||||
<para>After 2013-10-08 (<revnumber>254273</revnumber>), | <para>After 2013-10-08 (<revnumber>254273</revnumber>), | ||||
&os; 10-CURRENT and newer versions have a native | &os; 10-CURRENT and newer versions have a native | ||||
▲ Show 20 Lines • Show All 749 Lines • Show Last 20 Lines |