Apr 12, 2015, 7:07:19 PM (5 years ago)

base: document sources.conf, #44530

1 copied


  • 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 ================
    8 macports.conf - Configuration file of the MacPorts system
     8sources.conf - port definition configuration file of the MacPorts system
    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.
    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:
    19 <key> <value>
     18<line>  ::= <URI> [ '[' <flags> ']' ]
     19<flags> ::= <flag> [ ',' [ ' ' | '\t' ] <flags> ]
     20<flag>  ::= 'default' | 'nosync'
    22 The value of any given key can be referred to by the '$\{<keyname>\}'
    23 abstraction, where '<keyname>' expands to the key in question.
     25// Set default style for second-level labeled lists in this section
     26//:listdef-labeled2.style: horizontal
    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.
    30 The following keys are used by *port* itself:
     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]
    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
     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
    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.
    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
     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
    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
    53 frameworks_dir::
    54     Directory containing Frameworks installed from ports.
    55     *Default:*;; $\{prefix\}/Library/Frameworks
     91Source specifications support a number of flags that modify the behavior of
     92a source:
    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
     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.
    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
    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
    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
    84 configureccache::
    85     Use ccache (C/C++ compiler cache). Requires that ccache has been installed.
    86     *Default:*;; no
    88 ccache_dir::
    89     Location where ccache stores its files
    90     *Default:*;; $\{portdbpath\}/build/.ccache
    92 ccache_size::
    93     Maximum size ccache may use. Use 'G', 'M', or 'K' suffix for giga-, mega- or
    94     kilobytes.
    95     *Default:*;; 2G
    97 configuredistcc::
    98     Use distcc (distributed compiler). Requires that distcc has been installed.
    99     *Default:*;; no
    101 configurepipe::
    102     Use pipes rather than intermediate files when compiling C/C++/etc (gcc
    103     -pipe)
    104     *Default:*;; yes
    106 buildnicevalue::
    107     Lowered scheduling priority (0-20) to use for make when building ports
    108     *Default:*;; 0
    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
    116 portautoclean::
    117     Automatic cleaning of the build directory of a given port after it has been
    118     installed.
    119     *Default:*;; yes
    121 keeplogs::
    122     Keep logs for ports.
    123     *Default:*;; no
    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
    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
    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
    145 destroot_umask::
    146     Umask value to use during the destrooting of a port.
    147     *Default:*;; 022
    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
    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)
    161 rsync_options::
    162     Default rsync options to use when connecting to the rsync server.
    163     *Default:*;; -rtzv --delete-after
    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
    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.
    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
    188 proxy_http::
    189     HTTP proxy
    190     *Default:*;; none
    192 proxy_https::
    193     HTTPS proxy
    194     *Default:*;; none
    196 proxy_ftp::
    197     FTP proxy
    198     *Default:*;; none
    200 proxy_rsync::
    201     rsync proxy
    202     *Default:*;; none
    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
    209 host_blacklist::
    210     Space separated list of download hosts that should not be used.
    211     *Default:*;; none
    213 preferred_hosts::
    214     Space separated list of download hosts that should be used preferentially.
    215     *Default:*;; none
    217 revupgrade_autorun::
    218     Controls whether the rev-upgrade action will be run automatically after
    219     upgrading ports.
    220     *Default:*;; yes
    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
    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)
     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.
    239 $\{prefix\}/etc/macports/macports.conf::
    240     Standard system-wide MacPorts configuration file.
    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]
    246114SEE ALSO
    248 man:port[1], man:portfile[7]
     116man:port[1], man:port-selfupdate[1], man:port-sync[1], man:portindex[1],
    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.