svn commit: r54017 - in head/en_US.ISO8859-1/books/porters-handbook: special uses
Gleb Popov
arrowd at FreeBSD.org
Fri Mar 27 19:18:25 UTC 2020
Author: arrowd (ports committer)
Date: Fri Mar 27 19:18:17 2020
New Revision: 54017
URL: https://svnweb.freebsd.org/changeset/doc/54017
Log:
Document USES=cabal and its knobs.
Reviewed by: bcr, crees, 0mp
Differential Revision: https://reviews.freebsd.org/D23816
Modified:
head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Fri Mar 27 13:00:02 2020 (r54016)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Fri Mar 27 19:18:17 2020 (r54017)
@@ -1368,6 +1368,111 @@ daviddengcn-go-colortext-186a3d44e920_GH0.tar.
<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 at 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">
@@ -7137,6 +7242,15 @@ GROUPS= pulse pulse-access pulse-rt</programlisting>
at the time of upstream development/release.</para>
</listitem>
</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">
Modified: head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml Fri Mar 27 13:00:02 2020 (r54016)
+++ head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml Fri Mar 27 19:18:17 2020 (r54017)
@@ -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>
More information about the svn-doc-head
mailing list