svn commit: r54017 - in head/en_US.ISO8859-1/books/porters-handbook: special uses

Gleb Popov <[email protected]>
Newsgroups gmane.os.freebsd.devel.cvs.doc
Message-ID <[email protected]> 
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=	[email protected]
+COMMENT=	Shell script analysis tool
+
+USES=		cabal
+
+.include &lt;bsd.port.mk&gt;</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>
 
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"
lmpx.com only provides a reader for public news (NNTP) servers. It is not affiliated with the servers or forums shown here and is not responsible for the content of articles, which is written by their respective authors.