Using Dev-C++ and TDM-GCC 32/64-Bit Compilers

• NOTE: This is the configuration we use when developing and testing software.
  

1. Download and Install the SpinAPI

Follow these instructions to download and install the SpinAPI Universal (32 and 64-bit) Installer.

2. Download and Install Dev-C++

Navigate to the Dev-C++ website and download the latest version of Dev-C++ with the 32 and 64-bit TDM-GCC compilers (we currently use Dev-C++ 5.11 with the TDM-GCC 4.9.2 compilers). Follow the default installation instructions.

3. Configure the Dev-C++ Compiler Settings

Once SpinAPI and Dev-C++ have been successfully installed, configure the compilers to compile SpinAPI code by following these procedures:

64-bit:

• Navigate to the "Tools" menu and select "Compiler Options". In the "Compiler" window make sure that the "Compiler set to configure" is "TDM-GCC X.X.X 64-bit". (X.X.X is the version number, we can guarantee that versions 4.7.1 and 4.9.2 are working with SpinAPI)

• Under this menu check the box titled "Add the following commands when calling the compiler:" and add the command "-lspinapi64" to its field. (Note that this is a lower-case "L" not an upper-case "i").
• Switch to the "Directories" window. Add "C:\SpinCore\SpinAPI\lib" to the "Binaries" path and to the "Libraries" path. Add "C:\SpinCore\SpinAPI\include" to the "C Includes" path.

• This concludes configuration of the 64-bit compiler. Select "OK" at the bottom of the "Compiler Options" window to save these settings.

• Navigate to the "Tools" menu and select "Compiler Options". In the "Compiler" window make sure that the "Compiler set to configure" is "TDM-GCC X.X.X 32-bit". (X.X.X is the version number, we can guarantee that versions 4.7.1 and 4.9.2 are working with SpinAPI)

• Under this menu check the box titled "Add the following commands when calling the compiler:" and add the command "-lspinapi" to its field. (Note that this is a lower-case "L" not an upper-case "i").
• Switch to the "Directories" window. Add "C:\SpinCore\SpinAPI\lib32" to the "Binaries" path and to the "Libraries" path. Add "C:\SpinCore\SpinAPI\include" to the "C Includes" path.

• This concludes configuration of the 32-bit compiler. Select "OK" at the bottom of the "Compiler Options" window to save these settings.
  

Using the Microsoft Windows SDK Tools to Compile Against SpinCore Libraries

• NOTE: For 64-bit machines please follow the Dev C++ section in "Windows Compilation How-to" after installation.

• NOTE: When installing the package, you will be prompted to install MinGW. Please make sure to check the "runtime" check box within MinGW.

• NOTE: This is only one option for compiling SpinAPI programs. You may use any environment you are familiar with.

1  Introduction

Recently, SpinAPI’s compilation process has moved to the Microsoft Windows SDK C/C++ compiler. The reason behind this move away from GCC is that true 64bit support became necessary. In order to use GCC for 64bit compilation on Windows, plain MinGW is not enough; a Cygwin environment with a 64bit port of MinGW becomes necessary. Requiring the use of Cygwin not only complicates the compilation process for us, but for customers as well.

The current solution to this problem is to use the Microsoft Windows SDK C/C++ compiler. The SDK provides an easy way to setup the correct build environment for 64bit or 32bit, and also will use the correct C++ name mangling conventions for C++ libraries compiled with Visual Studio. Additionally, the compilation method is easily scriptable.

If you wish to use a programming environment like DEV-C++, see the section 'Compiling on Windows Programming Environments'

2  Install necessary Tools

The Microsoft Windows SDK (at least v7.1 is recommended) is required to compile C programs against the SpinAPI library, or other SpinCore API packages. The Windows SDK can be found for free on Microsoft’s MSDN website.

3  Setup Build Environment

The Microsoft Windows SDK comes with a tool called “setenv.cmd”. This is the tool that is used to setup the 64bit and 32bit build environments. It is found in the installation directory of the SDK under the “Bin” folder. If you would like to have this tool available at the command line without typing out the absolute path, you will need to add the “Bin” directory to the system’s path variable. This can be done as follows (on Windows 7):

1. Click on the “Start” menu.
2. Right click on “Computer”
3. Click “Properties”
4. Click “Advanced System Settings”
5. Click “Environment Variables”
6. Under “System Variables” click on “Path”, then click the “Edit...” button below.
7. Add a semicolon at the end of the “Variable value” field, and then enter the full path to where “setenv.cmd” resides, for example (without quotes): “C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin”
8. Press “OK” 3 times.

Now you will be able to open a terminal and have “setenv.cmd” available in the system path.

3.1  Usage of “setenv.cmd”

To set up a 64bit build environment:

To set up a 32bit build environment:

4  Compiling

Once “setenv.cmd” has been called, the proper build environment has been setup and the compilers are available. “cl.exe” is the C/C++ compiler used. Some important parameters are listed below.

• Adding Include Directories:
  cl.exe foo.c /I YourPath
• Linking against a library requires that you add a full or relative path to the .lib file.
  cl.exe foo.c \path\to\bar.lib

Full example of 64bit compilation (with SpinAPI 64bit):

Full example of 32bit compilation (with SpinAPI 32bit):

Full example of 32bit compilation (with SpinAPI 64bit):

Compiling on Windows Programming Environments

   The SpinAPI control library is a standard windows .dll which can be accessed from a wide variety of programming environments, such as C/C++ programs, LabView, etc.

Accessing SpinAPI From a C/C++ Program:

   This section describes the basic steps needed to get your C/C++ program to work with SpinAPI.  Virtually any C/C++ compiler/programming environment is compatible, feel free to use your favorite.  If you do not currently have a C/C++ compiler, there are several high quality compilers available for free download on the internet, see below for some recommendations.

  The following files are necessary to be able to control your board using this approach:

1. .c/.cpp file: This is the program itself. Several example C programs are provided for each of our different products.
   


2. spinapi.h, registers.h: The SpinAPI header files. These contain the function declarations and definitions which are needed to access the SpinAPI functions. spinapi.h should be #included in all files which use the SpinAPI functions. (#include "spinapi.h").  Additionally, you should #define the correct directive for your board before including spinapi.h .  For example, with a PulseBlaster24 you would do "# define PB24"
1. The supported defines are: PB24, PBDDS, PBESR, and PBESRPRO.   If your board does not correspond to one of these, then you do not need one.
   


3. Import library: This library must be linked with your program so it will know to look inside the spinapi.dll file to find the API functions. Choose whichever is appropriate for the compiler you are using.  These libraries can be located in the "C:\SpinCore\SpinAPI\lib" (formerly "C:\SpinCore\SpinAPI\dll") directory.
   
• spinapi.lib | spinapi64.lib: Microsoft compilers
  
• libspinapi.a: GCC based compilers (such as MinGW)
  
  
4. spinapi.dll | spinapi64.dll: The control library itself. Windows must be able to find this file when you run your program, so it needs to be placed in the same directory as the executable program, or in one of the Windows library search directories.
   

The most straightforward way to compile a program using SpinAPI is to create a new, empty directory and copy each of the above required files into it. Look in the inc/ directory to find spinapi.h and register.h, and the lib/ directory to find the dynamic library and the import library. An example C program can be found the the appropriate product subdirectory of the examples/ directory. Then open the C file, configure your compiler to link with the import library, and start the compile. It is recommended that you compile one of the unchanged example programs first, to ensure your compiler is set up correctly. Once the example is compiled correctly, you can move on to creating custom programs.

Below are detailed instructions for specific compilers on how to configure them to use SpinAPI. The procedure for other compilers should be similar.

Microsoft Visual C++ 2010:

1. Create a new Win32 Console Application (check "Empty Project").
   
2. In the properties for your project, navigate to the "VC++ Directories" page
1. Add "C:\SpinCore\SpinAPI\inc" to your "Include Directories" property
2. Add "C:\SpinCore\SpinAPI\lib" to your "Library Directories" property (or "C:\SpinCore\SpinAPI\lib32 if you are using a 64bit installation of SpinAPI and your target is 32bit)
   
3. Navigate to Linker>Input
1. Add "spinapi.lib" to the "Additional Dependencies" property (if it is a 32bit target, otherwise if you target is 64bit: "spinapi64.lib")
4. Right-click on your "Source Files" folder in the Solution Explorer and go to "Add>Existing Item..." and browse to the source file you wish to compile.
5. Now right-click on your project in the Solution Explorer and select "Build" to compile the code.
   

Microsoft Visual Studio 6:

1. Open the C file.
   
   
2. Select "Build>Compile zzz.c" from the menu. (zzz.c will be the name of the C file you opened)
   
   
3. You will be asked if you wish to create a new workspace. Answer yes.
   
   
4. You must tell the compiler to use the import library. Choose "Product>Settings..." from the menu. Click on the "Link" tab. In the "Object/Library modules:" box, add spinapi.lib in addition to the libraries already listed, and click "Ok"
   
   
5. Everything is now configured correctly. To build the executable, simply choose "Build>Build zzz.exe" from the menu, and the program will be created and placed in the Debug subdirectory.

Dev-C++ (Instructions are for 32bit executable):

1. Open the C file.
   
   
2. Choose "Tools>Compiler Options".
   
   
3. Under the "Compiler" tab, check the "Add these commands to the linker command line" box, and enter "-lspinapi" in the text box below.  For our MRI Spin-API package you will need to include "-lmrispinapi"
   
   
4. Under the "Directories" tab, choose the "Binaries" tab and add the directory where the "libspinapi.a" file is located. (Click the icon with a picture of a folder on it, choose the directory in the dialog box that pops up, and click the "Add" button). Under a default installation of SpinAPI, this directory would be "C:\SpinCore\SpinAPI\lib" for 32-bit systems and "C:\SpinCore\SpinAPI\lib32" for 64-bit systems. For the MRI SpinAPI packages you will need to add "C:\SpinCore\MRI SpinAPI\lib".
   

5. Repeat Step 4, but with the "Libraries" tab, which is also under "Directories."
   
   
6. Under the "Directories" tab click the "C Includes" tab.  For SpinAPI you need to add the SpinAPI include directory, which is by default located at "C:\SpinCore\SpinAPI\inc".  For the MRI SpinAPI packages you will need to add "C:\SpinCore\MRI SpinAPI\src".

7. Everything is now configured. Choose "Execute>Compile" from the menu to compile the program.
1. NOTE:  If you have MinGW installed separately, you may need to rename the installation directory.  By default, it is "C:\MinGW".  Renaming to something like "C:\MinGW_Vanilla" will suffice.  If you do not do this, Dev-C++ may fail to compile executables.
   

Code::Blocks (Instructions are for 32bit executable):

1.  Open the C file.

2. Choose "Settings>Compiler..."

3. Under the "Linker Settings" tab add the "libspinapi.a" file. Under a default installation of SpinAPI, the directory containing this file would be "C:\SpinCore\SpinAPI\lib" for 32-bit systems and "C:\SpinCore\SpinAPI64\lib32" for 64-bit systems. For the MRI SpinAPI package you will need to add the "libmrispinapi.a" file. The default location for this file is "C:\SpinCore\MRI SpinAPI\lib."

4. Under the "Search directories" tab, choose the  "Compiler" tab and add the directory "C:\SpinCore\SpinAPI\inc" for 32-bit and 64-bit systems (Note: this is the default directories). For the MRI SpinAPI packages you will need to add "C:\SpinCore\MRI SpinAPI\src".

5. Under the "Search Directories" tab, choose the "Linker" tab and add the directory "C:\SpinCore\SpinAPI\lib" for 32-bit, and "C:\SpinCore\SpinAPI\lib32" for 64bit systems.  For the MRI SpinAPI packages you will need to add "C:\SpinCore\MRI SpinAPI\lib".

6. Everything is now configured. Choose "Build>Compile Current File" from the menu to compile the program.

Free C/C++ Compilers:

Accessing SpinAPI From Other Programming Environments:

    Virtually all programming environments provide some mechanism for accessing an API provided by a Windows .dll. Please consult the help files of your environment if you are unsure of how to do this.

General Tips

• We highly recommend you check the result of the pb_get_version() function at the beginning of each program. This way, if you upgrade to a newer version of SpinAPI, you can check to make sure your program is not accidentally still using the older version of the library.


• Checking the return value of all SpinAPI functions is highly recommended. This way you will be able to detect common errors (such as entering too short a time for an instruction length, etc.)
  


• If you encounter difficulties controlling your board with SpinAPI, you can enable debugging features by calling pb_set_debug(1) on the first line of your program. This will create file called log_boardXXX.txt when you run your program, which can then be emailed to us along with a description of the problem to help us solve your problem as quickly as possible.