source: trunk/base/doc/sources.conf.5.txt @ 134971

Last change on this file since 134971 was 134971, checked in by cal@…, 5 years ago

base: document sources.conf, #44530

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 4.9 KB
Line 
1// vim: set et sw=4 ts=8 ft=asciidoc tw=80:
2sources.conf(5)
3===============
4$Id: sources.conf.5.txt 134971 2015-04-12 19:07:19Z cal@macports.org $
5
6NAME
7----
8sources.conf - port definition configuration file of the MacPorts system
9
10DESCRIPTION
11-----------
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:
17--------
18<line>  ::= <URI> [ '[' <flags> ']' ]
19<flags> ::= <flag> [ ',' [ ' ' | '\t' ] <flags> ]
20<flag>  ::= 'default' | 'nosync'
21--------
22
23URI FORMATS
24-----------
25// Set default style for second-level labeled lists in this section
26//:listdef-labeled2.style: horizontal
27
28MacPorts supports a number of different protocols as source descriptions.
29
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]
43
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
61
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.
73
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.
81
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.
88
89FLAGS
90-----
91Source specifications support a number of flags that modify the behavior of
92a source:
93
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.
100
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.
105
106FILES
107-----
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.
113
114SEE ALSO
115--------
116man:port[1], man:port-selfupdate[1], man:port-sync[1], man:portindex[1],
117man:macports.conf[5]
118
119AUTHORS
120-------
121  (C) 2015 The MacPorts Project
122  Clemens Lang <cal@macports.org>
Note: See TracBrowser for help on using the repository browser.