source: trunk/www/en/variants.php @ 1575

Last change on this file since 1575 was 1464, checked in by kevin, 18 years ago

Added variants description.

  • Property svn:eol-style set to native
File size: 5.2 KB
Line 
1<?
2
3//
4// File     : variants.php
5// Version  : $Id: variants.php,v 1.1 2002/12/20 08:47:58 kevin Exp $
6// Location : /projects/darwinports/variants.php
7//
8
9        include_once("$DOCUMENT_ROOT/includes/od_lib.inc.php");
10        od_print_header("DarwinPorts Portfile Variants", "en", "iso-8859-1", "", 0);
11?>
12
13<h2>
14Variants
15</h2>
16<pre><tt>
17Kevin Van Vechten | <a href="mailto:kevin@opendarwin.org">kevin@opendarwin.org</a>
189-Oct-2002
19</tt></pre>
20<a name="basictoc"></a><h4>Variants</h4>
21<ul>
22<li><a href="#what_are_they">What are Variants?</a></li>
23<li><a href="#additive_variants">Variants are Additive</a></li>
24<li><a href="#ordering_variants">Ordering Variants</a></li>
25<!-- <li><a href="#conflicting_variants">Conflicting Variants</a></li> -->
26<li><a href="#default_variants">Default Variants</a></li>
27<li><a href="#implicit_variants">Implicit Variants</a></li>
28</ul>
29<h3>
30<a name="what_are_they"></a>What are Variants?
31</h3>
32<p>
33Many software titles have optional functionatily which needs to be dealt with at compile time.
34These titles are either compiled with or without support for a certain feature.  One of the
35most common examples is whether to compile software with or without X11 support.
36</p>
37<p>
38Variants were created as a means to address this optional functionality.  Often, compiling
39with or without X11 support is a matter of specifying <tt>--with-x11</tt> or <tt>--without-x11</tt>
40in the <tt>configure.args</tt> variable.  In its most basic form, a variant is equivalent to
41a Tcl <tt>if</tt> statement.  If the variant was specified by the user, then the block of code is
42executed.  Here's an example of an X11 variant:
43</p>
44<pre><tt>
45configure.args --without-x11
46
47variant x11 {
48    configure.args-delete --without-x11
49    configure.args-append --with-x11
50}
51</tt></pre>
52<p>
53As normal, the code outside of any variant block is executed unconditionally before any variants
54are evaluated.  However, if <tt>+x11</tt> was specified, the <tt>configure.args-delete</tt> and <tt>configure.args-append</tt> statements will also be evaluated.
55</p>
56<h3>
57<a name="additive_variants"></a>Variants are Additive
58</h3>
59<p>
60If two variants are defined, for example <tt>x11</tt> and <tt>kde</tt>, either or both
61of them may be chosen by the user.  Specifying <tt>+x11</tt> will cause the <tt>x11</tt> variant to be evaluated,
62and specifying <tt>+kde</tt> will cause the <tt>kde</tt> variant to be evaluated.  If <tt>+x11 +kde</tt> is specified,
63then both variants will be evaluated.  It's also possible to define variants containing several terms.  For example:
64</p>
65<pre><tt>
66variant x11 kde {
67    # do something here, when both x11 and kde are selected
68}
69</tt></pre>
70<p>
71In this example, the <tt>x11-kde</tt> variant will execute only if both <tt>+x11</tt> and <tt>+kde</tt> were specified.
72This allows conflicts between two variant "primitives" to be resolved without much overhead.  Also, because these
73combined variants are most often used to resolve conflicts, they're evaluated after each of the constituent parts has
74been evaluated.
75</p>
76<h3>
77<a name="ordering_variants"></a>Ordering Variants
78</h3>
79<p>
80Sometimes it's beneficial to guarantee a variant runs after another variant.  This can make variable manipulation and
81and other operartions more straightforward.  Ordering can be achieve by the <tt>follows</tt> keyword.  (<b><i>Important:</i></b> the <tt>follows</tt> keyword has not yet been implemented.)  In the following
82example, the <tt>kde</tt> variant declares that whenever both <tt>+kde</tt> and <tt>+x11</tt> are specified, the
83<tt>kde</tt> variant will always be evaluated after the <tt>x11</tt> variant.  The <tt>kde</tt> variant will still
84be evaluated even if only <tt>+kde</tt> is specified.
85<pre><tt>
86variant kde follows x11 {
87    # do something here, after x11
88}
89</tt></pre>
90<p>
91On the other hand, it's possible to allow <tt>kde</tt> as a variant if and only if <tt>x11</tt> has also been selected.
92This can be done using the <tt>requires</tt> keyword in the following manner:
93</p>
94<pre><tt>
95variant kde requires x11 {
96    # do something here, only after x11
97}
98</tt></pre>
99<!--
100<h3>
101<a name="conflicting_variants"></a>Conflicting Variants
102</h3>
103<p>
104</p>
105-->
106<h3>
107<a name="default_variants"></a>Default Variants
108</h3>
109<p>
110A Portfile may specify a default set of variants, which will be selected while evaluating the Portfile, unless the
111user has specifically negated them.  This can be done by using the <tt>default_variants</tt> command in the
112Portfile as follows:
113</p>
114<pre><tt>
115default_variants    +x11 +kde
116</tt></pre>
117<p>
118This specifies that the <tt>x11</tt> and <tt>kde</tt> variants will be evaluated, unless the user were to specify
119<tt>-kde -x11</tt> on the command line.
120</p>
121<h3>
122<a name="implicit_variants"></a>Implicit Variants
123</h3>
124<p>
125Some variants are specified by the system implicitly.  Like default variants, these can be negated on the
126command line.  Currently the platform and architecture are the only two implicit variants.  Variants of the
127same name as the values of <tt>os.platform</tt> and <tt>os.arch</tt> are selected.  <tt>os.platform</tt> contains
128the value of <tt>uname -s</tt> such as <tt>darwin</tt> or <tt>freebsd</tt>.  <tt>os.arch</tt> contains the value of
129<tt>uname -p</tt> such as <tt>ppc</tt> or <tt>i386</tt>.
130</p>
131
132<?
133        od_print_footer("en");
134?>
Note: See TracBrowser for help on using the repository browser.