Setting up the build environment involves specifying the header files and libraries that you need to create an adaptor. For those familiar with their IDE environment, see the following sections for lists of these required include files and libraries. This section also describes how to create an environment variable that you can use to specify the MATLAB® installation folder. The header file and library paths use this environment variable. For detailed instructions on setting up your build environment in the Microsoft® Visual C++® development environment, see Creating an Adaptor Project Using Microsoft Visual C++.
Users of Microsoft Visual C++ should be aware that there are certain project parameters that they must set. See Configuring Other Project Parameters.
The following table lists the locations of the header files and libraries that you need to build an adaptor.
You must also specify the location of the header files and libraries required by your device. Read your device's SDK documentation to get this information.
Header File and Libraries
Adaptor kit header files
Image Acquisition Toolbox™ engine library
For information about defining environment variables, see Using Environment Variables.)
To learn how to specify header files in Microsoft Visual C++, see Specifying Header Files in Microsoft Visual C++.
To learn how to specify the libraries in Microsoft Visual C++, see Specifying Libraries and Library Paths.
To create an environment variable on your Windows® system that specifies your MATLAB installation folder, follow this procedure:
Open the System Properties dialog box in Windows Control Panel: Control Panel > System and Security > System.
In the System Control Panel, click the Advanced system settings option.
On the Advanced tab, click the Environment Variables button.
In the Environment Variables dialog box, in the User variables section, click New to create an environment variable.
In the New User Variable dialog box, assign the name
MATLAB to the variable and set the value of the
variable to your MATLAB installation folder path. Click OK.
Click OK in the Environment Variables dialog box, and then in the System Properties dialog box.
If Microsoft Visual C++ is running when you create this variable, you must restart it.
As the first step toward building an adaptor, open Microsoft Visual C++ and create a new project.
It is strongly recommended that you use a version of Microsoft Visual Studio®. For information about supported versions, see the MATLAB column in the table: https://www.mathworks.com/support/compilers.html.
Set up any required environment variables—see Using Environment Variables.
Start Microsoft Visual C++.
On the Start Page, click New Project.... Visual Studio opens the New Project dialog box. You can also open this dialog box from the File > New > Project menu.
In the New Project dialog box:
Expand Visual C++, under Installed Templates, if needed, and select Win32.
Select Win32 Project.
Enter the name you want to assign to the project in the Name field and specify where you want to locate the project in the Location field.
You can give your adaptor project any name. A convention used by the toolbox is to name adaptors as follows:
vendor_name + imaq
where you replace the character vector
vendor_name with something
appropriate to your project.
Click OK. Visual C++ opens the Win32 Application Wizard.
In the Win32 Application Wizard, click Application Settings.
On the Application Settings page, select DLL from the list of application types and select Empty project from the Additional options section. Click Finish to create the project.
After you create the project, close the Start Page. Visual C++ displays the project in its Solution Explorer, with separate folders for source files, header files, and other project resources.
After you have created an adaptor, you generally only need to recompile it for use with new major versions of the Image Acquisition Toolbox software. Adaptor writers should recompile when a major update is released, such as Image Acquisition Toolbox Version 4.0. If your adaptor works in one version but not in the new version of the toolbox, try recompiling and relinking to see if that resolves the issue.
Minor updates of the toolbox generally do not include changes to the adaptor kit, so adaptor writers generally will not need to recompile their adaptors.
When you create a project, Microsoft Visual C++ automatically creates a solution that contains your project. As a convenience, while you are developing your adaptor, you might want to add the adaptor kit project to your solution to make it easier to refer to adaptor kit files. Adding the adaptor kit project to your solution does not affect the compilation or linkage of your adaptor DLL.
To add the adaptor kit project to your solution, go to the File > Add > Existing Project menu. In the Add Existing Project dialog box, open the following project file,
matlabroot represents your MATLAB installation folder.
Before you can compile your adaptor, you must specify the locations of the header files required by the adaptor kit and by your device's SDK. For a list of the header files required by the adaptor kit, see Setting up a Build Environment on Windows Systems. The following section describes how to specify these header file locations in the Microsoft Visual C++ environment.
The examples in the following section use environment variables. For more information, see Using Environment Variables.
To specify the locations of the adaptor kit header files in Microsoft Visual C++, follow these instructions:
Open the Property Pages dialog box: Projects > Properties.
Expand Configuration Properties and select VC++ Directories.
Then select Include Directories and choose Edit from the menu associated with that row.
Add the locations of adaptor kit header files and the header files required by your device's SDK to the list of folders displayed, each on a separate line.
In this example,
$(MATLAB) dereferences the
MATLAB, which is set to the name
of your installation folder. (See Using Environment Variables for
After specifying the header file folders, click OK.
Before you can create your adaptor DLL, you must specify the libraries required by the adaptor kit and by your device's SDK. For a list of required libraries, see Setting up a Build Environment on Windows Systems. The following sections describes how to specify these libraries and library paths in Microsoft Visual C++.
Open the Property Pages dialog box (if it is not already open): Projects > Properties.
Change the Configuration setting (at the top of the dialog box) to All Configurations.
Expand Configuration Properties and then expand Linker. Select General and, on this page, select Additional Library Directories and click Edit from the menu associated with that row.
Add the locations of adaptor kit libraries and the libraries required by your device's SDK in the Additional Library Directories field. Use a semicolon to separate the folders.
This example adds this line to the field:
In the example,
$(MATLAB) dereferences the
MATLAB, which is set to the name
of your installation folder — see Using Environment Variables. You
<ARCH> with the name of an
architecture-specific folder, such as
To specify the library names, follow this procedure.
Open the Property Pages dialog box (if you do not already have it open): Projects > Properties.
In the Property Pages dialog box for your project, expand Configuration Properties and then expand Linker. Select the Input category and, on this page, select Additional Dependencies and click Edit.
Specify the names of the adaptor kit libraries and the names of the libraries required by your device's SDK. Use spaces to separate the names of the libraries. The following shows the adaptor kit libraries.
In addition to specifying the header files and libraries, an adaptor project requires these additional settings. If you do not set these parameters, your adaptor might encounter run-time problems.
Add an empty source file to your project. To set the values of these additional properties, your project must contain files. To create a source file, follow this procedure:
Select File > New > File.
In the New File dialog box, select Visual C++.
Select C++ File (.cpp) and then click Open.
Add the new source file to your project. From the File menu, select Move Source1.cpp into and select the name of your project. Accept the default file name for now; you can always change it later.
Open the Property Pages for your project by right-clicking on your project in the Solution Explorer and choosing Properties, or by selecting Properties from the Project menu.
In the Property Pages dialog box, open C/C++ and select Code Generation. On the Code Generation page, set the following values.
Enable C++ Exceptions
Yes with Extern C functions (/EHs)
Multi-threaded DLL (/MD)
Disable Security Check (/GS-)
In the Property Pages dialog box, under C/C++, select Language. On the Language page, set the Enable Run-time Type Information field to Yes (/GR).
In the Property Pages dialog box, under C/C++, select Command Line and specify the following compiler flag.
Click OK to close the Property Pages dialog box.