pylon Deployment Guide#

This topic describes how to deploy pylon software via copy deployment or the runtime redistributable packages on Windows operating systems.

Overview#

To deploy pylon software and camera drivers, two options are available:

• Copy deployment: Deploy the necessary files simply by copying them. This is the recommended option if you want to deploy pylon as part of your own application. Camera drivers must be installed separately using .msi installers. For more information, see Copy Deployment.

• pylon runtime redistributable package (also known as "runtime installer"): Deploy the necessary files and drivers using an installation program. This is the recommended option if you want to perform an unattended or silent installation of the pylon software. For more information, see Runtime Redistributable Package.

  Info

  You can also use the pylon installer (Basler_pylon_x.x.x.xxxxx.exe) to deploy pylon software and drivers in a silent installation. The advantage of using the installer is that you can install CLI/GUI tools, SDK samples, and documentation at the same time.

For the advantages and disadvantages of each option, see the following table.

Runtime Redistributable Package#

The pylon runtime redistributable package allows you to deploy the pylon files and drivers by running an installation program.

This is the recommended option if you want to perform an unattended or silent installation of the pylon software.

You can choose whether to install support for all camera interfaces (GigE, USB 3.0, CXP 2.0, Camera Link) or whether to pick individual interfaces as required. If you want to install support only for selected camera interfaces, see "Configuring and Customizing the Installation".

Configuring and Customizing the Installation#

The runtime redistributable package (.exe file) accepts command line switches to customize and configure the installation.

The following options, among others, are available:

• Running a "silent installation" without displaying any messages or windows during installation
• Installing only specific components (e.g., only the C++ runtime files, the USB runtime files, the USB camera driver, and the pylon Viewer)
• Uninstalling specific components

To access information about the available switches, launch the runtime redistributable package (.exe file) from the command prompt with the /help or /? switch.

Example:

"Basler pylon Runtime 7.x.x.xxxx.exe" /help

A help window will appear, providing information about the available command line switches.

Copy Deployment#

Using Copy Deployment#

Copy deployment, also known as XCopy deployment, allows you to deploy the necessary files simply by copying them to the target computer. Because there is no automatic installation routine, you must provide and maintain your own installation routine to automate the process.

This is the recommended option if you want to deploy pylon as part of your own application.

To deploy pylon via copy deployment:

1. Set up your installation routine to do the following:
   • Copy the required pylon files to the target computer. For a list of the pylon files, see pylon Files.
   • Execute the Visual C++ Redistributable Package installer. For more information, see Visual C++ Runtime Files.
   • Execute the appropriate camera driver installer (.msi file). For a list of pylon camera driver installers, see pylon Camera Driver Packages.
2. Make sure your application's executable file(s) can find the pylon DLLs on the target computer. For more information, see Locating the pylon DLLs.

These steps can be carried out in any order.

Choosing Files for Copy Deployment#

pylon Files#

To deploy pylon using copy deployment, a set of .dll and .zip files must be copied to the target computer. The file names and the number of files vary depending on the camera interface(s) that you want your application to support (GigE Vision, USB 3.0 Vision, Camera Link, CoaXPress 2.0, or multiple interfaces).

The files required for each interface are shown in the following table. All files are available in 32-bit and 64-bit versions, with identical file names. If your application is available in both 32-bit and 64-bit versions, you must provide each file twice.

To obtain the files, install the pylon Software Suite on your computer. During installation, select the Developer profile and choose the desired interface(s).

After the installation, you can find the files in the \Runtime\x64 and \Runtime\Win32 subdirectories of the pylon installation directory, unless otherwise noted. For details, see the "Notes" column in the following table.

x = Required file, o = Optional file

Visual C++ Runtime Files#

The pylon DLLs depend on the following Visual C++ runtime files:

These files must always be deployed together with the pylon DLLs. The files are available in 32-bit and 64-bit versions, with identical file names. If your application is available in both 32-bit and 64-bit versions, you must provide each file twice.

To do so, two options are available:

• Run the Visual C++ Redistributable Package for Visual Studio 2015, 2017, or 2019, provided by Microsoft. This is the recommended method. The installer will automatically copy the required files to the respective Windows system directory (%windir%\System32 or %windir%\SysWOW64).
  You can download the package from the Microsoft website:
  2015 version: https://www.microsoft.com/en-us/download/details.aspx?id=48145
  2017/2019 version: https://visualstudio.microsoft.com/vs/older-downloads/.
  Expand the Redistributables and Build Tools section and select the desired operating system version of the redistributable package.

• Manually copy the files listed in the table above to the same target directory as the pylon DLLs. You can use this deployment method to enable installation by users who don't have administrator rights, or for applications that can be run from a network share.

For more information, see the "Choosing a Deployment Method" topic on the Microsoft Docs websites:

https://docs.microsoft.com/en-us/cpp/windows/choosing-a-deployment-method?view=vs-2019

https://docs.microsoft.com/en-us/cpp/windows/universal-crt-deployment?view=vs-2019

pylon Camera Driver Packages#

Camera drivers must be installed separately using .msi packages.

To install the camera drivers on the target computer, set up your installation routine to execute the corresponding .msi file.

The installer will automatically install the driver without displaying any messages or windows during its progress ("silent installation").

The .msi packages for each interface are shown in the following table. If you want your application to support multiple camera interfaces, execute the respective .msi files one after the other.

To obtain the files, install the pylon Software Suite on your computer. During installation, select the "Developer" profile and choose the desired interface(s).

After the installation, you can find the files in the \Development\Redist\Drivers subdirectory of the pylon installation directory.

Locating the pylon DLLs#

To deploy pylon via copy deployment, you must make sure your application's executable file(s) can find the required pylon DLLs on the target computer. Otherwise, your application won't start or issue an error message.

Enabling your application to find the pylon DLLs can be done in several ways:

• Place the pylon DLLs in the application's working directory. For more information, see Method 1: Placing the pylon DLLs in the Application's Working Directory.
• Register the application path in the Windows registry. For more information, see Method 2: Registering the Application Path in the Windows Registry.
• Run the application using a batch file. For more information, see Method 3: Running the Application Using a Batch File.
• Use the SetDllDirectory function in the source code of your application. For more information, see Method 4: Using SetDllDirectory in the Source Code.
• Create assembly manifests and embed them in your application project. For more information, see Method 5: Creating and Embedding Assembly Manifests.

The following flowchart can help you choose the right method.

Method 1: Placing the pylon DLLs in the Application's Working Directory#

The easiest copy deployment method is to set up your installation routine to copy the required pylon DLLs to the same target directory as your application's executable files. This enables your application to find the pylon DLLs automatically.

Because this is also the most reliable method, you should always consider this option first.

Method 2: Registering the Application Path in the Windows Registry#

To point your application to the pylon DLLs, you can register the application path ("AppPath") in the Windows registry.

This is the recommended method if your application's executable file(s) and the dependent pylon DLLs can't be placed in the same directory.

To deploy the pylon DLLs by registering the application path:

1. Set up your installation routine to copy the required pylon DLLs. If your application is available in 32-bit and 64-bit versions, the 32-bit pylon DLLs must be copied to one target directory and the 64-bit pylon DLLs to another.
2. Set up your installation routine to add or change the following registry entries:
   1. Add the subkey HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\file.exe where file.exe must be replaced by the name of your application's executable file, e.g., Grab.exe.
   2. Set the value of the subkey's (Default) entry to the path of the application's executable file, e.g., C:\Program Files\Grab\Grab.exe.
   3. Add a Path entry and set its value to the path of the directory containing the pylon DLLs, e.g., C:\Program Files\Grab\dll\pylon32\.
      In the Windows Registry Editor, the result should look like this (sample values):
      
3. If your application is available in 32-bit and 64-bit versions, repeat step 2 for the application's 64-bit executable file and the directory containing the 64-bit pylon DLLs. For example, add a second subkey Grab64.exe with the entries C:\Program Files\Grab\Grab64.exe and C:\Program Files\Grab\dll\pylon64\.

Method 3: Running the Application Using a Batch File#

To point your application to the pylon DLLs, you can write a batch file that will temporarily add the pylon DLL directories to the Windows PATH environment variable and then launch the application.

This is the recommended method in the following conditions apply:

• Your application's executable file(s) and the dependent pylon DLLs can't be placed in the same directory (see Method 1: Placing the pylon DLLs in the Application's Working Directory).
• Your application must be launchable via Command Prompt.
• You can't modify the source code of your application.

To deploy the pylon DLLs using a batch file:

1. Set up your installation routine to copy the required pylon DLLs. If your application is available in 32-bit and 64-bit versions, the 32-bit pylon DLLs must be copied to one target directory and the 64-bit pylon DLLs to another.
2. Open a text editor, e.g., Notepad.

3. If your application is available

   • only in a 32-bit version or only in a 64-bit version, add the following lines:

       @ECHO OFF
       SET relPath=DllDir
       SET PATH=%~dp0%relPath%;%PATH%
       SET app=%~dp0%~n0.exe
       "%app%"
   

   • in both 32-bit and 64-bit versions, add the following lines:

       @ECHO OFF
       SET relPathWin32=DllDir32
       SET relPathX64=DllDir64
       SET PATH=%~dp0%relPathWin32%;%~dp0%relPathX64%;%PATH%%
       SET app=%~dp0%~n0.exe
       "%app%
   

4. Replace the DllDir, DllDir32, and/or DllDir64 entries by the paths to the pylon DLL directories. The paths must be relative to the directory containing the application's executable files.

   Example: These are the target directories (sample values):

   • Executable files: C:\Program Files\Grab\
   • 32-bit pylon DLLs: C:\Program Files\Grab\dll\pylon32\
   • 64-bit pylon DLLs: C:\Program Files\Grab\dll\pylon64\

   In this case, you must set up the batch file like this:

       @ECHO OFF
       SET relPathWin32=dll\pylon32
       SET relPathX64=dll\pylon64
       SET PPATH=%~dp0%relPathWin32%;%~dp0%relPathX64%;%PATH%
       SET app=%~dp0%~n0.exe
       "%app%"
   

5. If your application is available

   • only in a 32-bit version or only in a 64-bit version, save the batch file with the same file name as your application's executable file and with a .cmd file extension.
     Example: If your application's executable file is named Grab.exe, save the batch file as Grab.cmd.

   • in both 32-bit and 64-bit versions, save the batch file twice: The first time with the file name of your 32-bit executable file, and the second time with the fil e name of your 64-bit executable file. The contents of the batch file can remain exactly the same.
     Example: If your application's executable files are Grab32.exe and Grab64.exe, save the batch file as Grab32.cmd and Grab64.cmd.

6. Set up your installation routine to copy the batch file(s) to the same directory as your application's executable file(s).

7. Make sure the user of your application launches the application via the batch file and not via the executable file (e.g., by creating desktop shortcuts to Grab32.cmd and Grab64.cmd).

Method 4: Using SetDllDirectory in the Source Code#

To point your application to the pylon DLLs, you can use the SetDllDirectory function (C++ only) in the source code of your application.

This is the recommended method if the following conditions apply:

• Your application's executable file(s) and the dependent pylon DLLs can't be placed in the same directory (see Method 1: Placing the pylon DLLs in the Application's Working Directory).
• Your application must be launchable via Command Prompt.
• You can modify the source code of your application.

To deploy the pylon DLLs using the SetDllDirectory function:

1. Set up your installation routine to copy the required pylon DLLs. If your application is available in 32-bit and 64-bit versions, the 32-bit pylon DLLs must be copied to one target directory and the 64-bit pylon DLLs to another.
2. Open your application project in an IDE, e.g., Visual Studio.

3. At the beginning of your application's source code, add the following preprocessor directives:

       // Preprocessor directives for SetDllDirectory
       #include <pylon/Platform.h>
       // Path helper functions
       #include "Shlwapi.h"
       #pragma comment(lib, "Shlwapi.lib")
       #include "TCHAR.h"
       // Link delay load implementation needed when using SetDllDirectory
       #pragma comment(lib, "delayimp")
   

4. In the application's main() function, add the following lines:

       // Set dll relative path
       #if defined PYLON_32_BUILD
       const TCHAR* relPath = TEXT("dllDirectory32");
       #elif defined PYLON_64_BUILD
       const TCHAR* relPath = TEXT("dllDirectory64");
       #endif
       // Path length of dll directory must be smaller than MAX_PATH
       TCHAR dirPath[MAX_PATH];
   
       // The following code is supported by Windows 7.
       // For Windows 8 or higher, other Windows Path Functions are recommended esp.
       // to avoid buffer overrun.
       const int cErrorGetModuleFileName = 1; // replace with your special exit code
       const int cErrorPathAppend = 1; // replace with your special exit code
       const int cErrorSetDllDirectory = 1; // replace with your special exit code
   
       // Assume this is the main function of a .exe, not of a dll. Otherwise use GetModuleHandle).
       if ((0 == GetModuleFileName(NULL, dirPath, MAX_PATH)) || (ERROR_INSUFFICIENT_BUFFER == GetLastError()))
       {
           return cErrorGetModuleFileName;
       }
       // For Windows 8 or higher the use of PathCchRemoveFileSpec is recommended.
       PathRemoveFileSpec(dirPath);
   
       // Avoid buffer overrun when using PathAppend (i.e. here we don't care about the
       // (also restricted) length of the dll's full path).
       // For Windows 8 or higher the use of PathCchAppend is recommended.
       if ((_tcslen(dirPath) + 1 + _tcslen(relPath) + 1 > MAX_PATH) || !PathAppend(dirPath, relPath))
       {
           return cErrorPathAppend;
       }
       if (!SetDllDirectory(dirPath))
       {
           return cErrorSetDllDirectory;
       }
   

5. Replace dllDirectory32 and dllDirectory64 by relative paths to the pylon DLL target directories (see step 1). The paths must be relative to the directory containing the application's executable files. You can use the double-dots specifier to denote the parent directory of the current directory.
   Example: These are the target directories (sample values):
   

   • Executable files: C:\Program Files\Grab\bin\
   • 32-bit pylon DLLs: C:\Program Files\Grab\dll\pylon32\
   • 64-bit pylon DLLs: C:\Program Files\Grab\dll\pylon64\

   In this case, you must replace dllDirectory32 by ..\\dll\\pylon32 and dllDirectory64 by ..\\dll\\pylon64.

6. Use the /DELAYLOAD linker switch to specify which DLLs to delay load:

   1. In the Solution Explorer pane, select a project.
   2. In the View menu, select Properties Pages.
   3. Navigate to Configuration Properties > Linker > Input.
   4. Modify the Delay Loaded Dlls entry.
      Example: /DELAYLOAD:PylonBase_v8_0.dll;PylonGUI_v8_0.dll
7. Build all versions of your project and deploy the newly created builds.

Method 5: Creating and Embedding Assembly Manifests#

To point your application to the pylon DLLs, you can create assembly manifests and embed them in your application project.

This is the recommended method if the following conditions apply:

• Your application's executable file(s) and the dependent pylon DLLs can't be placed in the same directory (see Method 1: Placing the pylon DLLs in the Application's Working Directory).
• Your application must be launchable via Command Prompt.
• You can modify the source code of your application.
• Your application doesn't support delayed loading of DLLs or your application already uses assembly manifests.

To deploy the pylon DLLs using assembly manifests:

1. Create and deploy the assembly manifest files (.manifest files). For more information, see Creating the Assembly Manifests (.manifest Files).
2. Create and deploy the application configuration files (.config files). For more information, see Creating the Application Configuration Files (.config Files).
3. Embed the assembly manifest in your application project. For more information, see Embedding the Manifest.

Creating the Assembly Manifests (.manifest Files)#

The .manifest files contain references to the pylon DLLs. For each version of your application (32 bit or 64 bit), you must create a separate .manifest file. Each file must be copied to the corresponding directory containing the pylon DLLs.

To create and deploy the .manifest file(s):

1. Open a text editor, e.g., Notepad.

2. If your application is available in a 32-bit version:

   1. Create a new text file and add the following lines:

          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
          <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
              <assemblyIdentity type="win32" name="assemblyName32" version="1.0.0.0" processorArchitecture="x86"/>
              <file name="dll32FileName1" hashalg="SHA1"/>
              <file name="dll32FileName2" hashalg="SHA1"/>
          </assembly>
      

   2. Replace assemblyName32 by a unique identifier for the 32-bit assembly, e.g., Grab.Assembly.

   3. Use the <file> tags to refer to each required 32-bit pylon DLL. Replace each dll32FileName entry by the file name of a required DLL. Add more lines if required.
      Example:

          <file name="GCBase_MD_VC141_v3_1_Basler_pylon.dll" hashalg="SHA1"/>
          <file name="GenApi_MD_VC141_v3_1_Basler_pylon.dll" hashalg="SHA1"/>
          <file name="Log_MD_VC141_v3_1_Basler_pylon.dll" hashalg="SHA1"/>
      

   4. Save the file with the same file name as assemblyName32 and with a .manifest file extension, e.g., save it as Grab.Assembly.manifest.

   5. Set up your installation routine to copy the .manifest file to the directory containing the 32-bit pylon DLLs, e.g., C:\Program Files\Grab\dll\pylon32.

3. If your application is available in a 64-bit version:

   1. Create a new text file and add the following lines:

              <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
              <assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
                  <assemblyIdentity type="win32" name="assemblyName64" version="1.0.0.0" processorArchitecture="amd64"/>
              <file name="dll64FileName1" hashalg="SHA1"/>
              <file name="dll64FileName2" hashalg="SHA1"/>
              </assembly>
      

      Note: type must always be win32, also for 64-bit applications.

   2. Replace assemblyName64 by a unique identifier for the assembly, e.g., Grab64.Assembly.
      If your application is available in both 32-bit and 64-versions, the identifier must be different from the identifier specified in step 2.

   3. Use the <file> tags to refer to each required 64-bit pylon DLL. Replace each dll64FileName entry by the file name of a required DLL. Add more lines if required.
      Example:

          <file name="GCBase_MD_VC141_v3_1_Basler_pylon.dll" hashalg="SHA1"/>
          <file name="GenApi_MD_VC141_v3_1_Basler_pylon.dll" hashalg="SHA1"/>
          <file name="Log_MD_VC141_v3_1_Basler_pylon.dll" hashalg="SHA1"/>
      

   4. Save the manifest file with the same file name as assemblyName64 and with a .manifest file extension, e.g., save it as Grab64.Assembly.manifest.

   5. Set up your installation routine to copy the .manifest file to the directory containing the 64-bit pylon DLLs, e.g., C:\Program Files\Grab\dll\pylon64.

Creating the Application Configuration Files (.config Files)#

The .config files point each application's executable file to its corresponding .manifest file. For each executable file (32 bit or 64 bit), you must create a separate .config file.

Each .config file must be copied to the same directory as the corresponding executable file.

To create and deploy the .config file:

1. Open a text editor, e.g., Notepad.

2. Add the following lines:

       <configuration>
           <windows>
               <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
                   <probing privatePath="dllPath"/>
               </assemblyBinding>
           </windows>
       </configuration>
   

3. Replace dllPath by the relative paths to the directories containing the 32-bit and 64-bit pylon DLLs. Delimit each directory path with a semicolon. Each path must be relative to the directory containing the application's executable files. You can use the double-dots specifier to denote the parent directory of the current directory.
   Example:

   • Executable files: C:\Program Files\Grab\bin\
   • 32-bit pylon DLLs: C:\Program Files\Grab\dll\pylon32\
   • 64-bit pylon DLLs: C:\Program Files\Grab\dll\pylon64\

   In this case, you must replace dllPath by ..\dll\pylon32;..\dll\pylon64.

4. Save the file with the same file name as your application's executable and with a .config file extension, e.g., save it as Grab.config.

5. If your application is available in 32-bit and 64-bit versions, save the file again with the file name of your 64-bit executable file, e.g., Grab64.config.
6. Set up your installation routine to copy the .config file(s) to the directory containing your application's executable file(s).

Embedding the Manifest#

After you have created the .manifest and .config files, you must embed the manifest in the source code of your application.

To embed the assembly manifest in your application project:

1. Open your application project in an IDE, e.g., Visual Studio.

2. If your application is available only in a 32-bit version or only in a 64-bit version:

   1. Add the following lines at the beginning of your application's source code:

          #pragma comment(linker,"/manifestdependency:\"type='win32' name='assemblyName' \
          version='1.0.0.0' processorArchitecture='procArch' \"")
      

   2. Replace assemblyName by the name of your assembly, e.g., Grab.Assembly.
      Replace procArch by x86 for a 32-bit application or by amd64 for a 64-bit application.

      Note: type must always be win32, also for 64-bit applications.

3. If your application is available in both 32-bit and 64-bit versions:

   1. Add the following lines at the beginning of your application's source code:

          #if defined _M_IX86
          #pragma comment(linker,"/manifestdependency:\"type='win32' name='assemblyName32' \
          version='1.0.0.0' processorArchitecture='x86' \"")
          #elif defined _M_X64
          #pragma comment(linker,"/manifestdependency:\"type='win32' name='assemblyName64' \
          version='1.0.0.0' processorArchitecture='amd64' \"")
          #endif
      

   2. Replace assemblyName32 by the 32-bit assembly name (e.g., Grab.Assembly)

   3. Replace assemblyName64 by the 64-bit assembly name (e.g., Grab64.Assembly).

4. Build all versions of your project and deploy the newly created builds.