---
title: Package import
sort_info: 250
---

As [we already mentioned](index.html), the source.yml file contains information
on where to import the source packages from. This information is included in the
version\_control field of the source.yml, and is of the general form:

{coderay:: yaml}
version_control:
    package_name:
        vcs_def
    package_name:
        vcs_def:
{coderay}

Autoproj follows the following rules to find the importer definition for a given
package:
 
 - it looks *in reverse order* in the package sets listed in the manifest file,
   and will take the definition from the *first* package set that has one.
 - in the source.yml file, it will match the package's name with the
   package\_name fields. It will consider every matching block (i.e. every
   package\_name that matches), overriding earlier options by later ones.

As an example, let's consider the following manifest:

{coderay:: ruby}
package_sets:
    - rubim.base
    - rubim.orocos
    - rubim.drivers
{coderay}

Now, let's assume that the rubim.orocos package set has a source.yml file with:

{coderay:: ruby}
version_control:
    - orocos/:
        type: git
        url: git://github.com/$PACKAGE.git
    - orocos/orocos.rb:
        branch: roby
{coderay}

Finally, the rubim.drivers package set has:

{coderay:: ruby}
version_control:
    - orocos/logger:
        type: git
        url: git://github.com/$PACKAGE.git
        branch: perf
{coderay}

Then, the following will happen:

 * all packages that are prefixed with "orocos/" will match the general
   definition of rubim.orocos.
 * in addition, the 'branch' flag of orocos/orocos.rb will be overriden from
   'master' (the default) to 'roby'
 * in the case of orocos/logger, since there is a matching definition in
   rubim.drivers, the definition in rubim.orocos *is not used at all*. Only the
   definition found in rubim.drivers' source.yml file matters.

The remaining of this page will detail the various options that exist to import
a source package.

Git {#all_importers}
\--- 

The general setup for git imports is:

{coderay:: yaml}
version_control:
    package_name:
        type: git
        url: repository_url_or_path
        branch: branch_name
        tag: tag_name # it is branch OR tag
{coderay}

Autoproj will maintain an 'autobuild' remote on the checked out repository:
i.e., it will make sure that the URL of this remote is always linked to the
right URL from the config file, and will update the relevant branch on update
(beware: the other branches won't get updated).

Moreover, autoproj will make sure that updating your local repository always
resolves as a fast-forward (i.e., it will never create a merge)

Subversion
----------

The general setup for subversion imports is:

{coderay:: yaml}
version_control:
    package_name:
        type: svn
        url: repository_url_or_path
{coderay}

Note that the repository *must* be accessible without any password, and the
import will fail if a password was needed.
{: .warning}

Tar archives
------------

{coderay:: yaml}
version_control:
    package_name:
        type: archive
        url: http://sourceforge.net/blablabla.tar.gz?option=value
        filename: blabla.tar.gz # Optional: if the file name cannot be inferred from the URL
        no_subdirectory: false # Optional. Set to true if there is not a leading directory in the archive
        update_cached_file: false # Optional. Set to false to disable automatic updates
{coderay}

The importer expects that there is a leading subdirectory in the archive, under
which all files. If that is not the case, i.e. if all files are in the root of
the archive, do not forget to set the no\_subdirectory option.

Autoproj tries to guess what is the name of the downloaded file by extracting it
out of the URL. Sometimes, this does not work as the URL does not fit the
expected scheme -- in these cases you will get a tar error on update. To
override this autodetection behaviour, set the filename option to the actual
downloaded file name.

By default, autoproj will check if the downloaded file has been updated on the
server, and will download it again if it is the case. If you are downloading
release tarballs, this is unneeded as the archive should not be updated. In that
case, set the update\_cached\_file option to false to save the time needed to
check for the update (can be long on, for instance, sourceforge). The source
will of course be updated if you change the URL (i.e. to download a new release
of the same software).

Patching the source once it is checked out/updated
--------------------------------------------------

It is possible to apply patches after a given package (imported by any of the
importer types) has been checked out/updated. To do so, simply add a
<tt>patches:</tt> option in the importer configuration, that lists the patches
to apply:

{coderay:: yaml}
version_control:
    package_name:
        type: archive
        url: http://sourceforge.net/blablabla
        patches:
            - $AUTOPROJ_SOURCE_DIR/blablabla-01.patch
            - $AUTOPROJ_SOURCE_DIR/blablabla-02.patch
{coderay}

Note that in the example above, the patch is saved in the package set's folder
(the value of AUTOPROJ_SOURCE_DIR). This is a highly required practice.

Note that if the patch list changes (i.e. the *names* change), autoproj will
automatically unpatch and repatch as required. It is therefore highly required
to change the patch name if the patch changes.