Linking to libraries in your projects
If you happen to use external libraries in your projects, you often find that you add the whole library into your project and commit it into your project repository. This ends up with a whole lot of external sources choking up your project. This also prevents maintaining newer versions of those libraries in your project in an efficient manner as there is no record of what version of the library was used.
Externals definitions
Fortunately, Subversion provides support for externals definitions. An externals definition is a mapping of a local directory to the URL – and possibly a particular revision – of a versioned resource. In Subversion, you declare externals definitions in groups using the svn:externals property. You can create or modify this property using svn propset or svn propedit commands. It can be set on any versioned directory, and its value is a multi-line table of subdirectories (relative to the versioned directory on which the property is set) and fully qualified, absolute Subversion repository URLs.
The convenience of the svn:externals property is that once it is set on a versioned directory, everyone who checks out a working copy with that directory also gets the benefit of the externals definition. In other words, once one person has made the effort to define those nested working copy checkouts, no one else has to bother. Subversion will, upon checkout of the original working copy, also checkout the external working copies. Lets look at an example:
I am in a project library directory located under “/project/library/wysiwyg” and I need to link the fckeditor library into my subversioned project. The wysiwyg folder is already part of the project. So now lets add a property file which will hold the information of the externals definitions.
We will create a file called externals in the wysiwyg folder.
vim externals
..and add the following property values:
fckeditor -r222 http://svn.fckeditor.net/FCKeditor/trunk
fckeditor is the local directory which will contain the library we want to map against an external source. -r222 means the project should link to revision 222 of the external library source. And the last part of the externals definitions is the actual repository URL. In this instance, I am tracking the trunk of the FCKeditor project. Now you might think its bad to track to the trunk of a project as it might not be stable. But if you observed, I am not tracking the HEAD of the trunk but a particular revision of the project. If you look up that revision of the project, you will note that -r222 was the revision when FCKeditor released version 2.4.1 of their project.
Having setup the externals definitions config, now lets set the wysiwyg folder to the externals property we defined. Execute the following command from within the wysiwyg folder:
svn propset svn:externals -F externals .
What that command does is, it sets an “externals” property to the wysiwyg folder with the externals definitions available in the “externals” config file. If everything went ok, subversion should respond with the following:
property 'svn:externals' set on '.'
Next we need to get our working copy of the libraries in the “wysiwyg” folder. We do a normal “svn up” and it should fetch the contents of the FCKeditor into a folder called fckeditor (as thats what we told it to do in the config file). Now to benefit from this setup, we add and commit the “externals” config file as being part of your project. Some time in the future FCKeditor will release version 2.5.0 of their project and all you have to do is update the “externals” config file with the correct revision number of the FCKeditor project, update the folder with the “svn propset” command, “svn up” and presto you have a stable library version for the working copy of your project.
Verifying svn:externals
To verify an externals property of a folder, you can execute the following syntax:
svn propget svn:externals .
and it should tell you the “wysiwyg” folder has an externals config of
fckeditor -r222 http://svn.fckeditor.net/FCKeditor/trunk