Installing and configuring libwdi

​(Previous) ​(Next) ​(Back to Table of Content)

Prerequisites

Compilation of libwdi is supported for the following environments, with the restrictions indicated below:

• ​MinGW (32 bit):
  Will only allow the production of a 32 bit library, which is incompatible with 64 bit Windows platforms.

• ​MinGW-w64 (64 bit):
  By default, will only produce 64 bit binaries, that are incompatible with 32 bit platforms. However, you can either recompile MinGW-w64 so that it supports the -m32 option (for production of 32 bit binaries) or use the latest WPG System 64, that can also be downloaded from ​horizonchess.com.

• ​Microsoft Visual C++ (Visual Studio), either Express or full version:
  Currently only Visual Studio 2008 project files are provided. If you have the commercial version of Visual Studio, you should be able to produce both win32 and x64 binaries with Visual C++. If you have the free Express version, you will only be able to produce a 32 bit library, that is incompatible with 64 bit platforms. Take not that the Express version also required the distribution of Microsoft redistributables along with your applications or libraries.

• ​Windows DDK build environment:
  This is the free, recommended environment for libwdi compilation. This will produce both the 32 and 64 bits binaries required for universal use of libwdi.

• ​Cygwin (32 bit):
  Will only work if you have installed the -mno-cygwin extensions. Native cygwin compilation is not supported.

• Cross compilation:
  Not supported, as the building if libwdi relies on a custom Windows embedder executable, to create the resource include, and this embedder is both created and run during the compilation process.

Depending on the driver files you are planning to enable in libwdi, you will also require:

• The WinUSB driver files from the ​Windows DDK. This is regardless of whether you use the DDK build environment to compile libwdi.
• The latest libusb0.sys driver files from ​libusb-win32

MinGW/cygwin compilation also requires the following packages to be installed:

• autotools (automake, autoconf, libtool), if running the autogen.sh from git
• getopt, to compile the zadic sample

Configuration

Provided that you have one of the environments highlighted above and retrieved the source (either from a tarball or the git repository), you need to configure the building of libwdi as follows:

• MinGW or cygwin:
  If downloaded from git, from a shell prompt, run ./autogen.sh. This is required to create the configure and Makefile scripts. You might want to edit autogen.sh to set the configure options
  Run configure --help to select your options, or refer to the list below:
  • --enable-shared: build shared libraries (default y)
  • --enable-static: build static libraries (default y)
  • --enable-32bit: build 32 bit compatible library if -m32 is available (default y)
  • --enable-64bit: build 64 bit compatible library if -m64 is available (default y)
  • --enable-log: enable library logging (default y)
  • --enable-debug-log: force debug logging (cannot be disabled, default n)
  • --enable-toggable-debug: enable switchable debug logging (default n)
  • --enable-debug: include debug symbols for gdb (default y)
  • --enable-examples-build: build example applications (default n)
  • --with-ddkdir="<dir>": embed WinUSB driver files from the following DDK location
  • --with-libusb0="<dir>": embed libusb0 driver files from the following location
  • --with-userdir="<dir>": embed user defined driver files from the following location
    
  Notes:
  1. At least one of --with-ddkdir, --with-libusb0, --with-userdir must be specified when running configure.
  2. configure will check the ddk and libusb0 directories for the relevant driver files, and prevent completion if they are not found.

• DDK or MSVC:
  Edit the file msvc/config.h to set/modify your options, or refer to the list below:
  • #define DDK_DIR "<dir>": embed WinUSB driver files from the following DDK location
  • #define LIBUSB0_DIR "<dir>": embed libusb0 driver files from the following location
  • #define USER_DIR "<dir>": embed user defined driver files from the following location
  • #define OPT_M32: build 32 bit compatible library if possible
  • #define OPT_M64: build 64 bit compatible library if possible
  • #define ENABLE_LOGGING: enable library logging
  • #define ENABLE_DEBUG_LOGGING: force debug logging (cannot be disabled)
  • #define INCLUDE_DEBUG_LOGGING: enable switchable debug logging
  • #define WDF_VER: define the version of the WDF CoInstaller? for WinUSB. If you are using the current version, this should be set to "01009"
    
  Notes:
  1. Make sure you edit msvc/config.h and set at least one of DDK_DIR, LIBUSB0_DIR or USER_DIR to a valid directory.
  2. As DDK_DIR is automatically set when building from the DDK, if you want to prevent the embedding of the WinUSB files, you need to edit libwdi/embedder_files.h

Compilation

Once you have configured libwdi according to your needs:

• MinGW or cygwin:
  • Run 'make'
  • The resulting library and examples can be retrieved in the .libs directory
• Visual Studio:
  • Select your target (Release/Debug, Win32/x64) and select 'Build'
  • The resulting library and examples can be retrieved from <arch><Release|Debug> (eg: ".x64Release")
• DDK:
  • Open the relevant build command prompt (eg. "Windows XP x86 Free Build" for a 32/64 library compatible with XP and later), then navigate to the libwdi directory and run 'ddk_build.cmd' or 'ddk_build DLL' to build either the static or dynamic version of the library. DLL must be specified in uppercase if needed.
  • The resulting library and examples can be retrieved from their respective source directory.