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

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

base/doc: actually use proper EBNF in config file grammar, add note on comments and empty lines in sources.conf

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 5.0 KB
Line 
1// vim: set et sw=4 ts=8 ft=asciidoc tw=80:
2sources.conf(5)
3===============
4$Id: sources.conf.5.txt 134981 2015-04-12 20:24:01Z 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. Lines beginning with '#' are comments, empty
15lines are ignored. Entries in this file are URIs optionally followed by flags in
16square brackets. Each source specification is given on a separate line.
17A grammar in EBNF is given below:
18--------
19line  = URI, [ '[', flag, { space, flag }, ']' ] ;
20flag  = 'default' | 'nosync' ;
21space = ' ' | '\t' ;
22--------
23
24URI FORMATS
25-----------
26// Set default style for second-level labeled lists in this section
27//:listdef-labeled2.style: horizontal
28
29MacPorts supports a number of different protocols as source descriptions.
30
31'rsync://'::
32    Followed by a server name and a path on this server, this URI instructs
33    MacPorts to fetch the contents of the file or directory referenced by this
34    URI into a path of its own choosing. This is the default method of port tree
35    synchronization and is generally recommended. MacPorts will derive
36    a machine- and architecture-specific URI (in the subdirectory
37    PortIndex_$\{platform\}_$\{os_major\}_$\{os_arch\}/) and attempt to download
38    a pre-generated PortIndex (including the PortIndex.quick file) from there.
39    +
40    *Example*;;
41        rsync://rsync.macports.org/release/tarballs/ports.tar
42    *Default*;;
43        rsync://rsync.macports.org/release/tarballs/ports.tar [default]
44
45'file://'::
46    Followed by an absolute path (which will result in *three* slashes at the
47    beginning of the URI) to a local directory that should be used as port tree.
48    A port index will automatically be generated for this source. Note that
49    MacPorts will try to determine whether the given path is under source
50    control and attempt to update from the default remote server if it is.
51    Currently, Subversion and Git (including git-svn) are supported options. You
52    can add the 'nosync' tag to avoid this behavior.
53    +
54    NOTE: The MacPorts user (usually called 'macports') needs to be able to read
55    and write to this location. This usually means your home directory is not
56    a suitable place for a port tree, unless you adjust permissions accordingly.
57    +
58    *Example*;;
59        file:///opt/dports [nosync,default]
60    *Default*;;
61        none
62
63'http://', 'https://' and 'ftp://'::
64    Followed by a server name and a path on this server, this URI instructs
65    MacPorts to download a tarball snapshot of a ports tree from the URI and
66    extract it to a path of its choice. This possibility is provided as
67    a fallback to users that can use neither rsync nor subversion to sync the
68    MacPorts port tree.
69    +
70    If the tarball contains a pre-built PortIndex and PortIndex.quick file at
71    PortIndex_$\{platform\}_$\{os_major\}_$\{os_arch\}/, those will be used as
72    default. If it does not, MacPorts will build a suitable port index for the
73    local system automatically.
74
75SOURCE FORMATS
76--------------
77Port definition trees can be either directories (e.g. for the 'file://' and
78rsync methods) or tarballs (for HTTP, HTTPS, FTP and rsync). For the directory
79format, no additional verification is performed. Because transfers using rsync
80are not encrypted or authenticated, the use of this setup over rsync is
81discouraged.
82
83If the URI ends with '.tar', MacPorts assumes the source is a tarball and
84attempts to download an additional '.tar.rmd160' signature file. It then uses
85the public keys configured in man:pubkeys.conf[5] to verify this signature to
86ensure the source has not been tampered with. You are strongly encouraged to use
87this setup, and it has been the default for MacPorts since it has been
88introduced.
89
90FLAGS
91-----
92Source specifications support a number of flags that modify the behavior of
93a source:
94
95'nosync'::
96    Skip this source when *port sync* or *port selfupdate* are used. You can use
97    this flag to avoid updating your local ports tree managed by a source
98    control system such as Git or Subversion. You are responsible for generating
99    a current port index using the man:portindex[1] command for sources marked
100    with this flag.
101
102'default'::
103    Mark this source as the default. The default source is used as a fallback to
104    load additional files (such as PortGroups and mirror definitions) from the
105    '_resources/port1.0' directory.
106
107FILES
108-----
109The path of the 'sources.conf' file is specified in the *sources_conf* option of
110man:macports.conf[5]. It defaults to '$\{prefix\}/etc/macports/sources.conf'.
111There is no user-specific 'sources.conf' file, but support for this can be
112emulated by setting 'sources.conf' in the user-specific man:macports.conf[5]
113file.
114
115SEE ALSO
116--------
117man:port[1], man:port-selfupdate[1], man:port-sync[1], man:portindex[1],
118man:macports.conf[5]
119
120AUTHORS
121-------
122  (C) 2015 The MacPorts Project
123  Clemens Lang <cal@macports.org>
Note: See TracBrowser for help on using the repository browser.