coder.ExternalDependency class

Package: coder
Superclasses:

Interface to external code

expand all in page

Description

coder.ExternalDependency is an abstract class for developing an interface between external code and MATLAB® code intended for code generation. You can 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.

To define a class derived from coder.ExternalDependency, create a subclass. For example:

classdef myClass < coder.ExternalDependency

You must define all of the methods listed in Methods. These methods are static and are not compiled. The code generator invokes these methods in MATLAB after code generation is complete to configure the build for the generated code. The RTW.BuildInfo and coder.BuildConfig objects that describe the build information and build context are automatically created during the build process. The updateBuildInfo method provides access to these objects. For more information on build information customization, see Build Process Customization.

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.

Methods

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

Examples

collapse 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)
%#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(buildContext)
            if  buildContext.isMatlabHostTarget()
                tf = true;
            else
                error('adder library not available for this target');
            end
        end
        
        function updateBuildInfo(buildInfo, buildContext)
            % Get file extensions for the current platform
            [~, linkLibExt, execLibExt, ~] = buildContext.getStdLibInfo();
            
            % Add file paths
            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 for packaging
            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
                % Add the required include statements to the generated function code
                coder.cinclude('adder.h');
                coder.cinclude('adder_initialize.h');
                coder.cinclude('adder_terminate.h');
                c = 0;
                
                % Because MATLAB Coder generated adder, use the
                % housekeeping functions before and after calling
                % adder with coder.ceval.

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

| | |

Topics

Introduced in R2013b

MATLAB Coder Documentation

Support