source: trunk/doc/guide/xml/portfiles/variants.xml @ 11436

Last change on this file since 11436 was 11436, checked in by mww, 15 years ago

add some guidelines for using variants

  • Property svn:eol-style set to native
File size: 3.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8" ?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="variants">
5        <title>Variants</title> 
6        <sect1>
7                <title>What are variants?</title> 
8                <para>DarwinPorts allows multiple versions of a port to be specified in a single Portfile. For example, vim can be built with and without x11 support. Rather than duplicate the whole port and have vim-x11 vim-nox ports DarwinPorts supports "variants". </para>
9
10        </sect1>
11
12        <sect1>
13                <title>Guidelines</title>
14                <para>There are some guidelines for using variants:</para>
15                <itemizedlist>
16                        <listitem><para>Never change the version of a port inside a variant.</para></listitem>
17                        <listitem><para>Heavy usage of variants is considered bad style - keep the number of variants low.</para></listitem>
18                        <listitem><para>Prefer function restricting variants over function enhancing ones. Make the default installation the one that serves most purposes.</para></listitem>
19                </itemizedlist>
20        </sect1>
21
22        <sect1>
23                <title>Syntax</title> 
24                <para>The variants syntax is largely identical to the syntax in the main part of the Portfile. </para>
25
26                <variablelist>
27                        <varlistentry id='variant'>
28                                <term>
29                                        variant
30                                </term>
31                                <listitem>
32                                        <para>The key variant is used to begin the foo variant as shown in the example.
33                                                <programlisting>
34<![CDATA[
35variant foo    {
36                              [variant code]
37                              [more variant code]
38                 }
39]]> 
40                                                </programlisting></para>
41
42                                        <para>Within the variant block essentially all of the keys available in the main section are available. Using a key used in the main section will overwrite it. </para>
43
44                                </listitem>
45                        </varlistentry>
46                        <varlistentry id='append'>
47                                <term>
48                                        append
49                                </term>
50                                <listitem>
51                                        <para>For most of the keys you can append additional terms.
52                                                <programlisting>
53<![CDATA[
54variant foo    { configure.args-append --with-x}
55
56]]> 
57                                                </programlisting></para>
58
59                                </listitem>
60                        </varlistentry>
61                        <varlistentry id='delete'>
62                                <term>
63                                        delete
64                                </term>
65                                <listitem>
66                                        <para>For most of the keys you can delete terms. The item being deleted should match a string in the option being deleted exactly.
67                                                <programlisting>
68<![CDATA[
69variant gnome    { configure.args-delete --without-gnome}
70
71]]> 
72                                                </programlisting></para>
73
74                                </listitem>
75                        </varlistentry>
76                </variablelist>
77        </sect1>
78        <sect1>
79                <title>Advanced variants</title> 
80                <para>For the most part, variants are quite straightforward to use. Several more advanced features of variants are also available. </para>
81
82                <variablelist>
83                        <varlistentry id='default_variants'>
84                                <term>
85                                        default_variants
86                                </term>
87                                <listitem>
88                                        <para>In some cases you may want a variant or variants to be executed by default. For example w3m is distributed with a patch to add international text support. This is a vendor provided patch, but not a core part of the program. In this case it makes sense to make the internationalised version the default, but keep the vanilla w3m as the main port. The default_variants key is used in the main section of a Portfile, not in a variant. </para>
89
90                                        <para><userinput>
91                                                        default_variants +foo +bar
92                                                </userinput></para>
93
94                                </listitem>
95                        </varlistentry>
96                        <varlistentry id='platform_variants'>
97                                <term>
98                                        platform_variants
99                                </term>
100                                <listitem>
101                                        <para>Platform specific variants are automatically executed on that platform, without needing any intervention from the user. Currently available platforms are:
102                                                <simplelist>
103                                                        <member>
104                                                                darwin
105                                                        </member>
106                                                        <member>
107                                                                freebsd
108                                                        </member>
109                                                        <member>
110                                                                linux
111                                                        </member>
112                                                </simplelist></para>
113
114                                        <para><userinput>
115                                                        variant foo darwin {[variant code]}
116                                                </userinput></para>
117
118                                </listitem>
119                        </varlistentry>
120                </variablelist>
121        </sect1>
122</chapter>
Note: See TracBrowser for help on using the repository browser.