.TH "doc_tutorials_compilation-variants_md" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
doc_tutorials_compilation-variants_md \- Compilation Variants 
To create different variants of the same feature, but avoid code duplications within plugins, you have multiple options:
.IP "\(bu" 2
Define a needs clause in a \fBcontract\fP and reuse another plugin as it is\&.
.IP "\(bu" 2
Have common code together in a helper library (or core library), see the CMake function add_plugin_helper for creating such a library\&.
.IP "\(bu" 2
Have configuration for plugins (See \fCelektraPluginGetConfig()\fP and dynamically switch with if according to the configuration\&.
.IP "\(bu" 2
Or use compilation variants to compile the plugin code multiple times with different COMPILE_DEFINITIONS (that are Macro definitions)\&.
.PP
.PP
The compilation variants are the hardest to use, so you should reconsider if another technique is more appropriate\&.
.PP
The advantage of compilation variants are:
.IP "\(bu" 2
No runtime overhead
.IP "\(bu" 2
Can be used during Bootstrapping (when no configuration is available)
.PP
.PP
To use compilation variants, add your plugin in the CMake Cache Variable PLUGINS multiple times\&. There has to be the base variant, called in the same name as the directory\&. Then there can be an arbitrary number of variants that additional have a name appended with underscore, e\&.g\&.: 
.PP
.nf
    myplugin;myplugin_varianta;myplugin_variantb

.fi
.PP
.PP
In the CMakeLists\&.txt of your plugin, you need a loop over all PLUGINS and create a plugin per compilation variant: 
.PP
.nf
    foreach (plugin ${PLUGINS})
            if(${plugin} MATCHES "myplugin_.*")
                    # somehow process the variant names and include
                    # or change sources and compile definitions
                    # based on that.
                    add_plugin(${plugin}
                    SOURCES      <your sources here..>
                    COMPILE_DEFINITIONS   <definitions here..>

.fi
.PP
.PP
Now every public function of the plugin conflicts with itself\&. To avoid that, you can use:
.IP "\(bu" 2
static functions, but they are only visible within one file
.IP "\(bu" 2
use helper libraries using add_plugin_helper to share code between compilation variants
.IP "\(bu" 2
Get a unique name for every variant using the macro \fC\fBELEKTRA_PLUGIN_FUNCTION(myplugin, open)\fP\fP where myplugin is the name of the plugin and the second argument is how the function should be called\&.
.IP "\(bu" 2
Including a readme for every variant (with #ifdef for different text) using the macro \fC#include \fBELEKTRA_README(myplugin)\fP\fP
.PP
.PP
As a summary, you can have many plugins build out of the same source\&. Using pluginname_variantnames many plugins will be compiled, each with other SOURCES or COMPILE_DEFINITIONS\&. If you, e\&.g\&. just set the variants name as macro you can use 
.PP
.nf
    #ifdef varianta
    #endif

.fi
.PP
.PP
within the code and can have two plugins: one (called myplugin_varianta) compiled included the \fC#ifdef\fP the other (base variant called myplugin) without\&.
.PP
Currently compilation variants is used in \fCthe resolver plugin\fP\&.