Including papaya CMS via SVN externals
From PapayaCMS
When you are working on a web project with papaya CMS and are using subversion for source control, you can include directories from our public papaya SVN into your subversion projects using a mechanism called svn externals. You don't need to export the latest stable release of papaya CMS from the papaya SVN and check it into your subversion repository.
Contents |
What are Externals?
An external is a directory or project which is controlled in an external subversion repository. In case you want to include the source code of such external projects in your own project without having the hassle of updating each change manually, you can define an externals subversion property for a directory in your project. When you check out or update your project, the source code of the external code is also automatically updated from the external repository. As a result, you will always have the latest bugfixes and features.
You can create an external by setting a svn:external property for a directory. The console command has the following form:
svn propedit "svn:external" system http://svn.papaya-cms.com/trunk/papayaCMS/papaya-lib/system
This command sets ans svn:external property in the current directory. The svn:external property includes the external project directory papaya-lib/system from the trunk of the papaya SVN into the local directory 'system'. This directory does not exist.
Now you need to call 'svn update. During the update, subversion first creates the missing directory system and checks out all the code from the remote repository directory specified in the external property.
How the SVN repository is organized
The following table describes the basic directories of the papaya CMS repository. Developers who are already aquainted with source control tools like SVN or CVS will probably know what these directories mean:
| Path | Meaning |
|---|---|
| svn.papaya-cms.com/trunk | Directory that contains the current development version. |
| svn.papaya-cms.com/tags | Directory that contains the stable versions of papaya CMS. |
| svn.papaya-cms.com/branches | Directory that contains the (stable) builds. |
When you plan to include external source code into your project, you will usually want to have a stable version, not the development version. When you include the trunk version as an external, you may run into trouble if the code in the trunk contains an error because new modules or features haven't been tested yet. So you want to exclude the possibility that a bug stemming from external code is wrecking your project.
We advise you to use the latest stable branch which can be found in the branches directory. If you want to use the release version only, you can take a look at the tags directory. The tags directory has the following naming convention for release directories (all directories start from the repository's base url):
./tags/<version number>/papayaCMS/
The element <version number> can be replaced with the number of the release version of papaya CMS. The current (April 29. 2010) release of papaya CMS is 5.0.5. In ./papayaCMS/, you can find all directories of the papaya release.
Selecting directories for externals
You can link the following directories from the latest tagged papaya CMS into you svn project using the external mechanism (All paths start from the current tag directory ./tags/5.0.5/papayaCMS):
./papaya
Next, you need to create the following directories in your svn project:
- papaya-lib and papaya-lib/modules
- papaya-data and papaya-data/templates
- papaya-themes
Defining externals in the papaya-lib directory
In the directory papaya-lib, you need to create the following externals to the aforementioned papaya-tag (./tags/5.0.5/papayaCMS/):
./papaya-lib/system ./papaya-lib/external
In ./papaya-lib/modules, you need to create the following externals from the aforementioned papaya-Tag:
./papaya-lib/modules/_base/ ./papaya-lib/modules/free/ ./papaya-lib/modules/gpl/
Defining externals in papaya-data
In case you want the demo template in your project---if you want a reference implementation for your own templates, for instance---you can include the following directory from the papaya-tag as an external into your project. The following example assumes you have created the directory papaya-data/templates:
./papaya-data/templates/default-xhtml
To make sure that the demo template will work correctly, you also need to include the suitable theme as an external. The following directory needs to be included in the papaya-themes directory:
./papaya-themes/default
Run svn update
Thats it. All you need to do now is run svn update. This will cause subversion to pull all the external source code into your project.
NOTE: Make sure that you commit all your changes to the directories before running svn update. A commit needs to be done when you add, delete or edit the properties of a directory. This also holds for the svn:external property.
