<pre style='margin:0'>
Joshua Root (jmroot) pushed a commit to branch master
in repository macports-guide.
</pre>
<p><a href="https://github.com/macports/macports-guide/commit/867c12e123e6ec3aa5c5c95b7b77b828d4c0ab3d">https://github.com/macports/macports-guide/commit/867c12e123e6ec3aa5c5c95b7b77b828d4c0ab3d</a></p>
<pre style="white-space: pre; background: #F8F8F8"><span style='display:block; white-space:pre;color:#808000;'>commit 867c12e123e6ec3aa5c5c95b7b77b828d4c0ab3d
</span>Author: Joshua Root <jmr@macports.org>
AuthorDate: Tue Nov 1 02:48:17 2022 +1100
<span style='display:block; white-space:pre;color:#404040;'> Document known_fail and new platforms syntax
</span><span style='display:block; white-space:pre;color:#404040;'>
</span><span style='display:block; white-space:pre;color:#404040;'> Fixes: https://trac.macports.org/ticket/59640
</span>---
guide/xml/portfile-keywords.xml | 79 +++++++++++++++++++++++++++++++++++++----
1 file changed, 72 insertions(+), 7 deletions(-)
<span style='display:block; white-space:pre;color:#808080;'>diff --git a/guide/xml/portfile-keywords.xml b/guide/xml/portfile-keywords.xml
</span><span style='display:block; white-space:pre;color:#808080;'>index ab9cb17..4a0a859 100644
</span><span style='display:block; white-space:pre;background:#e0e0ff;'>--- a/guide/xml/portfile-keywords.xml
</span><span style='display:block; white-space:pre;background:#e0e0ff;'>+++ b/guide/xml/portfile-keywords.xml
</span><span style='display:block; white-space:pre;background:#e0e0e0;'>@@ -363,8 +363,9 @@
</span>
<listitem>
<para>A list of the platforms on which the port is expected to work.
<span style='display:block; white-space:pre;background:#ffe0e0;'>- Required, but not interpreted in any way by MacPorts at this time; it is
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- purely informational for users. Possible values:</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ Defaults to <literal>darwin</literal> if not set. Consists of a list of
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ platform specifiers, each of which is at minimum a platform name and
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ may also include version information. Possible platform names are:</para>
</span>
<itemizedlist>
<listitem>
<span style='display:block; white-space:pre;background:#e0e0e0;'>@@ -399,17 +400,63 @@
</span> </listitem>
</itemizedlist>
<span style='display:block; white-space:pre;background:#ffe0e0;'>- <para>Ports for software that does not require macOS-specific features
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- should use <literal>darwin</literal>. Most ports use this value on the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>A platform specifier that is just a platform name is purely
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ informational for users; it is displayed in the output of <code>port info</code>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ but has no other effect.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ Ports for software that does not require macOS-specific features
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ can generally use the default value of <literal>darwin</literal>. Most
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ ports use this value on the
</span> presumption that they would work on Pure Darwin, even if that has not
been attempted. Ports for software that is known to require
<span style='display:block; white-space:pre;background:#ffe0e0;'>- macOS-specific features should set this to <literal>macosx</literal>.
</span><span style='display:block; white-space:pre;background:#ffe0e0;'>- Including the xcode portgroup will set this to <literal>macosx</literal>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ macOS-specific features should use <literal>macosx</literal>.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ Including the xcode portgroup will change the default to <literal>macosx</literal>
</span> automatically.</para>
<para>See also <varname>os.platform</varname>.</para>
<span style='display:block; white-space:pre;background:#ffe0e0;'>- <programlisting>platforms darwin</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <programlisting>platforms macosx freebsd</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>(Added: MacPorts 2.8.0) A platform specifier can also be a list, where
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ the first element is a platform name and subsequent elements are pairs of
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ comparison operators and versions. This indicates the version ranges of each
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ platform that the port works on.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>If a platform specifier's name matches <code>${os.platform}</code>, then
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ each comparison operator in the specifier is applied to <code>${os.version}</code>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ as the left operand and the listed version as the right operand. If any of the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ comparisons evaluate to false, then the default value of <code>known_fail</code>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ is changed to <literal>yes</literal>.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>Possible operators are: <code><</code>, <code><=</code>,
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <code>></code>, <code>>=</code>, <code>==</code>, <code>!=</code>.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ The <code>==</code> and <code>!=</code> operators support globbing. The rest
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ of the operators compare as per the <code>vercmp</code> command.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>Examples:</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>A port that works on Darwin 12 and later:</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <programlisting>platforms {darwin >= 12}</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>A port that works on Darwin versions between 10 and 19 inclusive:</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <programlisting>platforms {darwin >= 10 <20}</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>A port that works on Darwin versions between 10 and 19 but not
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ version 12.x:</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <programlisting>platforms {darwin >= 10 != 12.* <20}</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>The special value <literal>any</literal> can also be used to indicate that
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ a port will install identical files across platforms or platform versions. This can
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ help to reduce the number of binary archives that have to be built. In most cases,
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ this is only applicable to ports that don't install any architecture-specific
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ files.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>Ports that install identical files on any platform should use:</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <programlisting>platforms any</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>Ports that install identical files on any Darwin version, but may install
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ different files on other platforms, should use:</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <programlisting>platforms {darwin any}</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span> </listitem>
</varlistentry>
<span style='display:block; white-space:pre;background:#e0e0e0;'>@@ -501,5 +548,23 @@
</span> </listitem>
</varlistentry>
<span style='display:block; white-space:pre;background:#e0ffe0;'>+ <varlistentry>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <term>known_fail</term>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>Setting this option to <code>yes</code> indicates that the
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ port is known not to work. Users will be told this and asked for
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ confirmation if they attempt to install it, and the Buildbot and
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ GitHub Actions will not attempt to build it.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <para>Don't set this option conditionally on the basis of
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ anything that can change dynamically, such as <code>$build_arch</code>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ or <code>$xcodeversion</code>, since it will be
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ recorded in the static PortIndex. If a port works only on certain
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ OS versions, use the <code>platforms</code> option to indicate
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ this rather than setting <code>known_fail</code> directly.</para>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ <programlisting>known_fail yes</programlisting>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </listitem>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ </varlistentry>
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span> </variablelist>
</section>
</pre><pre style='margin:0'>
</pre>