History: StaticLinking

Source of version: 5 (current)

%prevogre%
These notes explain how to statically link Ogre. Official support for static linking was introduced in ((EihortNotes|1.4.x (Eihort))). Static linking can be used to embed Ogre (including plugins) in your own application's executable rather than as a set of dynamically linked libraries.

{maketoc}

!!Legal Considerations
Firstly, lets get the legalese out the way. Linking Ogre statically to your code carries additional responsibilities under the [http://www.gnu.org/licenses/lgpl.html|LGPL license] which you must comply with. Normally, that would mean that if you statically linked, you would have to comply with more stringent conditions than if you dynamically linked.

However, OGRE added an exclusion to its license as of 1.6.2 which means the conditions for linking OGRE statically are no different to linking it dynamically. We don't think it's a material difference and that the user should only be required to release changes to OGRE, not their own application, regardless of how they link.

!!Microsoft Visual C++
!!!Building Ogre Statically
Firstly, you need to build Ogre statically. In Visual C++ 2005, the static link targets are in the main Ogre_vc8.sln so just load that as normal. In Visual C++ 2003, they are in a separate solution OgreStatic.sln because of a limitation in the way dependencies are determined in that version.

Build targets called DebugStaticLib and ReleaseStaticLib exist for OgreMain and all the plugins and rendersystems, so build those. They will produce static libraries of the form ProjectNameStatic[[_d].lib in ogrenew/lib. Don't worry about the size of them, when finally linked with optimisation this will reduce substantially.

!!!Altering Your Project Files
!!!!Core Linking
* Define OGRE_STATIC_LIB in your application's preprocessor settings
* Link to OgreMainStatic[[_d].lib instead of OgreMain[[_d].lib

This is enough to link to get the core running, say for tools. If you need any plugins (rendersystems, scene managers etc), then you need to do more, see the next section.

!!!!Plugins
Since you will not be loading plugins from DLLs anymore, your application needs to decide what plugins it is going to use at compilation time, and specifically register them.

Every plugin has a subclass of Ogre::Plugin defined in it, usually in a separate header file. When loading a plugin dynamically, the dllStartPlugin entry point on the DLL is automatically called, which will then instantiate a copy of this plugin class and register it by calling Ogre::Root::installPlugin. When linking statically, you have to do this instead. The steps are:

* Add the folder containing the plugin header file to your projects include path, e.g. ogrenew/Plugins/ParticleFX/include
* Add the plugin's static library to your linker path, e.g. Plugin_ParticleFXStatic[[_d].lib
* At some point during your application's initiation sequence, after Root has been created, instantiate and register the plugin, e.g.

{CODE(wrap="1", colors="c++")} #include "OgreParticleFXPlugin.h"
 ..
 ..
 // Assumes mParticlePlugin is a member variable in your class somewhere
 mParticlePlugin = new ParticleFXPlugin();
 Root::getSingleton().installPlugin(mParticlePlugin);
{CODE}

* Ensure that you are not supplying plugins.cfg (or equivalent) when creating Root, pass in an empty string
* If you are using Root::restoreConfig, make sure this is done __after__ the rendering plugin is installed
* If you want to unload plugins early, you can do so by calling Root::uninstallPlugin although you don't have to do this since when Root shuts down, it automatically safely terminates and removes the plugins. Doing it manually has to be done carefully in case there are cross-plugin dependencies, e.g. one plugin creating rendersystem resources from another plugin.
* Delete your plugin instances at some point ''after'' Root has been shut down, or after you manually uninstalled the plugin.

There is an example helper class for using plugins statically in the PlayPen tester application, see [http://ogre.cvs.sourceforge.net/ogre/ogrenew/Tests/PlayPen/include/StaticPluginLoader.h?view=markup|StaticPluginLoader.h].

!!!!Resource Files
If you use the default config or error dialogs, you will need the Windows resources to go with them. These are compiled into OgreWin32Resources[[_d].res and are located in the ogrenew/lib folder with all the other libraries. Add this file to your linker just like a regular .lib file to embed the dialog resources in your own executable so that they can be used. Normally these resources are embedded in OgreMain[[_d].dll but since we're linking statically, your own binary has to carry them.
History: StaticLinking

Source of version: 5 (current)

Search by Tags

Latest Changes

Search

Online Users
