[MacPorts] PortfileRecipes modified

[MacPorts]

Page "PortfileRecipes" was changed by elelay at macports.org
Diff URL: <https://trac.macports.org/wiki/PortfileRecipes?action=diff&version=67>
Revision 67
Comment: document the require_active_variants portgroup
Changes:
-------8<------8<------8<------8<------8<------8<------8<------8<--------
Index: PortfileRecipes
=========================================================================
--- PortfileRecipes (version: 66)
+++ PortfileRecipes (version: 67)
@@ -111,6 +111,99 @@
 }}}
 
 Formerly, use of negatively-named variants (like `no_x11`) was preferred to having a default positively-named variant (like `x11`), due to a deficiency in the port registry (ticket #2377). Now that this is fixed, use of negatively-named variants should be avoided.
+
+== require_active_variants == #require_active_variants
+Depending upon a specific port variant is not possible in MacPorts:
+The quartz variant of a graphic library cannot require automatically that the quartz variant
+of gtk is picked. It's up to the user to issue the correct command and to the port maintainer
+to check for the installed variant.
+
+There was a common practice in Portfiles to check for the presence of a file known to be provided by the wanted variant
+and to display a message requesting the user to install the correct variant if it's missing.
+
+example ([source:trunk/dports/devel/gtk-osx-application/Portfile at 109119 gtk-osx-application])
+{{{
+   pre-configure {
+        if {![file exists ${prefix}/lib/pkgconfig/gdk-quartz-3.0.pc]} {
+            ui_error "
+
+****
+**** gtk-osx-application is meant to be used only in a GTK3 quartz
+**** development environment but your version of GTK3 does not
+**** support quartz.  Please make sure that port gtk3 and all its
+**** dependencies are built with variants +no_x11 +quartz and try again.
+****
+"
+            error "gtk3 +no_x11 +quartz not installed."
+        }
+    }
+}}}
+
+A PortGroup has been created to simplify this: [source:trunk/dports/_resources/port1.0/group/active_variants-1.1.tcl active_variants].
+
+To use it:
+1. add {{{ PortGroup       active_variants 1.1 }}} to the top of your Portfile
+2. add {{{ require_active_variants $depspec $required $forbidden}}} 
+   where
+  $depspec:: is the name of the port you're trying to check (required), which can be
+    specified as either just the port, or via "(bin:lib:path):FOO:port"
+    as accepted by the dependency parser.
+  $required:: is a list of variants that must be enabled for the test to succeed
+    (required; remember this can also be a space-separated string or just
+    a string for a single value. It's iterpreted as list, though.)
+  $forbidden:: is a list of variants that may not be enabled for the test to succeed
+    (default is empty list, see description of $required for values that can be
+    interpreted as list by Tcl)
+
+Exemple with gtk-osx-application requiring gtk2+quartz or gtk3+quartz:
+
+{{{
+PortSystem 1.0
+PortGroup  active_variants 1.1
+
+(...)
+
+variant gtk3 conflicts python25 description {Use gtk3} {
+    
+    require_active_variants gtk3 quartz
+    
+    (...)
+}
+
+if {![variant_isset gtk3]} {
+
+    require_active_variants gtk2 quartz
+
+    (...)
+}
+}}}
+
+{{{sudo port install gtk-osx-application +gtk3}}} results in 
+{{{
+--->  Configuring gtk-osx-application
+Error: org.macports.configure for port gtk-osx-application returned: gtk3 must be installed with +quartz.
+To report a bug, follow the instructions in the guide:
+    http://guide.macports.org/#project.tickets
+Error: Processing of port gtk-osx-application failed
+}}}
+
+
+Exemple with py-cairo +x11 requiring /cairo +x11 -quartz/ ([source:trunk/dports/python/py-cairo/Portfile at 106520 Portfile])
+and selecting a default variant based on the variants of a cairo:
+{{{
+    variant x11 {
+        require_active_variants path:lib/pkgconfig/cairo.pc:cairo x11 quartz
+    }
+
+    if {![catch {set result [active_variants path:lib/pkgconfig/cairo.pc:cairo x11 quartz]}]} {
+        if {$result} {
+            default_variants +x11
+        }
+    } else {
+        default_variants +x11
+    }
+}}}
+
 
 == cvs/svn/git tag for consistency == #checkout_tag
 When using one of the checkout-based fetch types (cvs, svn, git, etc) it is best to also use the accompanying tag or date to make sure everyone gets the same checkout as you originally did when creating the port.  For example, [browser:trunk/dports/lang/slime slime] does the following for cvs:
-------8<------8<------8<------8<------8<------8<------8<------8<--------

--
Page URL: <https://trac.macports.org/wiki/PortfileRecipes>
MacPorts <http://www.macports.org/>
Ports system for OS X

This is an automated message. Someone added your email address to be
notified of changes on 'PortfileRecipes' page.
If it was not you, please report to .