coder.ExternalDependency class

Package: coder

Interface to external code

Description

coder.ExternalDependency is an abstract class for encapsulating the interface between external code and MATLAB® code intended for code generation. You define classes that derive from coder.ExternalDependency to encapsulate the interface to external libraries, object files, and C/C++ source code. This encapsulation allows you to separate the details of the interface from your MATLAB code. The derived class contains information about external file locations, build information, and the programming interface to external functions.

To define a class, myclass, make the following line the first line of your class definition file:

classdef myclass < coder.ExternalDependency

You must define all of the methods listed in Methods. These methods are static and are not compiled. When you write these methods, use coder.BuildConfig methods to access build information.

You also define methods that call the external code. These methods are compiled. For each external function that you want to call, write a method to define the programming interface to the function. In the method, use coder.ceval to call the external function. Suppose you define the following method for a class named AdderAPI:

function c = adder(a, b)
    coder.cinclude('adder.h');
    c = 0;
    c = coder.ceval('adder', a, b);
end      

This method defines the interface to a function adder which has two inputs a and b. In your MATLAB code, call adder this way:

y = AdderAPI.adder(x1, x2); 

Methods

getDescriptiveNameReturn descriptive name for external dependency
isSupportedContextDetermine if build context supports external dependency
updateBuildInfoUpdate build information

Examples

expand all

Encapsulate the interface to an external C dynamic linked 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)
Was this topic helpful?