Working With Examples

This pages briefly explains how the Overture examples are used as part of Overture builds.

The Overture examples and the VDM libs are hosted and maintained at in the documentation repository. However, they are used for a couple of things in normal Overture builds:

• the libs are used as resources when building the ide/ui plug-in. They are needed for the Add VDM library feature.
• the libs and the examples are used as resources when building the ide/help plug-in. They are need for the Import Examples feature.
• the libs and the examples are used as resources for testing various core modules through the testing framework.

Because it's stupid to keep two copies of the examples under source control, we've used various solutions for keeping the examples in the documentation repo and making the main repo "depend on them". Up until recently, we used a maven download plug-in to grab a zip of the entire documentation repository. This worked reasonably well since it was invisible to most developers. But that solution doesn't work anymore*.

*This is because we now need different version of the main repo to depend on different versions of the examples. The symphony and crescendo branches can't depend on the main examples anymore since they won't support pure operations.

In order to depend on different versions we now use git submodules. A submodule lets you mount another git repository inside your current repo. So, we mount the documentation repository under externals/docrepo. From there, we have access to all the examples and the libs. When you clone or pull the main repo, all you get for the submodule is the branch the submodule points to. Ir order to get the actual content, you need to do a git submodule update. We have added an antrun plugin to do this automatically. Whenever you run mvn on the root of the repo (or inside the externals folder), this plugin will execute and you will get the files corresponding to the commit for the submodule. However, all this plugin does is synchronize your disk content with is specified in the current commit of the submodule. If you need to grab changes to the examples,you need to manually up the commit: go inside the submodule and do git pull or do git submodule update --remote from the repository root. The reason for this split is to ensure that all updates to the examples are done explicitly. The plugin is only used to make sure the build doesn't crash when you clone.

That was all very confusing so think of it like this. The plugin downloads the files specified in the submodule. In order to change the specification, you use git submodule update --remote. The change in specification can be committed like any other change. So, if someone else bumps the submodule, you will get that.

To avoid any kind of issues, you should never make or commit changes to the examples via the submodule. Whenever you need to change an example, do so via the documentation repository.