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

Installing and compiling libwdi

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. This binary can be used on Windows 2000.

• ​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 (has not been updated for months and can no longer produce a working libwdi).

• ​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. Also note that Microsoft crippled the 2010 version of Visual C++ Express, so that it chokes on importing project files that have 64 bit builds. If you plan on using Express 2010, you'll have to recreate the project files from scratch.

• ​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. Note however that the binaries produced from DDK will not be compatible with Windows 2000. To produce Windows 2000 compatible binaries, you must use a multilib version of MinGW-w64.

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

• Cross compilation:
  Not supported yet, 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.

Using a custom driver file with libwdi

If you have a custom driver that you would like to use with libwdi (eg, a custom USB .sys file and DLL, or a driver with a signed .inf+.cat), you can easily configure libwdi to install your driver instead of libusb0.sys/WinUSB:

1. Create a directory containing all the required driver files you need to embed in the library. This directory will be parsed recursively when creating the library, and recreated with the exact same structure (but in the libwdi user directory) before installation.
2. Use either the --with-userdir option when running configure (MinGW or cygwin) or set the #define USER_DIR in msvc/config.h (MS environments) to point to the directory above. You can also setup the WinUSB or libusb0.sys directories if you want to include these driver files as well.
3. In your application, use wdi_prepare_driver() with the driver_type set to WDI_USER for the options parameter (or, if this is the only driver embedded, you can leave the options blank) and call wdi_install_driver with the name of your inf file.

Notes:

1. Unless you manually edit libdwi/embedder_files.h it is not possible to differentiate between a 32 bit or 64 bit install, so both the 32 and 64 bit driver files must be included in your directory
2. Because it is impossible for libwdi to guess how the inf file for a custom driver should be generated, you must provide your own inf file along with the driver, and set all its parameters accordingly.