Encapsulate Interface to an External C Library

This example shows how to encapsulate the interface to an external C dynamic linked library using coder.ExternalDependency.

Write a function adder that returns the sum of its inputs.

function c = adder(a,b)
    %#codegen
    c = a + b;
end

Generate a library that contains adder.

codegen('adder','-args', {-2,5}, '-config:dll', '-report');

Write the class definition file AdderAPI.m to encapsulate the library interface.

%================================================================
% This class abstracts the API to an external Adder library.
% It implements static methods for updating the build information
% at compile time and build time.
%================================================================

classdef AdderAPI < coder.ExternalDependency
    %#codegen
    
    methods (Static)
        
        function bName = getDescriptiveName(~)
            bName = 'AdderAPI';
        end
        
        function tf = isSupportedContext(ctx)
            if  ctx.isMatlabHostTarget()
                tf = true;
            else
                error('adder library not available for this target');
            end
        end
        
        function updateBuildInfo(buildInfo, ctx)
            [~, linkLibExt, execLibExt, ~] = ctx.getStdLibInfo();
            
            % Header files
            hdrFilePath = fullfile(pwd, 'codegen', 'dll', 'adder');
            buildInfo.addIncludePaths(hdrFilePath);
            
            % Link files
            linkFiles = strcat('adder', linkLibExt);
            linkPath = hdrFilePath;
            linkPriority = '';
            linkPrecompiled = true;
            linkLinkOnly = true;
            group = '';
            buildInfo.addLinkObjects(linkFiles, linkPath, ...
                linkPriority, linkPrecompiled, linkLinkOnly, group);
            
            % Non-build files
            nbFiles = 'adder';
            nbFiles = strcat(nbFiles, execLibExt);
            buildInfo.addNonBuildFiles(nbFiles,'','');
        end
        
        %API for library function 'adder'
        function c = adder(a, b)
            if coder.target('MATLAB')
                % running in MATLAB, use built-in addition
                c = a + b;
            else
                % running in generated code, call library function
                coder.cinclude('adder.h');
                
                % Because MATLAB Coder generated adder, use the
                % housekeeping functions before and after calling
                % adder with coder.ceval.
                % Call initialize function before calling adder for the
                % first time.
                
                coder.ceval('adder_initialize');
                c = 0;
                c = coder.ceval('adder', a, b);
                
                
                % Call the terminate function after
                % calling adder for the last time.
                
                coder.ceval('adder_terminate');
            end
        end
    end
end

Write a function adder_main that calls the external library function adder.

function y = adder_main(x1, x2)
%#codegen
    y = AdderAPI.adder(x1, x2);
end

Generate a MEX function for adder_main. The MEX Function exercises the coder.ExternalDependency methods.

codegen('adder_main', '-args', {7,9}, '-report')

Copy the library to the current folder using the file extension for your platform.

For Windows®, use:

copyfile(fullfile(pwd, 'codegen', 'dll', 'adder', 'adder.dll'));

For Linux®, use:

copyfile(fullfile(pwd, 'codegen', 'dll', 'adder', 'adder.so'));

Run the MEX function and verify the result.

adder_main_mex(2,3)

See Also

| |

More About

Was this topic helpful?