From: Sebastien Marie <semarie@kapouay.eu.org>
Subject: opam-module man page
To: tech@openbsd.org
Date: Sat, 15 Feb 2025 09:27:16 +0100

Hi,

I am currently working on adding a man page for the sysutils/opam module.

Any review for formulation (I am not native english person) or mdoc(7)
structuration would be welcome.

Thanks.
-- 
Sebastien Marie

.\"	$OpenBSD$
.\"
.\" Copyright (c) 2025 Sebastien Marie
.\"
.\" 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$
.Dt OPAM-MODULE 5
.Os
.Sh NAME
.Nm opam-module
.Nd sysutils/opam port module
.Sh DESCRIPTION
This manual page documents the behavior of setting
.Li MODULES=sysutils/opam
in the
.Xr ports 7
tree.
.Pp
The module provides helpers for packaging a program using
.Xr opam 1
(OCaml Package Manager).
.Pp
.Ev WRKSRC
is expected to contains opam packages, possibly with local customization.
All .opam files, at any depth, will be registered.
Unmodified dependencies should be omitted, they will be managed separately.
.Pp
To generate a standalone opam repository containing only the dependencies and
the sources files for compiling the specified sources tree,
.Xr make 1
.Cm modopam-repository
target could be used.
It will download an opam repository from
.Ev MODOPAM_REPO_URL
(default to official opam repository hosted on github), using
.Ev MODOPAM_REPO_COMMIT
commit (it is preferable to explicitly specify it for reproductibility,
but "master" is the default value).
The repository will be named according to
.Ev MODOPAM_REPO_NAME
variable.
Next, the repository will be stripped to contains only the build dependencies of
.Ev MODOPAM_PACKAGES_REPOSITORY
(default to
.Ev MODOPAM_PACKAGES ).
And next, the repository will be filled with local cache of package archives.
The resulting directory could be packaged and distributed.
It contains source code for building the opam packages.
.Pp
External dependencies could be hinted using the
.Xr make 1
target
.Cm modopam-external .
The list of packages expected to be present at build time is shown.
.Pp
The module appends to
.Ev BUILD_DEPENDS
unless
.Ev MODOPAM_BUILDDEP
is set to `No'.
.Pp
It sets
.Ev MODOPAM_PACKAGES
variable to
.Ev PKGSTEM ,
as default value for opam packages to build and install.
.Pp
It sets
.Ev MODOPAM_OPAMROOT ,
.Ev MODOPAM_ENV ,
.Ev MODOPAM_OPAM_BIN
and
.Ev MODOPAM_OPAM_RUN
accordingly.
.Pp
The opam options
.Ar --with-doc
and
.Ar --with-test
are available using
.Ev MODOPAM_WITH_DOC
and
.Ev MODOPAM_WITH_TEST .
They defaults to `No'.
.Pp
A
.Ev CONFIGURE_STYLE
"opam" is provided.
It will initialize opam with opam repository at
.Ev MODOPAM_REPO_DIR
(default to
.Pa ${WRKDIR}/${MODOPAM_REPO_NAME} ).
It is expected to have been generated previously by
.Cm modopam-repository
target and distributed separately.
It will also pin the opam packages present in
.Ev WRKSRC ,
possibly overriding opam packages from the repository.
.Pp
A default build target is used (except if
.Ev MODOPAM_BUILD
is set to `No'.
It is using
.Ev MODOPAM_PACKAGES_BUILD
variable to list the opam packages to build (default to
.Ev MODOPAM_PACKAGES ).
.Pp
A default install target is used (except if
.Ev MODOPAM_INSTALL
is set to `No'.
It is using
.Ev MODOPAM_PACKAGES_INSTALL
variable to list the opam packages to install (default to
.Ev MODOPAM_PACKAGES ).
.Sh SEE ALSO
.Xr opam 1 ,
.Xr port-modules 5