Date: Fri, 27 Mar 2020 19:18:17 +0000 (UTC) From: Gleb Popov <arrowd@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r54017 - in head/en_US.ISO8859-1/books/porters-handbook: special uses Message-ID: <202003271918.02RJIHnb041772@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202003271918.02RJIHnb041772>