Document USES=cabal and its knobs.
Reviewed by: bcr, crees, 0mp Differential Revision: https://reviews.freebsd.org/D23816
This commit is contained in:
Gleb Popov
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>
|
||||
</example>
|
||||
</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 xml:id="using-autotools">
|
||||
|
|
@ -7139,6 +7244,15 @@ GROUPS= pulse pulse-access pulse-rt</programlisting>
|
|||
</itemizedlist>
|
||||
</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">
|
||||
<title>Shell Completion Files</title>
|
||||
|
||||
|
|
|
|||
|
|
@ -235,6 +235,109 @@
|
|||
dependencies.</para>
|
||||
</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">
|
||||
<title><literal>cargo</literal></title>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue