Document USES=cabal and its knobs.
Reviewed by: bcr, crees, 0mp Differential Revision: https://reviews.freebsd.org/D23816
This commit is contained in:
parent
9f5fb725a5
commit
98614b27d1
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=54017
2 changed files with 217 additions and 0 deletions
en_US.ISO8859-1/books/porters-handbook
|
@ -1368,6 +1368,111 @@ daviddengcn-go-colortext-186a3d44e920_GH0.tar. 4534 B 1098 kBps 00s
|
||||||
<literal>${PREFIX}/sbin</literal>.</para>
|
<literal>${PREFIX}/sbin</literal>.</para>
|
||||||
</example>
|
</example>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
|
<sect2 xml:id="using-cabal">
|
||||||
|
<title>Building <application>Haskell</application>
|
||||||
|
Applications with <command>cabal</command></title>
|
||||||
|
|
||||||
|
<para>For ports that use <application>Cabal</application>,
|
||||||
|
build system defines <literal>USES=cabal</literal>. Refer to <xref
|
||||||
|
linkend="uses-cabal"/> for a list of variables that can be
|
||||||
|
set to control the build process.</para>
|
||||||
|
|
||||||
|
<example xml:id="cabal-ex1">
|
||||||
|
<title>Creating a Port for a Hackage-hosted Haskell
|
||||||
|
Application</title>
|
||||||
|
|
||||||
|
<para>When preparing a Haskell Cabal port, the
|
||||||
|
<package role="port">devel/hs-cabal-install</package> program is
|
||||||
|
required, so make sure it is installed beforehand. First we need
|
||||||
|
to define common ports variables that allows
|
||||||
|
cabal-install to fetch the package distribution file:</para>
|
||||||
|
|
||||||
|
<programlisting>PORTNAME= ShellCheck
|
||||||
|
DISTVERSION= 0.6.0
|
||||||
|
CATEGORIES= devel
|
||||||
|
|
||||||
|
MAINTAINER= haskell@FreeBSD.org
|
||||||
|
COMMENT= Shell script analysis tool
|
||||||
|
|
||||||
|
USES= cabal
|
||||||
|
|
||||||
|
.include <bsd.port.mk></programlisting>
|
||||||
|
|
||||||
|
<para>This minimal Makefile allows us to fetch the distribution file:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>make cabal-extract</userinput>
|
||||||
|
[...]
|
||||||
|
Downloading the latest package list from hackage.haskell.org
|
||||||
|
cabal get ShellCheck-0.6.0
|
||||||
|
Downloading ShellCheck-0.6.0
|
||||||
|
Downloaded ShellCheck-0.6.0
|
||||||
|
Unpacking to ShellCheck-0.6.0/</screen>
|
||||||
|
|
||||||
|
<para>Now we have ShellCheck.cabal package description file,
|
||||||
|
which allows us to fetch all package's dependencies,
|
||||||
|
including transitive ones:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>make cabal-extract-deps</userinput>
|
||||||
|
[...]
|
||||||
|
Resolving dependencies...
|
||||||
|
Downloading base-orphans-0.8.2
|
||||||
|
Downloaded base-orphans-0.8.2
|
||||||
|
Downloading primitive-0.7.0.0
|
||||||
|
Starting base-orphans-0.8.2 (lib)
|
||||||
|
Building base-orphans-0.8.2 (lib)
|
||||||
|
Downloaded primitive-0.7.0.0
|
||||||
|
Downloading dlist-0.8.0.7
|
||||||
|
[...]</screen>
|
||||||
|
|
||||||
|
<para>As a side effect, the package's dependencies are
|
||||||
|
also compiled, so the command may take some time.
|
||||||
|
Once done, a list of required dependencies can generated:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>make make-use-cabal</userinput>
|
||||||
|
USE_CABAL=QuickCheck-2.12.6.1 \
|
||||||
|
hashable-1.3.0.0 \
|
||||||
|
integer-logarithms-1.0.3 \
|
||||||
|
[...]</screen>
|
||||||
|
|
||||||
|
<para>Haskell packages may contain revisions, just like
|
||||||
|
FreeBSD ports. Revisions can affect only <filename>.cabal</filename>
|
||||||
|
files, but it is still important to pull them in.
|
||||||
|
To check <varname>USE_CABAL</varname> items for available
|
||||||
|
revision updates, run following command:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>make make-use-cabal-revs</userinput>
|
||||||
|
USE_CABAL=QuickCheck-2.12.6.1_1 \
|
||||||
|
hashable-1.3.0.0 \
|
||||||
|
integer-logarithms-1.0.3_2 \
|
||||||
|
[...]</screen>
|
||||||
|
|
||||||
|
<para>Note additional version numbers after <literal>_</literal>
|
||||||
|
symbol. Put newly generated <varname>USE_CABAL</varname> list
|
||||||
|
instead of an old one.</para>
|
||||||
|
|
||||||
|
<para>Finally, <filename>distinfo</filename> needs to be regenerated to
|
||||||
|
contain all the distribution files:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>make makesum</userinput>
|
||||||
|
=> ShellCheck-0.6.0.tar.gz doesn't seem to exist in /usr/local/poudriere/ports/git/distfiles/cabal.
|
||||||
|
=> Attempting to fetch https://hackage.haskell.org/package/ShellCheck-0.6.0/ShellCheck-0.6.0.tar.gz
|
||||||
|
ShellCheck-0.6.0.tar.gz 136 kB 642 kBps 00s
|
||||||
|
=> QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz doesn't seem to exist in /usr/local/poudriere/ports/git/distfiles/cabal.
|
||||||
|
=> Attempting to fetch https://hackage.haskell.org/package/QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz
|
||||||
|
QuickCheck-2.12.6.1/QuickCheck-2.12.6.1.tar.gz 65 kB 361 kBps 00s
|
||||||
|
[...]</screen>
|
||||||
|
|
||||||
|
<para>The port is now ready for a test build and further
|
||||||
|
adjustments like creating a plist, writing a description,
|
||||||
|
adding license information, options, etc. as normal.</para>
|
||||||
|
|
||||||
|
<para>If you are not testing your port in a clean environment
|
||||||
|
like with <application>Poudriere</application>, remember to
|
||||||
|
run <command>make clean</command> before any testing.</para>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 xml:id="using-autotools">
|
<sect1 xml:id="using-autotools">
|
||||||
|
@ -7139,6 +7244,15 @@ GROUPS= pulse pulse-access pulse-rt</programlisting>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 xml:id="haskell-libs">
|
||||||
|
<title>Haskell Libraries</title>
|
||||||
|
|
||||||
|
<para>Just like in case of Go language, Ports must not package or
|
||||||
|
install Haskell libraries. Haskell ports must link statically
|
||||||
|
to their dependencies and fetch all distribution files on
|
||||||
|
fetch stage.</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
<sect1 xml:id="shell-completion">
|
<sect1 xml:id="shell-completion">
|
||||||
<title>Shell Completion Files</title>
|
<title>Shell Completion Files</title>
|
||||||
|
|
||||||
|
|
|
@ -235,6 +235,109 @@
|
||||||
dependencies.</para>
|
dependencies.</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 xml:id="uses-cabal">
|
||||||
|
<title><literal>cabal</literal></title>
|
||||||
|
|
||||||
|
<important>
|
||||||
|
<para>Ports should not be created for Haskell libraries, see
|
||||||
|
<xref linkend="haskell-libs"/> for more information.</para>
|
||||||
|
</important>
|
||||||
|
|
||||||
|
<para>Possible arguments: (none), <literal>hpack</literal></para>
|
||||||
|
|
||||||
|
<para>Sets default values and targets used to build
|
||||||
|
<application>Haskell</application> software using Cabal.
|
||||||
|
A build dependency on the Haskell compiler port (GHC)
|
||||||
|
is added. If <literal>hpack</literal> argument is given,
|
||||||
|
a build dependency on <package role="port">devel/hs-hpack</package>
|
||||||
|
is added and <command>hpack</command> is invoked at
|
||||||
|
configuration step to generate .cabal file.</para>
|
||||||
|
|
||||||
|
<para>The framework provides the following variables:</para>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><varname>USE_CABAL</varname></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>If the software uses Haskell dependencies, list them in
|
||||||
|
this variable. Each item should be present on Hackage and
|
||||||
|
be listed in form <literal>packagename-<replaceable>0.1.2</replaceable></literal>.
|
||||||
|
Dependencies can have revisions, which are specified after the
|
||||||
|
<literal>_</literal> symbol. Automatic generation of dependency
|
||||||
|
list is supported, see <xref linkend="using-cabal"/>.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><varname>CABAL_FLAGS</varname></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>List of flags to be passed to <command>cabal-install</command>
|
||||||
|
during the configuring and building stage. The flags are
|
||||||
|
passed verbatim.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><varname>EXECUTABLES</varname></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>List of executable files installed by the port.
|
||||||
|
Default value: <varname>${PORTNAME}</varname>.
|
||||||
|
Items from this list are automatically added to pkg-plist.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><varname>SKIP_CABAL_PLIST</varname></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>If defined, do not add items from
|
||||||
|
<varname>${EXECUTABLES}</varname> to pkg-plist.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><varname>opt_USE_CABAL</varname></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>Adds items to <varname>${USE_CABAL}</varname>
|
||||||
|
depending on <literal>opt</literal> option.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><varname>opt_EXECUTABLES</varname></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>Adds items to <varname>${EXECUTABLES}</varname>
|
||||||
|
depending on <literal>opt</literal> option.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><varname>opt_CABAL_FLAGS</varname></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>If <option>opt</option> is enabled, append the value
|
||||||
|
to <varname>${CABAL_FLAGS}</varname>. Otherwise, append
|
||||||
|
<literal>-value</literal> to disable the flag.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><varname>FOO_DATADIR_VARS</varname></term>
|
||||||
|
|
||||||
|
<listitem>
|
||||||
|
<para>For an executable named <literal>FOO</literal>
|
||||||
|
list Haskell packages, whose data files
|
||||||
|
should be accessible by the executable.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
<sect1 xml:id="uses-cargo">
|
<sect1 xml:id="uses-cargo">
|
||||||
<title><literal>cargo</literal></title>
|
<title><literal>cargo</literal></title>
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue