.. _site_definitions:

Site definitions
~~~~~~~~~~~~~~~~

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

.. note::

   All site values can be defined with a prefix value (e.g. ``git+`` for Git
   sources) or postfix value; 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:

.. code-block:: python

   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 [#bzrexport]_. 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:

.. code-block:: python

   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 [#cvsroot]_ to use and the second part specifies the CVS
module [#cvsmodule]_  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:

.. code-block:: python

   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 [#gitremote]_ 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).

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:

.. code-block:: python

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

The value after the prefix is used as the ``SOURCE`` in an ``hg clone`` call
[#hgclone]_. 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).

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:

.. code-block:: python

   LIBFOO_SITE = 'rsync+<source>'

The value of ``<source>`` will be provided to a ``rsync`` call's
[#rsynccommand]_ ``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:

.. code-block:: python

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

The value after the prefix is a path which will be provided to a ``scp`` call's
[#scpcommand]_ 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:

.. code-block:: python

   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 [#svncheckout]_. 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:

.. code-block:: python

   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 [#urlopen]_,
which includes (but not limited to) ``http(s)://``, ``ftp://``, ``file://`` and
more.

See also |CONF_URLOPEN_CONTEXT|_.
