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-all mailing list