Uses/cabal.mk: Improve our Cabal machinery.

- Introduce CABAL_PROJECT variable to simplify handling project files in ports.
- Put dependencies into ${WRKSRC}/_cabal_deps subdir to make WRKSRC look
  clean after `extract` stage.
- Perform cabal.project trickery on post-patch stage to allow users to fiddle
  with the original one before creation.
- Document some code.

Mk/Uses/cabal.mk

@@ -36,19 +36,27 @@
 #  FOO_DATADIR_VARS     Additional environment vars to add to FOO executable's
 #                       wrapper script.
 #
+#  CABAL_PROJECT	Sets how to treat existing cabal.project file. Possible
+#			values are "remove" and "append".
+#
 # MAINTAINER: haskell@FreeBSD.org
 
 .if !defined(_INCLUDE_USES_CABAL_MK)
 _INCLUDE_USES_CABAL_MK=    yes
 
-_valid_ARGS=	hpack nodefault
+_valid_ARGS=			hpack nodefault
+_cabal_project_valid_VALUES=	append remove
 
 .  for arg in ${cabal_ARGS}
 .    if !${_valid_ARGS:M${arg}}
 IGNORE=		USES=cabal: invalid arguments: ${arg}
 .    endif
 .  endfor
 
+.  if defined(CABAL_PROJECT) && !${_cabal_project_valid_VALUES:M${CABAL_PROJECT}}
+IGNORE=		CABAL_PROJECT: invalid value: ${CABAL_PROJECT}
+.  endif
+
 PKGNAMEPREFIX?=	hs-
 
 EXECUTABLES?=	${PORTNAME}
@@ -57,6 +65,8 @@ CABAL_HOME=	${WRKDIR}/cabal-home
 CABAL_LIBEXEC=	libexec/cabal
 CABAL_EXTRACT_SUFX=	.tar.gz
 CABAL_ARCH=	${ARCH:S/amd64/x86_64/:C/armv.*/arm/:S/powerpc64/ppc64/}
+CABAL_DEPSDIR=	${WRKSRC}/${CABAL_DEPS_SUBDIR}
+CABAL_DEPS_SUBDIR=	_cabal_deps
 
 .  if !defined(CABAL_BOOTSTRAP)
 BUILD_DEPENDS+=	cabal:devel/hs-cabal-install \
@@ -97,6 +107,7 @@ EXTRACT_ONLY+=	${DISTNAME}${_GITLAB_EXTRACT_SUFX}
 
 _USES_extract=	701:cabal-post-extract
 _USES_patch=	701:cabal-post-patch
+_USES_configure=301:cabal-pre-configure
 _USES_stage=	751:cabal-post-install-script
 
 BUILD_TARGET?=	${EXECUTABLES:S/^/exe:&/}
@@ -127,6 +138,8 @@ DISTFILES+=	${package:C/_[0-9]+//}/revision/${package:C/[^_]*//:S/_//}.cabal:${p
 .  endfor
 
 
+# Auxiliary targets used during port creation/updating.
+
 # Fetches and unpacks package source from Hackage using only PORTNAME and PORTVERSION.
 cabal-extract: ${WRKDIR}
 	${RM} -rf ${CABAL_HOME}/.cabal
@@ -170,21 +183,48 @@ make-use-cabal-revs:
 
 .  if !defined(CABAL_BOOTSTRAP)
 
+# Main targets implementation.
+
 cabal-post-extract:
-	@/bin/test ! -f ${WRKSRC}/cabal.project || (echo "cabal.project file already present in WRKSRC!" && false)
-	echo -n "packages: . " > ${WRKSRC}/cabal.project
+# Remove the project file as requested
+.    if "${CABAL_PROJECT}" == "remove"
+	${RM} ${WRKSRC}/cabal.project
+.    endif
+# Save the original project file so that users can patch them
+.    if "${CABAL_PROJECT}" == "append"
+	${MV} ${WRKSRC}/cabal.project ${WRKSRC}/cabal.project.${PORTNAME}
+.    endif
+
+	@/bin/test ! -f ${WRKSRC}/cabal.project || (echo "cabal.project file is already present in WRKSRC! Set CABAL_PROJECT variable." && false)
+
+# Move extracted dependencies into ${CABAL_DEPSDIR} directory
+	${MKDIR} ${CABAL_DEPSDIR}
 .    for package in ${_use_cabal}
-	echo -n "${package:C/_[0-9]+//} " >> ${WRKSRC}/cabal.project
+# Copy revised .cabal file if present
 .      if ${package:C/[^_]*//:S/_//} != ""
 		cp ${DISTDIR}/${DIST_SUBDIR}/${package:C/_[0-9]+//}/revision/${package:C/[^_]*//:S/_//}.cabal `find ${WRKDIR}/${package:C/_[0-9]+//} -name '*.cabal' -depth 1`
 .      endif
+# Move the dependency source itself
 	cd ${WRKDIR} && \
-		mv ${package:C/_[0-9]+//} ${WRKSRC}/
+		mv ${package:C/_[0-9]+//} ${CABAL_DEPSDIR}/
 .    endfor
-	mkdir -p ${CABAL_HOME}/.cabal
-	echo "jobs: ${MAKE_JOBS_NUMBER}" > ${CABAL_HOME}/.cabal/config
+# Create the cabal-install config
+	${MKDIR} ${CABAL_HOME}/.cabal
+	${ECHO_CMD} "jobs: ${MAKE_JOBS_NUMBER}" > ${CABAL_HOME}/.cabal/config
 
 cabal-post-patch:
+# Create our own cabal.project
+	${ECHO_CMD} "packages: ." > ${WRKSRC}/cabal.project
+.    for package in ${_use_cabal}
+	${ECHO_CMD} "        ${CABAL_DEPS_SUBDIR}/${package:C/_[0-9]+//}" >> ${WRKSRC}/cabal.project
+.    endfor
+# Append the (possibly patched) original cabal.project, if requested
+.    if "${CABAL_PROJECT}" == "append"
+	${CAT} ${WRKSRC}/cabal.project.${PORTNAME} >> ${WRKSRC}/cabal.project
+.    endif
+
+cabal-pre-configure:
+# Generate .cabal file with hpack if requested
 .    if ${cabal_ARGS:Mhpack}
 	cd ${WRKSRC} && ${SETENV} HOME=${CABAL_HOME} hpack
 .    endif