Starting Your Own Orca Project

Note:

Reviewed for release 2.10.0.

A common situation is that you want to work on a component outsided of the Orca source tree. This can happen if you want to experiment without the need to keep the code clean and documented (a requirement for Orca SourceForge repository) or you want to work on a closed-source component. In this case you should download and install the main Orca distribution and then setup a parallel workspace for your own project.

Creating a Satelite Project

To help you start quickly we provide a template project which uses CMake, mirrors the setup of the Orca repository and is already set up to find Ice and the Orca installation, etc. You can of course set up a project in any way you like, however you might find this template useful. (We use the export command instead checkout, to avoid manually removing the .svn directories).

$ svn export https://orca-robotics.svn.sf.net/svnroot/orca-robotics/empty/trunk empty-export

We'll walk through the steps of customizing the empty project into a project called 'tractor'.

• Rename the directory 'empty-export' to 'tractor'
• Edit the top level CMakeLists.txt file so it looks like this:

  PROJECT( tractor )
  
  SET( GBX_PROJECT_VERSION            0.0.1       CACHE STRING "Version of 'Empty' distribution" )
  
  SET( PROJECT_INTERFACE_LIB          TractorInterfaces )
  

• Rename interface subdirectories named after the project main namespace:

  $ mv src/interfaces/slice/empty src/interfaces/slice/tractor
  $ mv src/interfaces/cpp/empty src/interfaces/cpp/tractor
  $ mv src/interfaces/cpp/emptyifacestring src/interfaces/cpp/tractorifacestring
  $ mv src/interfaces/cpp/emptyifaceinit src/interfaces/cpp/tractorifaceinit
  

• Edit the corresponding CMakeLists.txt files (e.g. src/interfaces/slice/CMakeLists.txt), change the argument of SUBDIRS() command from 'empty' to 'tractor'.
• Rename the module name in the sample interface .ice file src/interfaces/slice/tractor/someinterface.ice so that the include line looks like this:

  #ifndef TRACTOR_SOME_INTERFACE_ICE
  #define TRACTOR_SOME_INTERFACE_ICE
  
  #include <orca/orca.ice>
  
  module tractor
  {
  

• Edit the source file of the sample component src/components/somecomponent/main.cpp so that the include line looks like this:

  #include <tractor/someinterface.h>
  ...
      tractor::SomeDataPtr someData = new tractor::SomeData;
  ...
      tractor::SomeClassDataPtr someCData = new tractor::SomeClassData;
  

• Edit the source file of the sample utility src/utils/someutil/main.cpp so that the include line looks like this:

  #include <tractor/someinterface.h>
  ...
      tractor::SomeDataPtr someData = new tractor::SomeData;
  ...
      tractor::SomeClassDataPtr someCData = new tractor::SomeClassData;
  

• If you're going to use revision control system (e.g. SVN, CVS), it's a good idea to commit your project to your own repository at this point. All the current files are "raw" files which need to be added to CVS. If you commit later and used an in-source build, raw and generated files will be mixed.

• Run cmake and compile.

This enough to get you started. Now you can start writing code: add your own components, libraries, and interfaces.

Tips for Maintaining a Satelite Project

Versions tags

If this is an internal project, then you probably don't bother realeasing distributions. It's still useful to have a history of working code. It's easy to add a tag when Orca version changes and you made sure that your project compiles with the new version.

In SVN you do it like this, assuming Orca version 2.12.0. URL is the URL to your repository, not Orca's. You can get it easily by typing 'svn info' at the top level of the local copy.

$ svn copy [URL]/tractor/trunk [URL]/tractor/tags/orca-2.12.0 -m "Works with orca release 2.12.0"

(Here's how we used to do the same thing in CVS.)

$ cvs tag -f orca-2.12.0