.\"	$OpenBSD: cabal-module.5,v 1.2 2021/07/25 11:29:42 espie Exp $
.\"
.\" Copyright (c) 2021 Greg Steuck
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: July 25 2021 $
.Dt CABAL-MODULE 5
.Os
.Sh NAME
.Nm cabal-module
.Nd devel/cabal port module for building Haskell programs
.Sh DESCRIPTION
This manual page documents the behavior of setting
.Li MODULES=devel/cabal
in the
.Xr ports 7
tree.
.Pp
Uses
.Xr cabal 1
to automate packaging Haskell binary projects.
During
.Cm fetch ,
the dependent packages enumerated in
.Ev MODCABAL_MANIFEST
are downloaded into the
.Pa hackage
subdirectory of
.Ev DIST_SUBDIR .
During
.Cm post-extract ,
the dependency sources are unpacked into
.Ev WORKDIR .
Special care is taken to replace .cabal files if they are updated
post-release on hackage.
A custom
.Pa cabal.project.local
file gets created to direct
.Xr cabal 1
to the extracted packages and prevent any network interaction.
In rare cases a custom
.Pa cabal.project
is required.
This module automatically copies such files from port's
.Pa files
into
.Ev WRKSRC .
During
.Cm build ,
.Xr cabal 1
is invoked to build the executables listed in
.Ev MODCABAL_EXECUTABLES .
.Pp
.Pa lang/ghc
and
.Pa devel/cabal-install
are added to
.Ev BUILD_DEPENDS .
This module uses
.Ev MASTER_SITES9
to download the sources from hackage.
.Pp
This module parameters:
.Bl -tag -width MODCABAL_EXECUTABLES
.It MODCABAL_STEM
Name of the package on hackage (required).
.It MODCABAL_VERSION
Version of the package (required).
.It MODCABAL_MANIFEST
Hackage dependencies required by this package, see below.
.It MODCABAL_DATA_DIR
data-dir from .cabal file (if executable needs this)
.It MODCABAL_REVISION
Numeric revision of .cabal file on hackage if one is
needed on top of .cabal file contained in the .tar.gz file.
.It MODCABAL_BUILD_ARGS
passed to cabal v2-build
.It MODCABAL_FLAGS
custom feature
.Fl -flags
for
.Xr cabal 1 .
.It MODCABAL_EXECUTABLES
Executable target in .cabal file, defaults to hackage package name in
.Ev MODCABAL_STEM .
.El
.Pp
This module adds currently adds no
.Xr make 1
targets.
.Sh DEPENDENCY MANIFEST
Hackage dependencies are listed in
.Ev MODCABAL_MANIFEST
as space separate triples of
.Em package
.Em version
.Em revision .
They correspond to the main package values of
.Ev MODCABAL_STEM
.Ev MODCABAL_VERSION
.Ev MODCABAL_REVISION .
.Pp
The contents of
.Ev MODCABAL_MANIFEST
is normally generated by
.Pa devel/cabal-bundler
which creates a working build plan from hackage dependency information.
.Sh EXAMPLES
To create a new Haskell binary port one would install cabal-bundler
port, look up the chosen package version number on hackage.
E.g.
.Pp
$
.Cm cabal-bundler
.Fl -openbsd
.Ar cpphs-1.20
.Sh SEE ALSO
.Xr cabal 1 ,
.Xr port-modules 5