diff options
author | Andrew RhodiumToad Gierth <andrew@tao11.riddles.org.uk> | 2023-08-03 09:40:34 +0000 |
---|---|---|
committer | Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> | 2023-08-03 09:40:34 +0000 |
commit | 4f16184d81f1c02196d91e8d2511f23fd48e8822 (patch) | |
tree | 6f0958cac2936ab008a2091af0fd25a16315b978 | |
parent | 7af27acb5ce859b9005686bbefa01b7d922a5a86 (diff) | |
download | doc-4f16184d81f1c02196d91e8d2511f23fd48e8822.tar.gz doc-4f16184d81f1c02196d91e8d2511f23fd48e8822.zip |
Porter's handbook: Document USES=guile
Approved by: fernape(ports), carlavilla(doc)
Reviewed by: Pau Amma <pauamma@gundo.com>
Differential Revision: https://reviews.freebsd.org/D41285
3 files changed, 268 insertions, 0 deletions
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= fred.bloggs@example.com +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` |