Package Generated Code as Shared Libraries - MATLAB & Simulink (original) (raw)

If you have an Embedded Coder® license, you can package generated source code from a model component for easy distribution and shared use by building the code as a shared library—Windows® dynamic link library (.dll), UNIX® shared object (.so), or Macintosh OS X dynamic library (.dylib). You or others can integrate the shared library into an application that runs on a Windows, UNIX, or Macintosh OS X development computer. The generated .dll,.so, or .dylib file is shareable among different applications and upgradeable without having to recompile the applications that use it.

About Generated Shared Libraries

You build a shared library by configuring the code generator to use the system target file ert_shrlib.tlc. Code generation for that system target file exports:

To view a list of symbols contained in a generated shared library:

To generate and use a shared library:

  1. Generate a shared library version of your model code
  2. Create application code to load and use your shared library file

Generate Shared Library Version of Model Code

To generate a shared library version of your model code:

  1. Open your model and configure it to use the ert_shrlib.tlc system target file.

    Selecting the ert_shrlib.tlc system target file causes the build process to generate a shared library version of your model code into your current working folder. The selection does not change the code that the code generator produces for your model.
  2. Build the model.
  3. After the build completes, examine the generated code in the model subfolder and examine the .dll, .so, or .dylib file in your current folder.

Create Application Code to Use Shared Library

To illustrate how application code can load a shared library file and access its functions and data, MathWorks provides the model SharedLibraryCode. To inspect the model, run this command from the MATLAB® command window:

openExample('SharedLibraryCode');

In the model, click the blue button to run a script. The script:

  1. Builds a shared library file from the model (for example,SharedLibraryCode_win64.dll on 64-bit Windows).
  2. Compiles and links an example application,SharedLibraryCode_app, that loads and uses the shared library file.
  3. Executes the example application.

Tip

Explicit linking is preferred for portability. However, on Windows systems, the ert_shrlib system target file generates and retains the .lib file to support implicit linking.

To use implicit linking, the generated header file needs a small modification for you to use it with the generated C file. For example, if you are using Visual C++®, declare __declspec(dllimport) in front of data to be imported implicitly from the shared library file.

The model uses the following example application files:

File Description
SharedLibraryCode_app.h Example application header file
SharedLibraryCode_app.c Example application that loads and uses the shared library file generated for the model
run_SharedLibraryCode_app.m Script to compile, link, and execute the example application

You can view each of these files by clicking white buttons in the model window. Additionally, running the script places the relevant source and generated code files in your current folder. The files can be used as templates for writing application code for your own ERT shared library files.

The following sections present key excerpts of the example application files.

Example Application Header File

The example application header file SharedLibraryCode_app.h contains type declarations for the model's external input and output.

#ifndef APP_MAIN_HEADER #define APP_MAIN_HEADER

typedef struct { int32_T Input; } ExternalInputs_SharedLibraryCode;

typedef struct { int32_T Output; } ExternalOutputs_SharedLibraryCode;

#endif /APP_MAIN_HEADER/

Example Application C Code

The example application SharedLibraryCode_app.c includes the following code for dynamically loading the shared library file. Notice that, depending on platform, the code invokes Windows or UNIX library commands.

#if (defined(_WIN32)||defined(_WIN64)) /* WINDOWS */ #include <windows.h> #define GETSYMBOLADDR GetProcAddress #define LOADLIB LoadLibrary #define CLOSELIB FreeLibrary

#else /* UNIX */ #include <dlfcn.h> #define GETSYMBOLADDR dlsym #define LOADLIB dlopen #define CLOSELIB dlclose

#endif

int main() { void* handleLib; ... #if defined(_WIN64) handleLib = LOADLIB("./SharedLibraryCode_win64.dll"); #else #if defined(_WIN32) handleLib = LOADLIB("./SharedLibraryCode_win32.dll"); #else /* UNIX */ handleLib = LOADLIB("./SharedLibraryCode.so", RTLD_LAZY); #endif #endif ... return(CLOSELIB(handleLib)); }

The following code excerpt shows how the C application accesses the model's exported data and functions. Notice the hooks for adding user-defined initialization, step, and termination code.

int32_T i;

... void (*mdl_initialize)(boolean_T); void (*mdl_step)(void); void (*mdl_terminate)(void);

ExternalInputs_SharedLibraryCode (*mdl_Uptr);
ExternalOutputs_SharedLibraryCode (*mdl_Yptr);
    
uint8_T (*sum_outptr);

... #if (defined(BORLANDCDLL)) /* Exported symbols contain leading underscores when DLL is linked with BORLANDC / mdl_initialize =(void()(boolean_T))GETSYMBOLADDR(handleLib , "_SharedLibraryCode_initialize"); mdl_step =(void()(void))GETSYMBOLADDR(handleLib , "_SharedLibraryCode_step"); mdl_terminate =(void()(void))GETSYMBOLADDR(handleLib , "_SharedLibraryCode_terminate"); mdl_Uptr =(ExternalInputs_SharedLibraryCode*)GETSYMBOLADDR(handleLib , "_SharedLibraryCode_U"); mdl_Yptr =(ExternalOutputs_SharedLibraryCode*)GETSYMBOLADDR(handleLib , "_SharedLibraryCode_Y"); sum_outptr =(uint8_T*)GETSYMBOLADDR(handleLib , "_sum_out"); #else
mdl_initialize =(void()(boolean_T))GETSYMBOLADDR(handleLib , "SharedLibraryCode_initialize"); mdl_step =(void()(void))GETSYMBOLADDR(handleLib , "SharedLibraryCode_step"); mdl_terminate =(void()(void))GETSYMBOLADDR(handleLib , "SharedLibraryCode_terminate"); mdl_Uptr =(ExternalInputs_SharedLibraryCode)GETSYMBOLADDR(handleLib , "SharedLibraryCode_U"); mdl_Yptr =(ExternalOutputs_SharedLibraryCode*)GETSYMBOLADDR(handleLib , "SharedLibraryCode_Y"); sum_outptr =(uint8_T*)GETSYMBOLADDR(handleLib , "sum_out"); #endif

if ((mdl_initialize && mdl_step && mdl_terminate && mdl_Uptr && mdl_Yptr && 
     sum_outptr)) {
    /* === user application initialization function === */
    mdl_initialize(1); 
    /* insert other user defined application initialization code here */
    
    /* === user application step function === */
    for(i=0;i<=12;i++){ 
        mdl_Uptr->Input = i;
        mdl_step(); 
        printf("Counter out(sum_out): %d\tAmplifier in(Input): %d\tout(Output): %d\n",
               *sum_outptr, i, mdl_Yptr->Output); 
        /* insert other user defined application step function code here */
    }
    
    /* === user application terminate function === */
    mdl_terminate();
    /* insert other user defined application termination code here */
}
else {
    printf("Cannot locate the specified reference(s) in the shared library.\n");
    return(-1);
}

Example Application Script

The application script run_SharedLibraryCode_app loads and rebuilds the model, and then compiles, links, and executes the model's shared library target file. You can view the script source file by openingSharedLibraryCode and clicking a white button to view source code. The script constructs platform-dependent command character vectors for compilation, linking, and execution that may apply to your development environment. To run the script, click the blue button.

Note

It is invalid to invoke the terminate function twice in a row. The terminate function clears pointers and sets them to NULL. Invoking the function a second time dereferences null pointers and results in a program failure.

Shared Library Limitations

The following limitations apply to building shared libraries:

See Also

Topics