ADTF3 Guides - ADTF Plugin Description Generator

ADTF Plugin Description Generator

This guide covers how to integrate your code into ADTF. After reading this guide, you will know:

What the extension points of ADTF are
What a plugin description is
How to create a plugin description

What is the ADTF Plugin Description?

The Plugin Description Generator (PDGen) extracts meta information from an ADTF plugin and stores it in an XML file. Tools such as the ADTF Configuration Editor use the extracted information to provide plugin related functionality without having to load the actual plugin.

To extract information such as any provided and/or required interfaces the PDGen has to actually load the plugin DLL and instantiate the contained ADTF Services and Filters. In some cases it may be necessary to include information which is not provided by the plugin at runtime. To achieve this you can provide an additional plugin description file to be merged with the generated file.

The Plugin Description Generator (PDGen) is located in <ADTF_DIR>/bin/ and <ADTF_DIR>/bin/debug respectively.

For a more technical explanation please follow this link

Extension points

To connect your code with ADTF you can choose from one of these interfaces:

Filters
Streaming Sources
Streaming Sinks
Services
Active Runners
Sample Streams
Binding Proxies

Turn your code into a plugin

We recommend to integrate the plugin description generation into your toolchain as post-build step using the provided CMake support as described and demonstrated in all our programming examples and tutorial here as well. There is no need to use the ADTF Plugin Description Generator as command line tool standalone. See also Best Practice Tooling. All additional information in this guide and listed command line options are just to provide you a deeper understanding.

All begins with a plugin. The SDK provides the ADTF_PLUGIN macro to connect your code with the ADTF world. The macro requires two parameters. The first parameter is the name of your new plugin. The second parameter is the name of the new class representing the plugin. The macro is used like this:

        
ADTF_PLUGIN("ADTF Demo Signal Provider Plugin", cMySignalProviderFilter);

After compiling your project, there will be a file called *.adtfplugin that represents your code as a shared library which ADTF can load at runtime. To make your new plugin available inside the Configuration Editor, you need an XML based description, which the Plugindescription Generator can create for you:

        
adtf_plugin_description_generator.exe --plugin="demo_data_triggered_filter.adtfplugin"

And this is what a *.plugindescription looks like:

CMake Support

This is the recommended way to call the ADTF Plugin Description Generator using our CMake function adtf_create_plugindescription.

For further reference see the function definition and documentation in <ADTF_DIR>/ADTFMacros.cmake and Generate Plugin Description.

Basic

This function takes care of calling the PDGen as part of the build.

Example usage:

                
adtf_add_filter(MyFilter my_filter.cpp my_filter.h)

...

adtf_create_plugindescription(
    TARGET MyFilter
    PLUGIN_SUBDIR "bin"
    VERSION "0.8.15"
    LICENSE "ADTF"
    SUPPORT_MAIL "support@mycompany.org"
    HOMEPAGE_URL "www.mycompany.org"
)

3rd Party dependencies

If your adtfplugin requires addtional shared libraries for plugindescription generation, you can specify the dependencies by using DEPENDENT_DYNAMIC_LIBS.

Example usage:

              
adtf_create_plugindescription(
    TARGET MyFilter
    PLUGIN_SUBDIR "bin"
    VERSION "0.8.15"
    LICENSE "ADTF"
    SUPPORT_MAIL "support@mycompany.org"
    HOMEPAGE_URL "www.mycompany.org" 
    DEPENDENT_DYNAMIC_LIBS
        "$(DEPENDENCY_DIR)/some_lib.dll" 
        "$(ANOTHER_DEPENDENCY_DIR)/path/to/another_lib.dll" 
)

If your adtfplugin requires addtional shared libraries for runtime, you can specify the dependencies by using PLATFORM_DEPENDENCIES, PLATFORM_DEPENDENCIES_RELEASE and/or PLATFORM_DEPENDENCIES_DEBUG.

Example usage:

              
adtf_create_plugindescription(
    TARGET MyFilter
    PLUGIN_SUBDIR "bin"
    VERSION "0.8.15"
    LICENSE "ADTF"
    SUPPORT_MAIL "support@mycompany.org"
    HOMEPAGE_URL "www.mycompany.org" 
    PLATFORM_DEPENDENCIES
        "=(RUNTIME_MACRO)/some_lib.dll" 
        "=(ANOTHER_RUNTIME_MACRO)/path/to/another_lib.dll" 
)

Unfortunately CMake will always resolve any macros specified with $. As you can see here, we created a workaround to store a library in ADTF macro syntax like $(SOME_DIR)/libray.ddl. To do so please use =(SOME_DIR)/libray.ddl and the ADTF Plugin Description Generator will automatically replace the '=' with '$' and store the path as specifed without resolving.

Command line support

Please see the output of a call with --help for all available command line options.

                
Executed call: 'adtf_plugindescription_generator --help'
adtf_plugin_description_generator

Usage:
        adtf_plugin_description_generator --help
        adtf_plugin_description_generator --plugin <pluginfile> [--merge <mergefile>] [--output
          <outputfile>] [--adtf-core-plugin <adtfcorepluginfile>] [--no-system]
          [--ignore-state-errors] [--system <adtfsystemfile>] [--settings <cesettingsfile>]
          [--plugin-version <major.minor.patch>] [--license-name <name>] [--support-mail <email
          address>] [--homepage-url <name>] [--issue-url <name>] [--plugin-directory
          <plugindirectory>]... [--dynamic-link <sharedlibrary>]... [--platform-dep
          <sharedlibrary>]... [--platform-dep-release <sharedlibrary>]... [--platform-dep-debug
          <sharedlibrary>]...

Options:
        --help, -h  Print the usage info and quit.
        --plugin, -p <pluginfile>
                    Path to the .adtfplugin

        --merge, -m <mergefile>
                    Path to the .plugindescription which will be merged

        --output, -o <outputfile>
                    Path to the resulting .plugindescription file

        --adtf-core-plugin <adtfcorepluginfile>
                    Path to adtf_core.adtfplugin (EXPERIMENTAL)

        --no-system Do not load an adtfsystem file at all.
        --ignore-state-errors
                    Ignore errors from changing the state of graph objects to 'constructed'.

        --system <adtfsystemfile>
                    Path to a .adtfsystem file. Providing additional platform dependencies, services
                    and plugins (EXPERIMENTAL)

        --settings <cesettingsfile>
                    (EXPERIMENTAL)

        --plugin-version <major.minor.patch>
                    Plugin version that should be stored in the generated description.

        --license-name <name>
                    License name that should be stored in the generated description.

        --support-mail <email address>
                    Support mail address that should be stored in the generated description.

        --homepage-url <name>
                    Homepage URL that should be stored in the generated description.

        --issue-url <name>
                    Bug/Issue tracker URL that should be stored in the generated description.

        --plugin-directory <plugindirectory>
                    A path containing additional .plugins (EXPERIMENTAL)

        --dynamic-link <sharedlibrary>
                    A list of shared libraries that need to be loaded before the adtfplugin is
                    loaded (for plugindescription generation only, path will be resolved, use macros
                    available in CMake like ${Macro}).

        --platform-dep <sharedlibrary>
                    A list of shared libraries that need to be loaded before the adtfplugin is
                    loaded (for ADTF runtime, all toolchains. Note: Unfortunately CMake will always
                    resolve any macros specified with '$' so to store a library in ADTF macro syntax
                    like $(SOME_DIR)/libray.ddl|so please use =(SOME_DIR)/libray.ddl|so as
                    workaround here, the '=' will be replaced by '$').

        --platform-dep-release <sharedlibrary>
                    A list of shared libraries that need to be loaded before the adtfplugin is
                    loaded (for ADTF runtime, release toolchain. Note: Unfortunately CMake will
                    always resolve any macros specified with '$' so to store a library in ADTF macro
                    syntax like $(SOME_DIR)/libray.ddl|so please use =(SOME_DIR)/libray.ddl|so as
                    workaround here, the '=' will be replaced by '$').

        --platform-dep-debug <sharedlibrary>
                    A list of shared libraries that need to be loaded before the adtfplugin is
                    loaded (for ADTF runtime, debug toolchain. Note: Unfortunately CMake will always
                    resolve any macros specified with '$' so to store a library in ADTF macro syntax
                    like $(SOME_DIR)/libray.ddl|so please use =(SOME_DIR)/libray.ddl|so as
                    workaround here, the '=' will be replaced by '$').

Where to go next?

Now you know a lot about setting up an ADTF Session but what about manipulating it without UI ? Let's have a look at ADTF Config Tool.