From nobody Thu Aug 03 09:43:45 2023 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4RGkSL0nWKzZSBJ for ; Thu, 3 Aug 2023 09:43:46 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4RGkSL014Bz3HZM; Thu, 3 Aug 2023 09:43:46 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1691055826; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=/MQ7L8GXMXjLQ29rKHthGZq1K1Lra5UOoYawqiNja9U=; b=aSUZ9dGGtd5IzMMshZgXh0YyRhOY3UrDBQmPEl5nzFZ4nzX3wgb1w0tZTBW6uPby0NHIhR hm7FskKTTyFPjKPVfl9eIf7PC7QRDrwA+e0WRr2wQ/zx9yS25NbHtZr9GMDZwIqdquzJfO Q6jqlAsQcYvo2k1F4ep2s1y9Ac1kim6bSteH+3mJf2kgwot+Gn3b30lnfdstH1UgmAsCA+ zUvWohyarHpiVZXNTbV4ML4QLOlHys+zicWlAsyHA5WBWN0jouFbaIL/MLd8eYH4/3Yb8w 0d7grGG1Bd7BzvtuVP8Ixz4ebjAsEvmxLbZ3CbcGSiFMByqNgkIXu9bSKxpWQQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1691055826; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=/MQ7L8GXMXjLQ29rKHthGZq1K1Lra5UOoYawqiNja9U=; b=A4J7dmNmchDvf7x2boaebrhhPOEhP3Y5ozvJTEAGvOWpIigDMzLG3mssWigUSpsuEY17oO 3SNlrekmikySXF1x75aMX92Z6zFD575JDYpuoeIdaQwzeiWYb+NZzYlqSHzcHCJi9UvSLK rnfFB/Ob/Q8Hz0dwdkvlzTO4ICDizCFOBEuG+O3IjrPvm/C3hB7miTTA+inFSqSTtNyMFg 3OoQp7+ID9dzhw+oXJRgKp4NyuY+7s5SEMr5k3whNHmwuXgD/sxtp52I7dSfl+ynFDNTko gFUVqIHNjd5gRcByHYK8tVEq00zaJ9UEyiJA0dr87kMk1V/sG+BoK5+PVA+tVg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1691055826; a=rsa-sha256; cv=none; b=elZgENZgsYxZeFu8KXcPLddBPAdnknHHiOpqwC6pkVuLmrEK99BJKwwCEWJvLbONwncAYq HzgSYyvAr/h5oSRy+YRk2Zlv/EOVY5mC1jzUOzTtsk67NPGR//8x9bm008guCASW8lJGZy WOY+0Eh4XJjzgIztNCXeh6jsjhGP7HpM6SMVstanO2ElpHA4MEBn3IjenjkgcaotxuJbOo G/UFGFRPaJgN3WBrV4Sxj+yiaHwEwX7wLW9FDFu/uEO1jmJ4XyCRuZjvetsRnnpQJf6BL3 Xtg4CQonuRCtUXPAH+PXNnrtBVMaP7R0JIPPcnUg30jWEE0y+HXHYF89Za9YMg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4RGkSK69T9z1g4; Thu, 3 Aug 2023 09:43:45 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 3739hjfE059117; Thu, 3 Aug 2023 09:43:45 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 3739hjYg059116; Thu, 3 Aug 2023 09:43:45 GMT (envelope-from git) Date: Thu, 3 Aug 2023 09:43:45 GMT Message-Id: <202308030943.3739hjYg059116@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Sergio Carlavilla Delgado Subject: git: 4f16184d81 - main - Porter's handbook: Document USES=guile List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-doc-all@freebsd.org X-BeenThere: dev-commits-doc-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: carlavilla X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 4f16184d81f1c02196d91e8d2511f23fd48e8822 Auto-Submitted: auto-generated The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=4f16184d81f1c02196d91e8d2511f23fd48e8822 commit 4f16184d81f1c02196d91e8d2511f23fd48e8822 Author: Andrew RhodiumToad Gierth AuthorDate: 2023-08-03 09:40:34 +0000 Commit: Sergio Carlavilla Delgado CommitDate: 2023-08-03 09:40:34 +0000 Porter's handbook: Document USES=guile Approved by: fernape(ports), carlavilla(doc) Reviewed by: Pau Amma 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= 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 +.... + +==== + [[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`