Main Content

Setting Up a Build Environment on Windows Systems

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++.

Note

Users of Microsoft Visual C++ should be aware that there are certain project parameters that they must set. See Configuring Other Project Parameters.

Required Header Files and Libraries

The following table lists the locations of the header files and libraries that you need to build an adaptor.

Note

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

Location

Adaptor kit header files

$(MATLAB)\toolbox\imaq\imaqadaptors\kit\includea

Image Acquisition Toolbox™ engine library

$(MATLAB)\toolbox\imaq\imaqadaptors\kit\lib\<ARCH>\release\imaqmex.lib

a  MATLAB is an environment variable that contains the name of your MATLAB installation folder.

Using Environment Variables

To create an environment variable on your Windows® system that specifies your MATLAB installation folder, follow this procedure:

  1. Open the System Properties dialog box in Windows Control Panel: Control Panel > System and Security > System.

  2. In the System Control Panel, click the Advanced system settings option.

  3. On the Advanced tab, click the Environment Variables button.

  4. In the Environment Variables dialog box, in the User variables section, click New to create an environment variable.

  5. 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.

  6. Click OK in the Environment Variables dialog box, and then in the System Properties dialog box.

Note

If Microsoft Visual C++ is running when you create this variable, you must restart it.

Creating an Adaptor Project Using Microsoft Visual C++

As the first step toward building an adaptor, open Microsoft Visual C++ and create a new project.

Note

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.

  1. Set up any required environment variables—see Using Environment Variables.

  2. Start Microsoft Visual C++.

  3. 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.

  4. 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.

  5. In the Win32 Application Wizard, click Application Settings.

  6. 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.

Recompiling with New Versions of the Image Acquisition Toolbox Software

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.

Adding the Adaptor Kit Project to Your Solution

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\toolbox\imaq\imaqadaptors\kit\imaqadaptorkit.vcxproj

where matlabroot represents your MATLAB installation folder.

Specifying Header File Locations

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.

Note

The examples in the following section use environment variables. For more information, see Using Environment Variables.

Specifying Header Files in Microsoft Visual C++

To specify the locations of the adaptor kit header files in Microsoft Visual C++, follow these instructions:

  1. Open the Property Pages dialog box: Projects > Properties.

  2. Expand Configuration Properties and select VC++ Directories.

    Then select Include Directories and choose Edit from the menu associated with that row.

  3. 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.

    $(MATLAB)\toolbox\imaq\imaqadaptors\kit\include

    In this example, $(MATLAB) dereferences the environment variable MATLAB, which is set to the name of your installation folder. (See Using Environment Variables for more information.)

  4. After specifying the header file folders, click OK.

Specifying Libraries and Library Paths

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++.

Specifying Library Locations in Microsoft Visual C++

  1. Open the Property Pages dialog box (if it is not already open): Projects > Properties.

  2. Change the Configuration setting (at the top of the dialog box) to All Configurations.

  3. 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.

  4. 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:

    $(MATLAB)\toolbox\imaq\imaqadaptors\kit\lib\<ARCH>\release

    In the example,$(MATLAB) dereferences the environment variable MATLAB, which is set to the name of your installation folder — see Using Environment Variables. You must replace <ARCH> with the name of an architecture-specific folder, such as win64.

Specifying Library Names in Microsoft Visual C++

To specify the library names, follow this procedure.

  1. Open the Property Pages dialog box (if you do not already have it open): Projects > Properties.

  2. 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.

  3. 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. 

    imaqmex.lib

  4. Click OK.

Configuring Other Project Parameters

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.

  1. 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:

    1. Select File > New > File.

    2. In the New File dialog box, select Visual C++.

    3. Select C++ File (.cpp) and then click Open.

    4. 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.

  2. 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.

  3. In the Property Pages dialog box, open C/C++ and select Code Generation. On the Code Generation page, set the following values.

    Field

    Setting

    Enable C++ Exceptions

    Yes with Extern C functions (/EHs)

    Runtime library

    Multi-threaded DLL (/MD)

    Security Check

    Disable Security Check (/GS-)

  4. 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).

  5. In the Property Pages dialog box, under C/C++, select Command Line and specify the following compiler flag.

    /EHs

    Click OK to close the Property Pages dialog box.