coder.ExternalDependency class

Package: coder

Interface to external code


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)
    c = 0;
    c = coder.ceval('adder', a, b);
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); 


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


expand all

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)
    c = a + b;

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
    methods (Static)
        function bName = getDescriptiveName(~)
            bName = 'AdderAPI';
        function tf = isSupportedContext(ctx)
            if  ctx.isMatlabHostTarget()
                tf = true;
                error('adder library not available for this target');
        function updateBuildInfo(buildInfo, ctx)
            [~, linkLibExt, execLibExt, ~] = ctx.getStdLibInfo();
            % Header files
            hdrFilePath = fullfile(pwd, 'codegen', 'dll', 'adder');
            % 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);
        %API for library function 'adder'
        function c = adder(a, b)
                % running in MATLAB, use built-in addition
                c = a + b;
                % running in generated code, call library function
                % 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.
                c = 0;
                c = coder.ceval('adder', a, b);
                % Call the terminate function after
                % calling adder for the last time.

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

function y = adder_main(x1, x2)
    y = AdderAPI.adder(x1, x2);

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', ''));

Run the MEX function and verify the result.


Introduced in R2013b

Was this topic helpful?