-
Notifications
You must be signed in to change notification settings - Fork 8
External Application
The External_Application Shawn module allows to easily create your shawn applications outside Shawn's build path, without having to mess up too much with the internals of Shawn. The users of this application only have to implement one initialization method which gets called by Shawn at runtime to initialize all new elements created for the application. Everything else, besides the new elements created for the application, is provided by the Shawn libraries automatically. The output of such an external project, if setup was correct, is an executable program that works just like the normal Shawn executable, with all self-written elements available.
One of the first tasks done by Shawn when executing it, is to initialize the simulator itself and all enabled applications (aka modules). For this, every application provides an initialization method. Inside this method, all elements added by the application to Shawn get initialized and are made available to Shawn. For example, when implementing a new processor for the application, Shawn has to know that this processor exists and how to create instances of it. To do that in this case, a factory creating instances of the processor has to be added to the SimulationController.
What the External_Application module does, is to provide such an initialization method to Shawn, without actually implementing it. As this isn't allowed when creating an executable program, the External_Application module only works when Shawn is compiled with die BUILD_LIB_WITH_MAIN option enabled inside CMake. This way, only libs are generated, containing the main method, but not containing the External_Application initialization method.
An application linked against Shawn's lib files created this way, has basically only to provide this initialization method.
To enable the External_Application, follow the steps below:
- Startup CMake using either the CMake GUI or calling "ccmake ../src" inside the buildfiles directory of Shawn
- Enable the "BUILD_LIB_WITH_MAIN" option
- Enable the "CONFIGURE_APPS" option
- Enable the "EXTERNAL_APPLICATION" module (and everything else you need)
- Generate your buildfiles
- Use the generated buildfiles to compile your Shawn libs
Once the libs are generated successfully, create a new project and make sure to add include and lib paths to shawn/src and shawn/buildfiles. Link against the Shawn libs you need and implement the External_Application initialization method like this:
#include "sys/simulation/simulation_controller.h"
void init_external_app( shawn::SimulationController& sc )
{
//Add your initialization code here
}
To clarify how a project using External_Application has to be set up, examples are provided for both makefiles (Unix/Cygwin) and Visual Studio projects (Windows).
This example provides a new processor called HelloWorldExternalProcessor, which just writes a Hello World message to console after a random number of simulation rounds (between round 1 and 11). It also provides a factory called "HelloWorldExternalProcessorFactory" to create instances of this processor type.
Inside the external_application_init.cpp, the External_Application initialization method gets implemented, just to register our new ProcessorFactory to the simulation controller.
Additionally, an example configuration file "example.conf" is provided, which just creates a random world with 20 of our new HelloworldExternal processors. After compiling the project, you may use it e.g. by calling helloworld_external -f "example.conf".
[http://www.ibr.cs.tu-bs.de/users/tbaum/helloworld_external.zip Download Examples]
The example is configured to be in a directory parallel to Shawn. So if Shawn is installed in projects/shawn, this example should reside in projects/helloworld_external. Otherwise you have to change the include and library paths inside the makefile or Visual Studio project accordingly.
When activating Shawn modules others than "EXTERNAL_APPLICATION" for building Shawn, all external libs needed by that module have to be added to the example buildfiles as well. This affects for example the VIS module which depends on cairo, so you have to make sure that cairo and it's dependencies are linked in.
In the CMake configuration of Shawn it is possible to disable the BUILD_SINGLE_LIB option to split up Shawn into several libs. When creating applications based on the "External Application" app, you have to link in the libs of all Shawn apps, which where enabled in CMake for building the Shawn libs, as well as their dependencies. Otherwise you will get linker errors.
It is not possible to just link in the app libs you want to use, as this is only supported when Shawn is compiled with disabled BUILD_LIB_WITH_MAIN option. The reason is, that the initialization method of every lib is called automatically by the built in main method (like the init method of the "External Application" app as well). If the lib is not linked in, these initialization methods cannot be found by the linker.
An alternative solution is to reimplement the initialization methods of the libs that are NOT linked in, just like implementing the "External Application" init method. This way, the linker is able to find these methods even though the libs are not available, and everything should work fine. You should check the lib's dependencies though, as some apps may require another app to work correctly.