From 4b12175a3cdb4e1031383ed7ecf6d5ebb6397340 Mon Sep 17 00:00:00 2001
From: sthen <sthen@openbsd.org>
Date: Tue, 13 Sep 2022 20:56:47 +0000
Subject: [PATCH] add some initial docs for MODPY_PYBUILD, prompted by espie

---
 share/man/man5/python-module.5 | 70 ++++++++++++++++++++++++++--------
 1 file changed, 55 insertions(+), 15 deletions(-)

diff --git a/share/man/man5/python-module.5 b/share/man/man5/python-module.5
index c94a49d324b..1c7ffd26711 100644
--- a/share/man/man5/python-module.5
+++ b/share/man/man5/python-module.5
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: python-module.5,v 1.4 2022/03/31 17:27:23 naddy Exp $
+.\"	$OpenBSD: python-module.5,v 1.5 2022/09/13 20:56:47 sthen Exp $
 .\"
 .\" Copyright (c) 2008 Marc Espie
 .\"
@@ -24,7 +24,7 @@
 .\" (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: March 31 2022 $
+.Dd $Mdocdate: September 13 2022 $
 .Dt PYTHON-MODULE 5
 .Os
 .Sh NAME
@@ -44,7 +44,7 @@ to the appropriate python version
 depending on the existence/presence of a
 .Sq python3
 .Ev FLAVOR
-.Pc .
+.Pc ,
 but
 .Ev MODPY_VERSION
 may be set manually to ${MODPY_DEFAULT_VERSION_2}
@@ -102,32 +102,72 @@ by default ${WRKSRC}
 .Pc
 before running tests.
 .Pp
-Ports which use the setuptools module should set
+Most modern Python software can be packaged using a PEP 517 build
+frontend (in the
+.Pa devel/py-build
+port).
+To use this, set
+.Ev MODPY_PYBUILD
+to the name of the build backend.
+If the port provides a
+.Pa pyproject.toml
+file, check the "build-backend" line in the [build-system] section.
+.Nm
+currently supports flit_core, hatchling, poetry-core, setuptools
+and setuptools_scm.
+If no
+.Pa pyproject.toml
+is provided then it probably uses setuptools.
+Setting
+.Ev MODPY_PYBUILD
+adds the backend to
+.Ev MODPY_BUILD_DEPENDS ,
+and sets
+.Ev MODPY_PYTEST .
+In rare cases, the build backend is distributed with the software
+itself and
+.Ev MODPY_PYBUILD
+can be set to Yes to use this mechanism without adding a dependency
+for another backend.
+.Pp
+Older ports using setuptools still set
 .Ev MODPY_SETUPTOOLS
-to Yes.
+to Yes, which appends to
+.Ev MODPY_BUILD_DEPENDS
+and calls the relevant commands to build (these ports are built
+using the deprecated mechanism of calling
+.Pa setup.py
+directly).
+Arguments can be passed to setup.py during
+.Cm configure
+with
+.Ev MODPY_SETUP_ARGS .
+Extra arguments to the build and install commands can be passed via
+.Ev MODPY_DISTUTILS_BUILDARGS
+and
+.Ev MODPY_DISTUTILS_INSTALLARGS .
+These ports can often be converted to
+.Ev MODPY_PYBUILD
+with some small changes to the port.
 .Pp
 Ports which use the pytest module should set
 .Ev MODPY_PYTEST
 to Yes.
+This is set automatically for builds using
+.Ev MODPY_PYBUILD .
 Arguments can be passed to pytest during
 .Cm test
 with
 .Ev MODPY_PYTEST_ARGS .
 .Pp
-All ports that generate egg-info files should set
+All ports that generate egg-info or dist-info files should set
 .Ev MODPY_EGG_VERSION
 to the version string used by the
 .Fn setup
 function in the port's
-.Pa setup.py .
-Arguments can be passed to setup.py during
-.Cm configure
-with
-.Ev MODPY_SETUP_ARGS .
-Extra arguments to the build and install commands can be passed via
-.Ev MODPY_DISTUTILS_BUILDARGS
-and
-.Ev MODPY_DISTUTILS_INSTALLARGS .
+.Pa setup.py
+or the version in
+.Pa pyproject.toml .
 .Pp
 If any files have a python shebang line where the interpreter should be
 ${MODPY_BIN}, list them in
-- 
2.20.1