Revision as of 11:58, 23 March 2015

Welcome

This part of the Wiki is dedicated to developers who would like to implement their own plug-ins for AnyWave.

Build the SDK

Before developing a plug-in for AnyWave, the developer must download and build the SDK.
The SDK is available here: https://github.com/anywave/aw-sdk
Note that you can also try to build the complete AnyWave software which includes the SDK.
AnyWave git repository is available here: https://github.com/anywave/anywave

Clone the SDK repository

We suggest cloning the repository in a folder named AwSDK_src (for example) to make a clear difference between source folder and build folder.

• On Linux or Mac systems this can be done in a terminal with the following command: git clone https://github.com/anywave/sdk AwSDK_src
• On Windows, we strongly suggest to install the TortoiseGit Software, freely available at https://code.google.com/p/tortoisegit/wiki/Download

Software requirements

A C/C++ compiler is required. Linux and Mac versions of AnyWave were built using the gcc/g++ compiler which is the most common compiler on these platforms.

The Windows version was built with Visual Studio 2008, so it is strongly advised to use the same IDE to build plug-ins that will run with the Windows version of AnyWave.
However, it is possible to rebuild the complete AnyWave application using another C++ compiler and to set that version as the SDK to build plug-ins.
This choice will raise a binary incompatibility with the distributed Windows package and the developed plug-ins. See AnyWave compatibility section.

On Mac OS X, XCode must be installed to provide access to the gcc/g++ compiler.
XCode.app is freely available on the App Store.

To successfully build the SDK, at least three software must be installed on the computer:

• The Qt4 framework
• The VTK library (version 5.4.2 to 5.8 will work)
• CMake 2.8 or greater.

Qt Framework

Mac Developers can download the Qt framework here: Qt Framework for Mac

Linux developers can install the Qt frameworks by installing the qt4-dev-tools package.

Windows developers can download source versions of Qt here: http://download.qt.io/archive/qt/4.8/4.8.6/

Build Qt from source with Visual Studio to match the binary version of AnyWave.

VTK Library

Have a look at the VTK Wiki page to build VTK for your system.

Note that you must build the VTK versions 5.4 to 5.8.

Versions 6.x are not compatible with the current version of AnyWave.

AnyWave compatibility

When building a plug-in, the developer has two choices:

• Build for the currently distributed binary version of AnyWave.
• Build for its own AnyWave version built from the sources available on github.

Plug-ins for the binary distributed package of AnyWave

Pay attention that if the plug-in must work with the distributed binary versions of AnyWave it must match more requirements:

• Qt4 must be 4.8.2 to work with the Linux debian packaged version of AnyWave.
• Qt4 must be 4.8.1 to 4.8.5 to work with the Mac OS X version.
• Qt4 must be 4.8.1 to 4.8.6 to work with the Windows versions. (Note that the Windows version will soon only support 64bit systems)
• VTK library must be 5.4.2 to 5.8.xx (VTK 6.x will not work)

The Linux and Mac versions have been built with the gcc compiler and therefore will use the glibc library.
On Mac systems, the XCode software must be installed to get access to the gcc compiler.

ATTENTION: The Windows version of AnyWave was built with Visual Studio 2008. Therefore, the plug-in must also be built using Visual Studio 2008 for binary compatibility.

Plug-ins for the developer version of AnyWave

If a developer plans to build plug-ins that will stay private, it is up to him/her not to match the requirements previously mentioned.

Building AnyWave from sources and use it as the SDK

As mentioned before, the developer is free to use the complete AnyWave source code as SDK.
The requirements to build AnyWave are the same than for the SDK.
Follow the instructions available when cloning the anywave repository to build AnyWave.

Choose the SDK folder

The first thing to do is to create a build folder with an explicit name, for example: AwSDK, that will be the root of the SDK.

We will consider for the following explanations that the folder is named AwSDK and is located in /home/user/Dev/AwSDK
We will consider that the git repository was cloned in a folder named AwSDK_src

Run cmake

Open a terminal and go to the SDK folder:
cd /home/user/Dev/AwSDK

Launch cmake from the source repository:
cmake ../AwSDK_src

If Qt and VTK were successfully detected, then type:
make install

This will build install headers and libraries in the AwSDK folder.
You are ready to build a plug-in.

How to use the SDK

A regular AnyWave plug-in is a C++ project that will be using C++ objects defined in the SDK.

So, before creating a project to build a plug-in, the SDK must be correctly configured.
This is easily done by defining an environment variable called AWSDK that must contain the path to the SDK folder location.

On Linux and Mac systems this can be accomplished by adding the two following lines to your .bashrc file:
AWSDK=/home/user/Dev/AwSDK
export AWSDK

On Windows, this can be done by opening the Security and System/System panel.
Then click on the left part of the window on Advanced properties.

NOTE: close and re-open the terminal for the changes to be applied.

[AnyWave:PrepareCMake|Prepare a cmake project to build a plugin]

Prepare a project to build a plug-in

Now that the SDK was built and correctly configured, it is time to set up a new project to build a plug-in.

AnyWave plug-ins are built using cmake. Thus, a project is nothing else than a cmake project describing how to use to SDK and the Qt Framework.

Basic CMake project

Create a folder that will be your plugin's project (for example MyPlugin).

Create the CMakeLists.txt file which is the CMake project file.
Here is an example of a CMakeLists.txt file:

# My plugin
CMAKE_MINIMUM_REQUIRED(VERSION 2.8)
PROJECT(MyPlugin)
# Build in release mode
SET(CMAKE_BUILD_TYPE "Release")
# Flags for gcc compiler and macro definitions 
ADD_DEFINITIONS("-fPIC -O3")
SET(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -DNDEBUG")
 
# Check for SDK
SET(SDK_FOUND 0)
IF( "$ENV{AWSDK}" STREQUAL "" )
   MESSAGE(STATUS "AWSDK environment variable not set." )
   MESSAGE(STATUS "On Linux or Mac OS X this can be done in your user .bashrc file by appending the corresponding line, e.g:" )
   MESSAGE(STATUS "export AWSDK=/home/user/dev/SDK" )
   RETURN()
ELSE()
   SET(SDK_FOUND 1)
   SET(SDK_ROOT $ENV{AWSDK})
   MESSAGE(STATUS "AWSDK found: ${SDK_ROOT}")
ENDIF()
 
# Add the current folder as include directroy
SET(CMAKE_INCLUDE_CURRENT_DIR ON)
 
# Link using SDK libraries
LINK_DIRECTORIES(${SDK_ROOT}/lib)
# Include SDK headers
INCLUDE_DIRECTORIES(${SDK_ROOT}/include)
# Include current source dir as header dir
INCLUDE_DIRECTORIES(${CMAKE_SOURCE_DIR})
INCLUDE_DIRECTORIES(${CMAKE_CURRENT_DIR})
 
# Find Qt
FIND_PACKAGE(Qt4 REQUIRED)
INCLUDE(${QT_USE_FILE})
ADD_DEFINITIONS(${QT_DEFINITIONS})
# Add some definitions to point out that the project must build a Qt plugin
ADD_DEFINITIONS(-DQT_PLUGIN)
ADD_DEFINITIONS(-DQT_SHARED)
 
# Define the output directory depending on platform
IF (APPLE)
   SET(LIBRARY_OUTPUT_PATH ${SDK_ROOT}/bin/Anywave_Plugins)
ELSE()
   SET(LIBRARY_OUTPUT_PATH ${SDK_ROOT}/bin/Plugins)
ENDIF()
 
 
# Plug-in specific part begins here
# Add source files for your project here:
# For example:
# SET(SRCS myplugin.cpp 
#   mylib.cpp)
 
# Add headers that need to be parse for Qt Signal and Slots mechanism.
# Those files need to be parse by the MOC tool of Qt to correctly compile signals and slots
# Example:
# SET(MOCS myplugin.h)
# Note that header files which are not describing Qt Objects won't be parse by the MOC tool.
 
 
# Depending on the plug-in type, your project may contain User Interfaces designed with the Qt Designer tool.
# To add UI files to your project, simply define a variable that will contain all the .ui files of your project.
# Example:
# SET(UIS myplugin.ui)
 
# Depending on the plug-in, your project may contain a Qt Resource file (.qrc)
# If so, add the file into a variable like this:
# QT4_ADD_RESOURCES(MyPlugin_QRC myplugin.qrc)
 
# Now call the MOC tool for header files
QT4_WRAP_CPP(MyPlugin_MOCS ${MOCS})
 
# If you have ui files, call the iuc tool:
# QT4_WRAP_UI(MyPlugin_UIS ${UIS})
 
# If your plug-in is using external libraries, you may define them here:
# Example of a plugin using the Qwt library
# SET(QWT_INCLUDE /home/dev/qwt/include)
# SET(QWT_LIB /home/dev/qwt/lib)
# INCLUDE_DIRECTORIES(${QWT_INCLUDE})
# LINK_DIRECTORIES(${QWT_LIB})
 
 
# define the library to build (the Qt Plugin)
ADD_LIBRARY(MyPlugin SHARED ${SRCS} ${MyPlugin_MOCS} ${MyPlugin_UIS} ${MyPlugin_QRC})
 
# remove ${MyPlugin_UIS} ${MyPlugin_QRC} if your project does not contain QRC or UI files
 
# Target
TARGET_LINK_LIBRARIES(MyPlugin AwCoreLib ${QT_LIBRARIES})
# This will tell cmake to link the plugin using AwCoreLib, which is the core library of AnyWave, and the Qt Libraries.
# Depending on your plug-in, extras libraries should be added.
# For example, if your plug-in is using graphics objects defined in the SDK, you must add AwGraphicsLib as a library.
# If the plug-in is a reader or a writer plug-in, you must add AwReadWriteLib
# If the plug-in is a signal processing plug-in, you must add AwProcessLib
 
# If your plugin must link with Qwt then the line should be:
#TARGET_LINK_LIBRARIES(MyPlugin AwCoreLib qwt ${QT_LIBRARIES})