git: 4f16184d81 - main - Porter's handbook: Document USES=guile

The branch main has been updated by carlavilla:

URL: https://cgit.FreeBSD.org/doc/commit/?id=4f16184d81f1c02196d91e8d2511f23fd48e8822

commit 4f16184d81f1c02196d91e8d2511f23fd48e8822
Author:     Andrew RhodiumToad Gierth <[email protected]>
AuthorDate: 2023-08-03 09:40:34 +0000
Commit:     Sergio Carlavilla Delgado <[email protected]>
CommitDate: 2023-08-03 09:40:34 +0000

    Porter's handbook: Document USES=guile
    
    Approved by:            fernape(ports), carlavilla(doc)
    Reviewed by:            Pau Amma <[email protected]>
    Differential Revision:  https://reviews.freebsd.org/D41285
---
 .../en/books/porters-handbook/flavors/_index.adoc  |  13 ++
 .../en/books/porters-handbook/special/_index.adoc  | 238 +++++++++++++++++++++
 .../en/books/porters-handbook/uses/_index.adoc     |  17 ++
 3 files changed, 268 insertions(+)

diff --git a/documentation/content/en/books/porters-handbook/flavors/_index.adoc b/documentation/content/en/books/porters-handbook/flavors/_index.adoc
index 47d78b0dd4..fb6ef8bc35 100644
--- a/documentation/content/en/books/porters-handbook/flavors/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/flavors/_index.adoc
@@ -362,3 +362,16 @@ most applications that embed or otherwise use Lua should simply use `USES=lua`.
 `LUA_FLAVOR` is available (and must be used) to depend on the correct version of dependencies regardless of whether the port used the `flavors` or `module` parameters.
 
 See crossref:special[using-lua,Using Lua] for further information.
+
+[[flavors-auto-guile]]
+== `USES=guile` and Flavors
+
+When using crossref:uses[uses-guile,`guile:flavors`],
+the port will automatically have `FLAVORS` filled in with the Guile versions it supports.
+However, it is not expected that ordinary applications should use this feature;
+it is primarily intended for use by libraries and extensions,
+such as `guile-lib` or `guile-cairo`.
+
+`GUILE_FLAVOR` is available (and must be used) to depend on the correct version of flavored dependencies regardless of whether the port used the `flavors` parameter or not.
+
+See crossref:special[using-guile,Using Guile] for further information.
diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc
index 32123e82a9..8bafbfbf1a 100644
--- a/documentation/content/en/books/porters-handbook/special/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/special/_index.adoc
@@ -4236,6 +4236,244 @@ DOCSDIR=	${LUA_DOCSDIR}
 
 ====
 
+[[using-guile]]
+== Using Guile
+
+This section describes the status of Guile in the ports tree and its integration with the ports system.
+
+[[guile-introduction]]
+=== Introduction
+
+There are multiple versions of the Guile libraries and corresponding interpreters, which conflict between them (install files under the same name).
+In the ports tree this problem has been solved by installing each version under a different name using version number suffixes.
+In most cases, applications should detect the correct version from the configuration variables provided and use `pkg-config` to determine the name and associated paths.
+However, some applications (especially those using their own configuration rules for `cmake` or `meson`) will always try to use the latest available version.
+In this case, either patch the port or declare a build conflict (see the `conflicts` option below) to ensure that the correct dependency is generated when building outside of poudriere.
+
+Applications that use Guile should normally build for just one version,
+preferably the one specified in `DEFAULT_VERSIONS`,
+or failing that the latest version that they support.
+However, Guile or Scheme libraries, or extension modules for Guile are built in a separate flavor for each Guile version that they support,
+and dependencies on such ports should specify the flavor using the `@${GUILE_FLAVOR}` suffix on the port origin.
+
+[[guile-version]]
+=== Version Selection
+
+A port using Guile should define `USES=guile:__arg,arg...__` with appropriate arguments as follows:
+
+[[guile-defined-uses-args]]
+.Arguments Defined for Ports That Use Guile
+[cols="1m,4", frame="none", options="header"]
+|===
+| Name
+| Description
+
+|_X.Y_
+|Declare compatibility with Guile version `X.Y`.
+Currently available versions are `1.8` (obsolete), `2.2` and `3.0`.
+Multiple versions may be specified.
+
+|flavors
+|Create a flavor for every Guile version specified.
+The version specified by `DEFAULT_VERSIONS` will become the default flavor.
+Flavor names are of the form `guileXY`.
+
+|build
+|Add the Guile interpreter as a build dependency only, rather than a library dependency.
+`build` and `run` may both be specified.
+
+|run
+|Add the Guile interpreter as a runtime dependency only, rather than a library dependency.
+`build` and `run` may both be specified.
+
+|alias
+|Add `BINARY_ALIAS` values for the interpreter and tools.
+
+|conflicts
+|Declare `CONFLICTS_BUILD` for Guile versions newer than the one selected.
+Use this when the port cannot be configured to use a specific Guile version.
+|===
+
+Some additional arguments are available for handling unusual cases; see `Mk/Uses/guile.mk` for details.
+
+Unless `build` or `run` is specified, then `LIB_DEPENDS` receives both the `libguile` library dependency and also any additional dependencies required by the guile version, e.g. `libgc`.
+Normally the port should not need any additional dependencies related to its use of Guile.
+
+[[guile-version-config]]
+=== Configuration flags
+
+Software that uses Guile should be using the `pkg-config` mechanism to obtain compiler and linker flags.
+Some older or esoteric ports may be using `guile-config` or obtaining values directly from `guile` instead,
+which should also work (the `alias` argument may be useful in some of these cases).
+
+The framework tries to inform the port of the desired Guile version using the following methods:
+
+* `GUILE_EFFECTIVE_VERSION` is added to `CONFIGURE_ENV`;
+* The full path to the Guile binary is specified in the `GUILE` variable in `CONFIGURE_ENV` and `MAKE_ENV`;
+* If the `alias` option is used, the desired Guile version's binaries are the ones aliased;
+* If the `alias` option is not used, paths to the desired Guile version's tools (`guild`, `guile-config`, etc.) are added to `CONFIGURE_ENV` and `MAKE_ENV` as variables `GUILD`, `GUILE_CONFIG`, etc.
+
+For some ports, it may be necessary to specify the version in additional ways, such as via `CONFIGURE_ARGS` or `MESON_ARGS`,
+depending on the port.
+
+If none of these methods cause the port to select the specified Guile version when other versions are present,
+then preferably patch it to do so.
+If that is not feasible, specify the `conflicts` option to prevent building the port under conditions where it will detect the wrong version.
+
+[[guile-version-flavors]]
+=== Version Flavors
+
+A port which installs a Guile extension or library, or a Scheme library that precompiles for Guile,
+should build a separate flavor for each supported Guile version.
+This is done by adding the `flavors` option.
+
+Since each flavor must have a different package name, such ports must set `PKGNAMESUFFIX`, typically:
+
+[.programlisting]
+....
+PKGNAMESUFFIX=	-${FLAVOR}
+....
+
+Such ports must install Scheme files to `GUILE_SITE_DIR` rather than to `GUILE_GLOBAL_SITE_DIR` even when the files are not version-specific.
+This often requires patching the port.
+
+Additionally, if such a port installs a `.pc` file, it must be placed in `GUILE_PKGCONFIG_PATH` rather than in the global `pkgconfig` directory.
+This allows dependent ports to find a correct configuration for the specific Guile version in use.
+
+If a Guile extension port installs a `.so` file, then it must usually be placed in the Guile-version-specific `extensions` directory.
+`USE_LDCONFIG` should usually not be used.
+
+Any other files installed by a flavored port must likewise be in version-specific directories or use version-specific filenames.
+For documentation and examples, `GUILE_DOCS_DIR` and `GUILE_EXAMPLES_DIR` specify suitable locations in which the port should create a subdirectory,
+see below.
+
+[[guile-defined-variables]]
+=== Defined Variables
+
+These variables are available in the port.
+
+[[using-guile-variables-ports]]
+.Variables Defined for Ports That Use Guile
+[cols="1,3m,6", frame="none", options="header"]
+|===
+| Name
+| Sample Value
+| Description
+
+|`GUILE_VER`
+|3.0
+|Guile version in use.
+
+|`GUILE_SFX`
+|3
+|Short suffix used on some names.
+Use only with care; may be non-unique or may change in the future.
+
+|`GUILE_FLAVOR`
+|guile30
+|Flavor name corresponding to the selected version.
+
+|`GUILE_PORT`
+|lang/guile3
+|Port origin of the specified Guile version.
+
+|`GUILE_PREFIX`
+|${PREFIX}
+|Directory prefix to be used for installation.
+
+|`GUILE_CMD`
+|guile-3.0
+|Name of the Guile interpreter, with version suffix.
+
+|`GUILE_CMDPATH`
+|${LOCALBASE}/bin/guile-3.0
+|Full path to the Guile interpreter.
+
+|`GUILD_CMD`
+|guild-3.0
+|Name of the Guild tool, with version suffix.
+
+|`GUILD_CMDPATH`
+|${LOCALBASE}/bin/guild-3.0
+|Full path to the Guild tool.
+
+|`++GUILE_*_CMD++` +
+`++GUILE_*_CMDPATH++`
+|
+|Like `GUILE_CMD` and `GUILE_CMDPATH`, but for other tool binaries.
+
+|`GUILE_PKGCONFIG_PATH`
+|${LOCALBASE}/libdata/pkgconfig/guile/3.0
+|Where packages using `flavors` should install `.pc` files.
+
+|`GUILE_INFO_PATH`
+|share/info/guile3
+|A suitable value for `INFO_PATH` for ports using the `flavors` option.
+|===
+
+The following are defined as variables and as `PLIST_SUB` entries.
+The variable form is suffixed with `_DIR` and is a full path (prefixed with `GUILE_PREFIX`).
+
+[[using-guile-path-variables-ports]]
+.Path Substitutions Defined for Ports That Use Guile
+[cols="1m,3m,6", frame="none", options="header"]
+|===
+| Name
+| Sample Value
+| Description
+
+|GUILE_GLOBAL_SITE
+|share/guile/site
+|Site directory shared by all guile versions; this should not usually be used.
+
+|GUILE_SITE
+|share/guile/3.0/site
+|Site directory for the selected Guile version.
+
+|GUILE_SITE_CCACHE
+|lib/guile/3.0/site-ccache
+|Directory for compiled bytecode files.
+
+|GUILE_DOCS
+|share/doc/guile30
+|Parent directory for version-specific documentation.
+
+|GUILE_EXAMPLES
+|share/examples/guile30
+|Parent directory for version-specific examples.
+|===
+
+[[guile-examples]]
+=== Examples
+
+[[guile-app-Makefile]]
+.Makefile for an application using Guile
+[example]
+====
+This example shows how to reference a Guile library required at build and run time.
+Notice that the reference must specify a flavor.
+This example assumes that the application is using `pkg-config` to locate dependencies.
+
+[.programlisting]
+....
+PORTNAME=	sample
+DISTVERSION=	1.2.3
+CATEGORIES=	whatever
+
+MAINTAINER=	[email protected]
+COMMENT=	Sample
+WWW=		https://example.com/guile_sample/sample/
+
+BUILD_DEPENDS=	guile-lib-${GUILE_FLAVOR}>=0.2.5:devel/guile-lib@${GUILE_FLAVOR}
+RUN_DEPENDS=	guile-lib-${GUILE_FLAVOR}>=0.2.5:devel/guile-lib@${GUILE_FLAVOR}
+
+USES=		guile:2.2,3.0 pkgconfig
+
+.include <bsd.port.mk>
+....
+
+====
+
 [[using-iconv]]
 == Using `iconv`
 
diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc
index 5a357f42a7..1387cb6254 100644
--- a/documentation/content/en/books/porters-handbook/uses/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc
@@ -920,6 +920,23 @@ The available components are:
 * `ximagesrc`
 * `zbar`
 
+[[uses-guile]]
+== `guile`
+
+Possible arguments: (none), `_X.Y_`, `flavors`, `build`, `run`, `alias`, `conflicts`
+
+Adds a dependency on Guile.
+By default this is a library dependency on the appropriate `libguile*.so`, unless overridden by the `build` and/or `run` option.
+The `alias` option configures `BINARY_ALIAS` appropriately (see crossref:makefiles[binary-alias,Use `BINARY_ALIAS`]).
+
+The default version is set by the usual `DEFAULT_VERSIONS` mechanism;
+if the default version is not one of the listed versions, then the latest available listed version is used.
+
+Applications using Guile are normally built for only a single Guile version.
+However, extension or library modules should use the `flavors` option to build with multiple flavors.
+
+For more information see crossref:special[using-guile,Using Guile].
+
 [[uses-horde]]
 == `horde`