Changeset 134969 for trunk/base/doc


Ignore:
Timestamp:
Apr 12, 2015, 7:06:41 PM (4 years ago)
Author:
cal@…
Message:

base: document port variants, #44530

File:
1 copied

Legend:

Unmodified
Added
Removed
  • trunk/base/doc/port-variants.1.txt

    r133158 r134969  
    11// vim: set et sw=4 ts=8 ft=asciidoc tw=80:
    2 port-info(1)
    3 ============
     2port-variants(1)
     3================
    44$Id$
    55
    66NAME
    77----
    8 port-info - Return information about the given ports.
     8port-variants - Print a list of variants with descriptions provided by a port
    99
    1010SYNOPSIS
    1111--------
    1212[cmdsynopsis]
    13 *port* [*-q*] [*-D* 'portdir'] *info*
    14      [--categories|--category] [--depends] [--depends_fetch] [--depends_extract]
    15      [--depends_build] [--depends_lib] [--depends_run] [--description] [--epoch]
    16      [--fullname] [--heading] [--homepage] [--index] [--license] [--line]
    17      [--long_description] [--maintainer|--maintainers] [--name]
    18      [--platform|--platforms] [--portdir] [--pretty] [--replaced_by]
    19      [--revision] [--subports] [--variant|--variants] [--version]
     13*port* [*-qvd*] [*-D* 'portdir'] *variants* [--index]
    2014     [['portname' | 'pseudo-portname' | 'port-expressions' | 'port-url']]
     15     [+/-variant ...]
    2116
    2217DESCRIPTION
    2318-----------
    24 *port info* prints information about the given ports. Specifying at least one of
    25 the options limits the output to the corresponding field. If no fields are
    26 specified, a useful default set consisting of name, epoch, version, revision,
    27 categories, replaced_by, variants, description, homepage, dependencies,
    28 platforms, license, and maintainers is shown.
     19*port variants* prints a list of variants provided by the port(s) given on the
     20command line. Variants allow users to select certain features when installing
     21a certain port. For example, the +gtk3+ port provides two conflicting variants
     22'+quartz' and '+x11' that select whether Gtk uses the X11 backend (which
     23requires an X server) or the OS X-native Quartz backend (which attempts to
     24provide a more native OS X look and feel). In addition, many ports feature an
     25'+universal' variant that enables building of universal (i.e. multi-arch)
     26binaries.
     27
     28*port variants* lists all variants by name and (if available) description. If
     29variants depend on or conflict with other variants, this information is printed
     30as a bulleted list for each variant.
     31
     32The output of *port variants* contains '[\+]' before a variant name, if the port
     33declares this variant as default. '(\+)' or '(-)' in the same spot mark variants
     34enabled or disabled by your man:variants.conf[5]. Last, a single '+' or '-'
     35marks variants explicitly enabled or disabled on the command line by appending
     36'+variantname' or '-variantname'.
    2937
    3038OPTIONS
    3139-------
    32 The following options do not select fields for the output but change how the
    33 information is obtained or formatted:
    34 
    3540*--index*::
    3641    Do not read the 'Portfile', but rely solely on the port index information.
    37     Note that this option will prevent the information reported from reflecting
    38     the effects of any variants specified.
    39 
    40 *--line*::
    41     Print a single line for each port. Fields are separated by spaces.
    42 
    43 *--pretty*::
    44     Format the output in a convenient, human-readable fashion. This is the
    45     default when no options are specified.
    46 
    47 The rest of the options affect which fields will be given in the output:
    48 
    49 *--category*, *--categories*::
    50     List the categories of a port.
    51 
    52 *--depends*, *--depends_fetch*, *--depends_extract*, *--depends_build*, *--depends_lib*, *--depends_run*::
    53     List the specified dependencies of a port. *--depends* is a shorthand option
    54     for all other *--depends_** options.
    55 
    56 *--description*, *--long_description*::
    57     Print the short or long description of a port, respectively.
    58 
    59 *--epoch*, *--version*, *--revision*::
    60     List the components of a MacPorts version tuple, epoch, version and
    61     revision, respectively.
    62 
    63 *--fullname*::
    64     Print name and the full MacPorts version tuple, e.g., ``yubico-pam @2.16''.
    65 
    66 *--heading*::
    67     Like *--fullname* but including the categories.
    68 
    69 *--homepage*::
    70     List the homepage of a port.
    71 
    72 *--license*::
    73     Print the license that applies to the source code of a port.
    74 
    75 *--maintainer*, *--maintainers*::
    76     List the email address(es) of a port's maintainer(s).
    77 
    78 *--name*::
    79     Print the name of a port.
    80 
    81 *--platform*, *--platforms*::
    82     List the platforms supported by a port. This field exists for historical
    83     reasons only. In modern MacPorts, this is always 'darwin', i.e., OS X.
    84 
    85 *--portdir*::
    86     Print the path to a port's directory relative to the port tree root.
    87 
    88 *--replaced_by*::
    89     List the name of the port that replaces a port, if any.
    90 
    91 *--subports*::
    92     Print a list of subports defined by this port's 'Portfile', i.e., ports that
    93     are defined in the same 'Portfile' because they share common parts.
    94 
    95 *--variant*, *--variants*::
    96     List the variants defined by a port by name.
     42    Note that this will limit the output to the variant names only. No
     43    descriptions, dependencies or conflicts between variants will be reported.
    9744
    9845include::global-flags.txt[]
    9946
    10047*-q*::
    101     Do not print the field description when using *--pretty* output.
     48    Do not print the header line.
     49
     50EXAMPLES
     51--------
     52The output of *port variants* provides all available information on a port's
     53variants. The +gtk3+ port can serve as a good example:
     54----
     55$> port variants gtk3 -universal
     56gtk3 has the variants:
     57(+)quartz: Support for native Mac OS X graphics
     58     * conflicts with x11
     59  -universal: Build for multiple architectures
     60[+]x11: Enable X11 support
     61     * conflicts with quartz
     62----
     63In this case, '(\+)' means that we have chosen '\+quartz' as a default variant in
     64our man:variants.conf[5]. Additionally, we have explicitly disabled the
     65universal variant on the command line, as indicated by its leading '-' symbol.
     66Finally, the port maintainer has chosen '\+x11' as the default, indicated by
     67'[+]'. Furthermore, the 'quartz' and 'x11' variants conflict with each other.
    10268
    10369SEE ALSO
     
    10773AUTHORS
    10874-------
    109  (C) 2014 The MacPorts Project
     75 (C) 2015 The MacPorts Project
    11076 Clemens Lang <cal@macports.org>
Note: See TracChangeset for help on using the changeset viewer.