split off the large module documentations, so that port-modules is less of

a monster.

okay sthen@

1 files changed, 152 insertions, 0 deletions

diff --git a/share/man/man5/python-module.5 b/share/man/man5/python-module.5
new file mode 100644
index 00000000000..634c1e67171
--- /dev/null
+++ b/share/man/man5/python-module.5
@@ -0,0 +1,152 @@
+.\"	$OpenBSD: python-module.5,v 1.1 2021/02/25 09:13:18 espie Exp $
+.\"
+.\" Copyright (c) 2008 Marc Espie
+.\"
+.\" 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: February 25 2021 $
+.Dt PYTHON-MODULE 5
+.Os
+.Sh NAME
+.Nm python-module
+.Nd lang/python port module
+.Sh DESCRIPTION
+This manual page documents the behavior of setting
+.Li MODULE=lang/python
+in the
+.Xr ports 7
+tree.
+.Pp
+Sets
+.Ev MODPY_VERSION ,
+.Ev MODPY_BIN ,
+.Ev MODPY_INCDIR ,
+.Ev MODPY_LIBDIR ,
+.Ev MODPY_SITEPKG ,
+.Ev MODPY_SETUP ,
+.Ev MODPY_TEST_DIR ,
+.Ev MODPY_TEST_LOCALE ,
+.Ev MODPY_WANTLIB ,
+.Ev MODPY_LIB_DEPENDS ,
+.Ev MODPY_RUN_DEPENDS ,
+.Ev MODPY_TEST_DEPENDS ,
+.Ev MODPY_BUILD_DEPENDS ,
+and
+.Ev MODPY_ADJ_FILES .
+Appends to
+.Ev RUN_DEPENDS
+unless
+.Ev MODPY_RUNDEP
+is set to No.
+Appends to
+.Ev BUILD_DEPENDS
+unless
+.Ev MODPY_BUILDDEP
+is set to No or
+.Ev NO_BUILD
+is set to Yes.
+Appends to
+.Ev TEST_DEPENDS
+if
+.Ev MODPY_PYTEST
+is set to Yes
+unless
+.Ev MODPY_TESTDEP
+is set to No.
+Appends
+.Ev MODPY_TEST_LOCALE
+to
+.Ev TEST_ENV .
+Changes to the directory specified in
+.Ev MODPY_TEST_DIR ,
+by default WRKSRC, before running tests.
+.Ev MODPY_VERSION
+is the default version used by all python modules.
+Ports which use the setuptools module should set
+.Ev MODPY_SETUPTOOLS
+to Yes.
+Ports which use the pytest module should set
+.Ev MODPY_PYTEST
+to Yes.
+Arguments can be passed to pytest during
+.Cm test
+with
+.Ev MODPY_PYTEST_ARGS .
+All ports that generate egg-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 .
+If any files have a python shebang line which needs to be replaced
+using MODPY_BIN, list them in
+.Ev MODPY_ADJ_FILES .
+These are prefixed with WRKSRC and replaced automatically
+at the end of
+.Cm pre-configure .
+Also affects
+.Ev CATEGORIES ,
+.Ev MAKE_ENV ,
+.Ev CONFIGURE_ENV ,
+and
+.Ev SUBST_VARS .
+May affect the
+.Cm test
+target.
+If
+.Ev MODPY_PI
+is set to Yes it will set
+.Ev HOMEPAGE
+and
+.Ev MASTER_SITES .
+The subdirectory can be overridden with
+.Ev MODPY_PI_DIR .
+.Pp
+Python 2.x places .pyc files in the same directory as the associated .py file.
+Python 3.x places these in a separate __pycache__ directory and uses an
+additional suffix.
+In some cases, an ABI tag is also used for names of compiled extensions.
+The python module defines variables to allow a single PLIST to be
+used for both versions.
+Generate or update the PLIST using the python3
+.Ev FLAVOR ,
+then edit it to prefix any lines creating
+.Ev MODPY_PYCACHE
+directories with
+.Ev MODPY_COMMENT .
+As python2 and python3 packages should permit being installed together,
+it may be necessary to suffix names of common binaries or directories,
+or split common files into a subpackage.
+If updating the PLIST without using the python3 flavor,
+take care not to remove ${MODPY_PYCACHE}, ${MODPY_PYC_MAGIC_TAG}, or
+${MODPY_ABI_TAG} variables from the PLIST.
+.Sh SEE ALSO
+.Xr port-modules 5