Version 1 (modified by andreasw, 15 years ago) (diff)

first draft

Handling Svn Externals

Externals allow subversion to download additional packages from other subversion repositories. For example, the COIN project Clp requires the COIN project CoinUtils to be compiled. Therefore, the Clp repository has externals defined, so that Clp is automatically downloaded when a user checks out Clp.


Externals are properties associated with directories in a subversion repository (with the name svn:externals). If someone checks out such a directory, the corresponding externals (defined as URL) are also checked out, into subdirectores of that directory. The names of those subdirectories, as well as the URL, are defined in the svn:externals property. It is possible to specify a specific revision number of the externals that is to be downloaded. This helps us in COIN to make sure that people get a compatible version of the dependency; the latest trunk version of the dependency might not work with the code of the package one tries to download and compile, if the development of the dependecy has proceeded.

Externals are checked out recursively, i.e., if there is an svn:externals property defined in an external, it is also downloaded. On can suppress the checkout (or the action of other svn commands) of externals by specifying the --ignore-externals flag.

Externals in COIN

In COIN, we use externals mainly to make sure that COIN packages, which require other COIN packages, obtain the dependency code automatically.

We policy for managing externals in COIN is that we put a file called Externals into the directory, for which the svn:externals property is set. For example, the Externals file in the base directory for the Clp package might look like this:

CoinUtils    -r500

The first column specifies the directory of the base directory, into which the externals is to be downloaded (this can be several levels of subdirectories). After this, one can optionally specify the revision number of the dependency code that it to be obtained (using the -rN flag, where N is the revision number. The last column is the URL that specifies the repository for the dependency.

Changing Externals

To see the value of a property (such as svn:externals one uses the svn propget command. For example, to see the current value set for the externals in the Clp base directory, you go into the Clp base directory and issue the command

svn propget svn:externals .

If you want to change the value of a property, you use the svn propset command. In COIN, we find it good practice to use the Externals file, so that also users that don't have svn can see, what the dependencies are. Assuming that you have edited the Externals file in a directory, you can use this file to update the externals. For this, you enter the command

svn propset svn:externals -F Externals .

The -F flag tells svn to take the content of the file as the value of the property to be set. In order to actually get the code that you specified in the external definition, you need to do an svn update.

Finally, if you decided to get rid of externals in a directory, you should delete the Externals file, and delete the svn:externals property with

svn propdel svn:externals .

Note: If you have configured your local copy with the --enable-maintainder-mode and have svn available on your system, the Makefiles will automatically do the svn propset command for you, when you changed the Externals file. However, you will need to run the svn update command by hand.

More information about externals can be obtained in the Externals Definitions chapter of the subversion book.