CVS commit: pkgsrc/mk

["Masatake Daimon" <pho%netbsd.org@localhost>]

Module Name:    pkgsrc
Committed By:   pho
Date:           Fri Feb 11 05:24:06 UTC 2022

Modified Files:
        pkgsrc/mk: haskell.mk
Added Files:
        pkgsrc/mk/haskell: README.md

Log Message:
Wrote a packaging guide for Haskell packages


To generate a diff of this commit:
cvs rdiff -u -r1.39 -r1.40 pkgsrc/mk/haskell.mk
cvs rdiff -u -r0 -r1.1 pkgsrc/mk/haskell/README.md

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

Modified files:

Index: pkgsrc/mk/haskell.mk
diff -u pkgsrc/mk/haskell.mk:1.39 pkgsrc/mk/haskell.mk:1.40
--- pkgsrc/mk/haskell.mk:1.39   Fri Feb 11 01:11:57 2022
+++ pkgsrc/mk/haskell.mk        Fri Feb 11 05:24:06 2022
@@ -1,9 +1,8 @@
-# $NetBSD: haskell.mk,v 1.39 2022/02/11 01:11:57 pho Exp $
+# $NetBSD: haskell.mk,v 1.40 2022/02/11 05:24:06 pho Exp $
 #
-# This Makefile fragment handles Haskell Cabal packages.
-# Package configuration, building, installation, registration and
-# unregistration are fully automated.
-# See https://www.haskell.org/cabal/.
+# This Makefile fragment handles Haskell Cabal packages. Package
+# configuration, building, installation, registration and unregistration
+# are fully automated. See also mk/haskell/README.md for a packaging guide.
 #
 # Package-settable variables:
 #

Added files:

Index: pkgsrc/mk/haskell/README.md
diff -u /dev/null pkgsrc/mk/haskell/README.md:1.1
--- /dev/null   Fri Feb 11 05:24:06 2022
+++ pkgsrc/mk/haskell/README.md Fri Feb 11 05:24:06 2022
@@ -0,0 +1,78 @@
+<!-- $NetBSD: README.md,v 1.1 2022/02/11 05:24:06 pho Exp $ -->
+
+# Packaging guide for Haskell packages
+
+## `PKGNAME`
+
+Packages that only make sense to be implemented in Haskell should have a
+prefix `hs-` to avoid conflicts with non-Haskell packages. Libraries fall
+into this category. Packages that install both a library and executables
+also fall into this, if their libraries are the main body and their
+executables are supplemental. `mk/haskell.mk` prepends the prefix by
+default.
+
+Packages that happen to be implemented in Haskell but could have been done
+otherwise should not have the prefix `hs-`. Applications fall into this
+category. Packages that install libraries too also fall into this, if their
+executables are the main body. You can remove the prefix by declaring this
+in your `Makefile`:
+
+```
+PKGNAME=       ${DISTNAME}
+```
+
+
+## Tools
+
+Some packages have build-time dependencies on external tools, which are
+typically Haskell source preprocessors. At the time of this writing the
+following tools are available via the variable `USE_TOOLS`:
+
+* pkg-config (which isn't specific to Haskell of course)
+* alex
+* cpphs
+* happy
+
+`mk/haskell.mk` generates dummy scripts for these tools by default, which
+unconditionally aborts the build with an error message. This is to prevent
+packages from silently depending on the tools.
+
+
+## `buildlink3.mk`
+
+Packages with the prefix `hs-` should have `buildlink3.mk` like this:
+
+```
+BUILDLINK_TREE+=       hs-distributive
+
+.if !defined(HS_DISTRIBUTIVE_BUILDLINK3_MK)
+HS_DISTRIBUTIVE_BUILDLINK3_MK:=
+
+BUILDLINK_API_DEPENDS.hs-distributive+=        hs-distributive>=0.6.2
+BUILDLINK_ABI_DEPENDS.hs-distributive+=        hs-distributive>=0.6.2.1nb2
+BUILDLINK_PKGSRCDIR.hs-distributive?=  ../../math/hs-distributive
+
+.include "../../devel/hs-base-orphans/buildlink3.mk"
+.include "../../math/hs-semigroups/buildlink3.mk"
+.include "../../devel/hs-tagged/buildlink3.mk"
+.endif # HS_DISTRIBUTIVE_BUILDLINK3_MK
+
+BUILDLINK_TREE+=       -hs-distributive
+```
+
+This is a `buildlink3.mk` for a package `math/hs-distributive` version
+`0.6.2.1`. The important part of this is that `buildlink3.mk` should have
+both `BUILDLINK_API_DEPENDS.*` and `BUILDLINK_ABI_DEPENDS.*`. The latter
+should be set to the exact version of the package because a Haskell
+package, once compiled, can provide absolutely zero ABI compatibility with
+any other versions of the same package.
+
+`BUILDLINK_API_DEPENDS.*` should have up to three version components but
+not more. This is because every Haskell package is supposed to follow [the
+versioning policy described here](https://pvp.haskell.org/). That is, for a
+version `A.B.C.D` the first two components `A.B` describes a major API
+version, whose change indicates a breaking one. The third component `C`
+desibes a minor API version whose change indicates a non-breaking API
+change. The fourth component `D` describes a patch version which introduces
+no API changes. It therefore doesn't make sense to include `D` in our
+`BUILDLINK_API_DEPENDS.*`.