Because of the latency involved, external items shared in a shared folder on a server or a file sharing service are never truly in-sync with one another. While this technique works with a single developer across two or three projects, it gets more and more complicated as you add more projects and even more-so if you try to add more developers.

One of the largest issues with this type of system is that everything must be kept in sync all the time. Making one little change to a shared file or method which works fine in the current project could completely break a project that you haven’t worked on in a year. When you do get around to working on it again, there’s three possibilities:

1. The project compiles and everything works just like it did before.
2. The project doesn’t compile.
3. The project compiles and doesn’t work like it did before.

With careful planning, you’ll probably hit #1 75% of the time, but the other two are wrought with problems. If the project compiles but doesn’t work correctly, you may not find out until you’ve given it to your users, with the worst case being unrecoverable data corruption. If it doesn’t compile, then what? The shared code is now required to be different in two different projects and you may have no history as to what was changed.

Thankfully the folks at who are maintaining Subversion at the Apache Software Foundation made it super easy to create shared code repositories using a feature called Externals. (For those of you that are using Git, I suggest looking into Submodules. Of the two techniques I’ve encountered, Submodules seem to require the least individual overhead.)

SVN Externals

SVN Externals are exposed as a property (svn:externals) on the containing folder and is set up using the svn propset or svn propedit commands, but most SVN visual clients have an interface for creating an SVN External to make the process easier. Once it’s set on a versioned directory, everyone who checks out or updates the working copy also gets the external definition.

It’s worth keeping in mind that because an SVN External definition points to a specific place within another repository, that this other location is also versioned. That is, you can (and probably should) point an external definition at a particular revision within that repository unless there’s a very good reason to always be pointing at the latest/greatest version. This helps alleviate the problems with shared library changes. Once you have it working for a particular version, you can lock-in to a particular date/time until you’re ready to check with a newer version.

Externals in Xojo

Setting up externals for use with a Xojo Text Project is fairly simple to do. As an example, let’s say you have two projects … ProjectX and ProjectY. ProjectX contains some items that you’d like to share with ProjectY.

1. Within Xojo, Open ProjectX and make a folder named “Shared_Items” and move any items you wish to share into this folder.
2. Save ProjectX and close it.
3. Quit the IDE.
4. Depending on whether you’re using a visual SVN client or the SVN command line the steps are similar:
   1. Go to the directory above where the “Shared_Items” folder is located in ProjectY
   2. Remove the empty “Shared_Items” folder.
   3. Add an SVN external with the name “Shared_Items” which points to the Shared_Items in the other repository (or branch or wherever it is).
      1. If you’re doing this using the command line, the command is:
         svn propset svn:externals "Shared_Items https://path/to/other/Shared_Items" .
         If you want to lock the project to a particular revision, you’ll need to tell SVN which revision to use:
         svn propset svn:externals "Shared_Items -r12345 https://path/to/other/Shared_Items" .
         Each of these commands are basically saying: Create a new external named “Shared_Items” using the https://path/to/other/Shared_Items source in the local directory (.), with the second one specifying that you want to use revision 12345.
      2. If you’re using a GUI client you usually select the parent folder and then add an external definition from there. There are usually fields for specifying the Local Path (Shared_Items), URL (https://path/to/other/Shared_Items) and Revision (either HEAD or a specific revision number)
   4. Now you need to update the contents of the folder.
      svn update Shared_Items
5. Open ProjectY.
6. Drag the “Shared_Items” folder from the project folder directly into your project. DO NOT SAVE YET. Any modules which contained other items will be represented by a Module in the project and an identically named Folder which contains the items that should be put inside the module.
7. Referring back to Project X, drag each of the items in Shared_Items to its corresponding location in ProjectY. It’s very important that the on-disk representation in both projects be identical, so make sure you’re using the same version of Xojo in both projects. For example, if after dragging in the Shared_Items folder, you might have:

   Shared_Items
     Module1 (Module)
     Module1 (Folder)
       Class1
       Module2 (Module)
       Module2 (Folder)
         Class2

8. If you have multiple levels of nested modules, I suggest working from the bottom up, that is from the lowest directories up to the highest ones to avoid confusion. Once you’ve emptied a folder, delete it. Using the example above:
   1. Drag Class2 from the Module2 folder directly into the Module2 module.
   2. Delete the Module2 folder.
   3. Drag Class1 from the Module1 folder directly into the Module1 module.
   4. Drag Module2 module into the Module1 module.
   5. Delete the Module1 folder.
9. Once the structure looks the same between the two projects, Save ProjectY. You’ll notice that on disk the folders are still there. That’s exactly what you should see. Check your SVN client, there should be no changes to be checked in. If there are, make sure they’re not file additions and/or deletions.

From now on (if you’re using a non-revision specific external), whenever you make a change to one of the items in this Shared_Items folder and check them in, they’ll be available to any other projects that use them, whether it’s the original items or any project where this folder is defined as an external.

While this looks really complicated to set up, once it’s done using the external will work and feel just like any other folder in your project.

A few things to remember:

1. Make sure you’ve named the shared items container so that it’s obvious that the items are shared between projects, so things don’t get inadvertently dragged into the folder if they’re not needed anywhere else and not dragged out of the folder if they are.
2. Make sure everyone on your team understands that this code is shared among projects.
3. Write Unit Tests for your shared items so when making changes you can verify that you’re not breaking other projects or inadvertently changing their behavior.

• Source control webinar
• Getting to Know Git, part 1 webinar
• Getting to Know Git, part 2 webinar
• Saving your Sanity with Git for Source Code Management XDC 2015 session
• Using Git with Xojo
• Mercurial and Xojo

Source control tracks your changes, can serve as a backup and allows you to try new and different things without fear of completely breaking your code (because you can always go back to a prior, working version of the source).

Since we talk about why you should be using source control so much, I thought I would point out some companies that provide hosted source control and some tools to help you use source control with Xojo.

Now remember, you can use Xojo with any source control system, but you’ll want to use the Text Project format which is available in licensed versions of Xojo (Desktop and higher). The Text Project format is not available with Single Desktop or the Free version of Xojo.

Subversion

Subversion is an open-source version control system made by the Apache folks. It is widely used and relatively easy to understand, using a centralized server as the master repository (or repo) for your source code.

• BitBucket
• Beanstalk (free plan available)
• Assembla (free plan available)

You’re likely to want to use a Subversion client app to make working with Subversion as easy as possible. Here are some that are available:

• Xversion (Mac)
• Versions (Mac)
• Cornerstone (Mac)
• SmartSVN (Mac, Windows, Linux)
• TortoiseSVN (Windows)

Git

Git is a “free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency”. With a distributed system, the full repo is available at each user. You can commit locally before pushing changes up to a central server for others to see.

• GitHub (free plans available)
• GitLab (free plans available)
• BitBucket (free plan available)

And here are some Git clients:

• SourceTree (Windows, OS X)
• GitHub (Windows, OS X)
• Tower (OS X)
• TortoiseGit (Windows)
• SmartGit (Windows, OS X, Linux)

Learn how to Start and Open-Source Xojo Project on GitHub.

Mercurial

Mercurial is a “free, distributed source control management tool. It efficiently handles projects of any size and offers an easy and intuitive interface”.

• BitBucket (free plan available)

Which Should You Use?

There is no right answer to this question. I have used Subversion and Git (and others), but not Mercurial. In my opinion, Subversion is easier to learn than Git, but it is less flexible. These days my preference is to use Git.

Of course, there are lots of other source control systems that exist, but the above are the major ones. If you are already using another source control system with other tools, rest assured that it will also work just fine with Xojo.