<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>&lt;</code>, <code>&lt;=</code>,
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+        <code>&gt;</code>, <code>&gt;=</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 &gt;= 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 &gt;= 10 &lt;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 &gt;= 10 != 12.* &lt;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>