Changeset 134971 for trunk/base/doc


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

base: document sources.conf, #44530

File:
1 copied

Legend:

Unmodified
Added
Removed
  • trunk/base/doc/sources.conf.5.txt

    r133158 r134971  
    11// vim: set et sw=4 ts=8 ft=asciidoc tw=80:
    2 macports.conf(5)
    3 ================
     2sources.conf(5)
     3===============
    44$Id$
    55
    66NAME
    77----
    8 macports.conf - Configuration file of the MacPorts system
     8sources.conf - port definition configuration file of the MacPorts system
    99
    1010DESCRIPTION
    1111-----------
    12 *macports.conf* is the configuration file used to bootstrap the MacPorts
    13 system. This file is read by the *port* command and determines how it behaves.
    14 Lines beginning with '#' are comments, empty lines are ignored. The format is
    15 that of a simple key/value space or tab separated pair.
    16 
    17 The file contains entries of the form:
     12*sources.conf* is the configuration file used by the MacPorts system to locate
     13its port definitions. The file is read by the *port* command to find available
     14ports and how to install them. Entries in this file are URIs optionally followed
     15by flags in square brackets. Each source specification is given on a separate
     16line. A grammar in EBNF is given below:
    1817--------
    19 <key> <value>
     18<line>  ::= <URI> [ '[' <flags> ']' ]
     19<flags> ::= <flag> [ ',' [ ' ' | '\t' ] <flags> ]
     20<flag>  ::= 'default' | 'nosync'
    2021--------
    2122
    22 The value of any given key can be referred to by the '$\{<keyname>\}'
    23 abstraction, where '<keyname>' expands to the key in question.
     23URI FORMATS
     24-----------
     25// Set default style for second-level labeled lists in this section
     26//:listdef-labeled2.style: horizontal
    2427
    25 KEYS
    26 ----
    27 // Set default style for second-level labeled lists in this section
    28 :listdef-labeled2.style: horizontal
     28MacPorts supports a number of different protocols as source descriptions.
    2929
    30 The following keys are used by *port* itself:
     30'rsync://'::
     31    Followed by a server name and a path on this server, this URI instructs
     32    MacPorts to fetch the contents of the file or directory referenced by this
     33    URI into a path of its own choosing. This is the default method of port tree
     34    synchronization and is generally recommended. MacPorts will derive
     35    a machine- and architecture-specific URI (in the subdirectory
     36    PortIndex_$\{platform\}_$\{os_major\}_$\{os_arch\}/) and attempt to download
     37    a pre-generated PortIndex (including the PortIndex.quick file) from there.
     38    +
     39    *Example*;;
     40        rsync://rsync.macports.org/release/tarballs/ports.tar
     41    *Default*;;
     42        rsync://rsync.macports.org/release/tarballs/ports.tar [default]
    3143
    32 prefix::
    33     Sets the directory where ports are installed. Any path may be used but those
    34     with spaces and/or non ascii characters should be avoided, as this can break
    35     some ports. This key is often referred to as '$\{prefix\}'.
    36     *Default:*;; /opt/local
     44'file://'::
     45    Followed by an absolute path (which will result in *three* slashes at the
     46    beginning of the URI) to a local directory that should be used as port tree.
     47    A port index will automatically be generated for this source. Note that
     48    MacPorts will try to determine whether the given path is under source
     49    control and attempt to update from the default remote server if it is.
     50    Currently, Subversion and Git (including git-svn) are supported options. You
     51    can add the 'nosync' tag to avoid this behavior.
     52    +
     53    NOTE: The MacPorts user (usually called 'macports') needs to be able to read
     54    and write to this location. This usually means your home directory is not
     55    a suitable place for a port tree, unless you adjust permissions accordingly.
     56    +
     57    *Example*;;
     58        file:///opt/dports [nosync,default]
     59    *Default*;;
     60        none
    3761
    38 portdbpath::
    39     Directory where MacPorts keeps working data such as downloaded sources,
    40     installed ports' receipts and the main registry. The same path restrictions
    41     apply as for '$\{prefix\}'.
    42     *Default:*;; $\{prefix\}/var/macports
     62'http://', 'https://' and 'ftp://'::
     63    Followed by a server name and a path on this server, this URI instructs
     64    MacPorts to download a tarball snapshot of a ports tree from the URI and
     65    extract it to a path of its choice. This possibility is provided as
     66    a fallback to users that can use neither rsync nor subversion to sync the
     67    MacPorts port tree.
     68    +
     69    If the tarball contains a pre-built PortIndex and PortIndex.quick file at
     70    PortIndex_$\{platform\}_$\{os_major\}_$\{os_arch\}/, those will be used as
     71    default. If it does not, MacPorts will build a suitable port index for the
     72    local system automatically.
    4373
    44 portdbformat::
    45     Storage type to use for the MacPorts registry. The preferred format is
    46     "sqlite", with "flat" also available as a legacy format.
    47     *Default:*;; sqlite
     74SOURCE FORMATS
     75--------------
     76Port definition trees can be either directories (e.g. for the 'file://' and
     77rsync methods) or tarballs (for HTTP, HTTPS, FTP and rsync). For the directory
     78format, no additional verification is performed. Because transfers using rsync
     79are not encrypted or authenticated, the use of this setup over rsync is
     80discouraged.
    4881
    49 applications_dir::
    50     Directory containing Applications installed from ports.
    51     *Default:*;; /Applications/MacPorts
     82If the URI ends with '.tar', MacPorts assumes the source is a tarball and
     83attempts to download an additional '.tar.rmd160' signature file. It then uses
     84the public keys configured in man:pubkeys.conf[5] to verify this signature to
     85ensure the source has not been tampered with. You are strongly encouraged to use
     86this setup, and it has been the default for MacPorts since it has been
     87introduced.
    5288
    53 frameworks_dir::
    54     Directory containing Frameworks installed from ports.
    55     *Default:*;; $\{prefix\}/Library/Frameworks
     89FLAGS
     90-----
     91Source specifications support a number of flags that modify the behavior of
     92a source:
    5693
    57 sources_conf::
    58     Location of the sources file. This file enables rsync synchronization of the
    59     default ports tree with the MacPorts rsync server (through the "sync" target
    60     of the port command) and any other local tree(s) you might have.
    61     *Default:*;; $\{prefix\}/etc/macports/sources.conf
     94'nosync'::
     95    Skip this source when *port sync* or *port selfupdate* are used. You can use
     96    this flag to avoid updating your local ports tree managed by a source
     97    control system such as Git or Subversion. You are responsible for generating
     98    a current port index using the man:portindex[1] command for sources marked
     99    with this flag.
    62100
    63 variants_conf::
    64     Location of the optional global variants definition file, listing those that
    65     should be used in all installed ports if available.
    66     *Default:*;; $\{prefix\}/etc/macports/variants.conf
    67 
    68 buildfromsource::
    69     Controls whether ports are built from source or downloaded as pre-built
    70     archives. Setting to 'always' will never use archives, 'never' will always
    71     try to use an archive and fail if one is not available. 'ifneeded' will try
    72     to fetch an archive and fall back to building from source if that isn't
    73     possible.
    74     *Default:*;; ifneeded
    75 
    76 portarchivetype::
    77     Format of archives in which to store port images. This controls both the
    78     type of archive cre- ated locally after building from source, and the type
    79     to request from remote servers. Changing this will not affect the usability
    80     of already installed archives; they can be of any supported type.
    81     *Supported types:*;; tgz, tar, tbz, tbz2, tlz, txz, xar, zip, cpgz, cpio
    82     *Default:*;; tbz2
    83 
    84 configureccache::
    85     Use ccache (C/C++ compiler cache). Requires that ccache has been installed.
    86     *Default:*;; no
    87 
    88 ccache_dir::
    89     Location where ccache stores its files
    90     *Default:*;; $\{portdbpath\}/build/.ccache
    91 
    92 ccache_size::
    93     Maximum size ccache may use. Use 'G', 'M', or 'K' suffix for giga-, mega- or
    94     kilobytes.
    95     *Default:*;; 2G
    96 
    97 configuredistcc::
    98     Use distcc (distributed compiler). Requires that distcc has been installed.
    99     *Default:*;; no
    100 
    101 configurepipe::
    102     Use pipes rather than intermediate files when compiling C/C++/etc (gcc
    103     -pipe)
    104     *Default:*;; yes
    105 
    106 buildnicevalue::
    107     Lowered scheduling priority (0-20) to use for make when building ports
    108     *Default:*;; 0
    109 
    110 buildmakejobs::
    111     Number of simultaneous make jobs (commands) to use when building ports. 0 is
    112     a special value meaning "the number of CPU cores or the number of GB of
    113     physical memory plus one, whichever is less."
    114     *Default:*;; 0
    115 
    116 portautoclean::
    117     Automatic cleaning of the build directory of a given port after it has been
    118     installed.
    119     *Default:*;; yes
    120 
    121 keeplogs::
    122     Keep logs for ports.
    123     *Default:*;; no
    124 
    125 build_arch::
    126     The machine architecture to try to build for in normal use.
    127     *Regular architectures include:*;; ppc, i386, ppc64, x86_64
    128     *Default (10.6):*;; x86_64 or i386 depending on hardware
    129     *Default (10.5 and earlier):*;; i386 or ppc depending on hardware
    130 
    131 universal_archs::
    132     The machine architectures to use for +universal variant (multiple
    133     architecture entries should be space separated).
    134     *Regular architectures include:*;; ppc, i386, ppc64, x86_64
    135     *Default (10.6):*;; x86_64 i386
    136     *Default (10.5 and earlier):*;; i386 ppc
    137 
    138 startupitem_type::
    139     Set the default type of startupitems to be generated, overridable by
    140     Portfiles that explicitly state a startupitem.type key. If set to "default",
    141     then a type will be selected that's appropriate to the OS.
    142     *Supported types:*;; none, SystemStarter, launchd, default, rcNG.
    143     *Default:*;; default
    144 
    145 destroot_umask::
    146     Umask value to use during the destrooting of a port.
    147     *Default:*;; 022
    148 
    149 rsync_server::
    150     Default rsync server to connect to when running "selfupdate" through the
    151     port com- mand to update your base MacPorts infrastructure. While selfupdate
    152     also syncs the ports tree, it uses the settings from $\{sources_conf\} to do
    153     so.
    154     *Default:*;; rsync.macports.org
    155 
    156 rsync_dir::
    157     Rsync directory from which to pull MacPorts sources from the rsync server.
    158     *Default:*;; release/base/ (which pulls sources for the currently shipping
    159     MacPorts release)
    160 
    161 rsync_options::
    162     Default rsync options to use when connecting to the rsync server.
    163     *Default:*;; -rtzv --delete-after
    164 
    165 binpath::
    166     Sets the directory search path for locating system executables used by
    167     MacPorts. This variable should contain the paths for locating utilities such
    168     as rsync, tar, cvs and others. Don't change this unless you understand and
    169     accept the consequences.
    170     *Default:*;; $\{prefix\}/bin:$\{prefix\}/sbin:/bin:/sbin:/usr/bin:/usr/sbin
    171 
    172 extra_env::
    173     List of extra environment variables MacPorts should keep in the user's
    174     environment when sanitizing it. Changing this is unsupported.
    175 
    176 proxy_override_env::
    177     Proxy support. Precedence is: env, macports.conf, System Preferences. That
    178     is, if it's set in the environment, that will be used instead of anything
    179     here or in System Preferences. Setting proxy_override_env to yes will cause
    180     any proxies set here (or in System Preferences if set there but not here) to
    181     override what's in the environment. Note that System Preferences doesn't
    182     have an rsync proxy definition. Also note, on 10.5, sudo will clear many
    183     environment variables including those for proxy support. Equivalent
    184     environment variables: http_proxy, HTTPS_PROXY, FTP_PROXY, RSYNC_PROXY,
    185     NO_PROXY
    186     *Default:*;; yes
    187 
    188 proxy_http::
    189     HTTP proxy
    190     *Default:*;; none
    191 
    192 proxy_https::
    193     HTTPS proxy
    194     *Default:*;; none
    195 
    196 proxy_ftp::
    197     FTP proxy
    198     *Default:*;; none
    199 
    200 proxy_rsync::
    201     rsync proxy
    202     *Default:*;; none
    203 
    204 proxy_skip::
    205     Hosts not to go through the proxy (comma-separated, applies to HTTP, HTTPS
    206     and FTP, but not rsync).
    207     *Default:*;; none
    208 
    209 host_blacklist::
    210     Space separated list of download hosts that should not be used.
    211     *Default:*;; none
    212 
    213 preferred_hosts::
    214     Space separated list of download hosts that should be used preferentially.
    215     *Default:*;; none
    216 
    217 revupgrade_autorun::
    218     Controls whether the rev-upgrade action will be run automatically after
    219     upgrading ports.
    220     *Default:*;; yes
    221 
    222 revupgrade_mode::
    223     Controls the rev-upgrade functionality which checks for broken linking and
    224     can rebuild ports to fix it. 'rebuild' means ports will automatically be
    225     rebuilt when broken linking is detected in their files, while 'report' means
    226     broken files will be scanned for and reported but the ports will not be
    227     rebuilt.
    228     *Default:*;; rebuild
    229 
    230 default_compilers::
    231     Default value for configure.compiler. This can be a space-separated list.
    232     Later entries will be used if earlier entries are unavailable or blacklisted
    233     by a port. Setting this is unsupported.
    234     *Default:*;; none (internal list based on Xcode version is normally used)
     101'default'::
     102    Mark this source as the default. The default source is used as a fallback to
     103    load additional files (such as PortGroups and mirror definitions) from the
     104    '_resources/port1.0' directory.
    235105
    236106FILES
    237107-----
    238 
    239 $\{prefix\}/etc/macports/macports.conf::
    240     Standard system-wide MacPorts configuration file.
    241 
    242 ~/.macports/macports.conf::
    243     User-specific configuration override. This file, if found, will be used
    244     instead of the default file at $\{prefix\}/etc/macports/macports.conf.
     108The path of the 'sources.conf' file is specified in the *sources_conf* option of
     109man:macports.conf[5]. It defaults to '$\{prefix\}/etc/macports/sources.conf'.
     110There is no user-specific 'sources.conf' file, but support for this can be
     111emulated by setting 'sources.conf' in the user-specific man:macports.conf[5]
     112file.
    245113
    246114SEE ALSO
    247115--------
    248 man:port[1], man:portfile[7]
     116man:port[1], man:port-selfupdate[1], man:port-sync[1], man:portindex[1],
     117man:macports.conf[5]
    249118
    250119AUTHORS
    251120-------
    252   (C) 2007-2011 The MacPorts Project
    253   Juan Manuel Palacios <jmpp@macports.org>
    254   Matt Anton <matt@opendarwin.org>
    255   Rainer Mueller <raimue@macports.org>
     121  (C) 2015 The MacPorts Project
     122  Clemens Lang <cal@macports.org>
Note: See TracChangeset for help on using the changeset viewer.