Site definitions¶

The following outlines the details for defining supported site definitions. If attempting to use an extension-provided site type, please refer to the documentation provided by the extension.

Note

All site values can be defined with a unique prefix value (e.g. git+ for Git sources); however, this is optional if a package wishes to use the LIBFOO_VCS_TYPE option.

Bazaar site¶

To define a Bazaar-based location, the site value must be prefixed with a bzr+ value. A site can be defined as follows:

LIBFOO_SITE = 'bzr+ssh://example.com/project/trunk'
# (or)
LIBFOO_SITE = 'bzr+lp:<project>'

The value after the prefix is a path which will be provided to a bzr export call [1]. Content from a Bazaar repository will be fetched and archived into a file during fetch stage. Once a cached archive is made, the fetch stage will be skipped unless the archive is manually removed.

CVS site¶

To define a CVS-based location, the site value must be prefixed with a cvs+ or other common CVSROOT value. A site can be defined as follows:

LIBFOO_SITE = ':pserver:anonymous@cvs.example.com:/var/lib/cvsroot mymodule'
# (or)
LIBFOO_SITE = 'cvs+:ext:cvs@cvs.example.org:/usr/local/cvsroot mymodule'

The value after the prefix is a space-separated pair, where the first part represents the CVSROOT [2] to use and the second part specifies the CVS module [3] to use. Content from a CVS repository will be fetched and archived into a file during fetch stage. Once a cached archive is made, the fetch stage will be skipped unless the archive is manually removed.

Git site¶

To define a Git-based location, the site value must be prefixed with a git+ value or postfixed with the .git value. A site can be defined as follows:

LIBFOO_SITE = 'https://example.com/libfoo.git'
# (or)
LIBFOO_SITE = 'git+git@example.com:base/libfoo.git'

The site value (less prefix, if used) is used as a Git remote [4] for a locally managed cache source. Git sources will be cached inside the cache directory on first-run. Future runs to fetch a project’s source will use the cached Git file system. If a desired revision exists, content will be acquired from the cache location. If a desired revision does not exist, the origin remote will be fetched for the new revision (if it exists).

Local site¶

To define a package to use local site/sources, the site value can be set to local. A local site can be defined as follows:

LIBFOO_SITE = 'local'

This is equivalent to configuring LIBFOO_VCS_TYPE to a local VCS type as well. Note that a local package is intended for development/testing/training purposes. See LIBFOO_VCS_TYPE for more information.

Mercurial site¶

To define a Mercurial-based location, the site value must be prefixed with a hg+ value. A site can be defined as follows:

LIBFOO_SITE = 'hg+https://example.com/project'

The value after the prefix is used as the SOURCE in an hg clone call [5]. Mercurial sources will be cached inside the cache directory on first-run. Future runs to fetch a project’s source will use the cached Mercurial repository. If a desired revision exists, content will be acquired from the cache location. If a desired revision does not exist, the origin remote will be pulled for the new revision (if it exists).

Perforce site¶

To define a Perforce-based location, the site value must be prefixed with an perforce+ value. A site can be defined as follows:

LIBFOO_SITE = 'perforce+srcs.example.com:1666 //base/libfoo/main'
# (or)
LIBFOO_SITE = 'perforce+guest@tcp4:perforce.example.org:1666 //guest/libfoo'

The value after the prefix is a space-separated pair, where the first part represents the Perforce service (P4PORT [6]) to use and the second part specifies the Perforce depot path. Perforce data is fetched using git p4 <option> [7] command. This requires a host to have both Git and Perforce’s Helix Command-Line Client (P4) installed. Content from a Perforce depot will be fetched and archived into a file during fetch stage. Once a cached archive is made, the fetch stage ill be skipped unless the archive is manually removed.

rsync site¶

To define an rsync-based location, the site value must be prefixed with an rsync+ value. A site can be defined as follows:

LIBFOO_SITE = 'rsync+<source>'

The value of <source> will be provided to a rsync call’s [8] SRC value. Fetched content will be stored in an archive inside the dl directory. Once fetched, the fetch stage will be skipped unless the archive is manually removed. By default, the --recursive argument is applied. Adding or replacing options can be done by using the LIBFOO_FETCH_OPTS option.

SCP site¶

To define an SCP-based location, the site value must be prefixed with a scp+ value. A site can be defined as follows:

LIBFOO_SITE = 'scp+[user@]host:]file'

The value after the prefix is a path which will be provided to a scp call’s [9] source host value. The SCP site only supports copying a file from a remote host. The fetched file will be stored inside the dl directory. Once fetched, the fetch stage will be skipped unless the file is manually removed.

SVN site¶

To define a Subversion-based location, the site value must be prefixed with a svn+ value. A site can be defined as follows:

LIBFOO_SITE = 'svn+https://svn.example.com/repos/libfoo/c/branches/libfoo-1.2'

The value after the prefix is a path which will be provided to a svn checkout call [10]. Content from a Subversion repository will be fetched and archived into a file during fetch stage. Once a cached archive is made, the fetch stage will be skipped unless the archive is manually removed.

URL site (default)¶

All packages that do not define a helper prefix/postfix value (as seen in other site definitions) or do not explicitly set a LIBFOO_VCS_TYPE value (other than url), will be considered a URL site. A URL site can be defined as follows:

LIBFOO_SITE = 'https://example.com/my-file'

The site value provided will be directly used in a URL request. URL values supported are defined by the Python’s urlopen implementation [11], which includes (but not limited to) http(s)://, ftp://, file:// and more.