Skip to content

Install

Jump to bottom
Pete Batard edited this page Mar 27, 2014 · 29 revisions

Installing and compiling libwdi

Table of Contents

Latest official release

The latest official release of libwdi can be donwloaded here. Or you can also use git to retrieve the latest development tree.

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. The produced binary can be used on Windows 2000 and later.
  • 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 TDM64 to produce 32 bit binaries that are compatible with 64 bit platforms. The produced binary can be used on Windows 2000 and later.
  • Microsoft Visual C++ (Visual Studio), either Express or full version:
    Currently only Visual Studio 2012 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++. The produced binary can be used on Windows XP and later.
    Note that if you have the free Express version and you want to produce 64 bit binaries, you may have to install the Windows SDK.
  • 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. The produced binary can be used on Windows XP and later.
  • Cross compilation:
    Is supported, as per git revision w120 (or libwdi v1.0.3). The standard --host=<host-triplet> option can be applied to either configure or autogen.sh
    Because the building if libwdi relies on running a custom embedder during the build process, your build platform must be able to compile code that can run on the platform. As such, you might have to specify the CC_FOR_BUILD environment variable with the relevant options for your build environment. For more information, have a look at the FAQ.
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, and/or the latest libusbK.sys driver files from libusbK.
MinGW 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 & Compilation

IMPORTANT: If you are not using the latest WinUSB driver files (from the Windows 8 Driver Kit), you must edit your config.h and set WDF_VER to the relevant WDF version. For instance, if you used the WinUSB installer files from WinDDK 7600.16385.0, you should use: WDF_VER=1009 (when compiling with MS compilers) or add the option --with-wdfver=1009 when invoking configure (MinGW).

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, cygwin or cross compilation:
    • (Optional) If cross-compiling, and if the default CC (as detected by configure) does not produce executables that can run on your platform, define a CC_FOR_BUILD environment variable with the required options.
    • (Optional) If downloaded from git, from a shell prompt, run ./autogen.sh. This is required to create the configure and Makefile scripts. You can feed the same options to autogen.sh as the ones you feed to configure
    • Run configure --help to select your options, or refer to the list below, and then run configure:
      • --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-libusbk="<dir>": embed libusbK 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-libusbK, --with-userdir must be specified when running configure.
        2. If not cross-compiling, configure will check the DDK, libusb0 and libusbK directories for the relevant driver files, and alert you if they are not found.
    • Run 'make'
    • The resulting library and examples can be retrieved in the .libs directory
  • DDK or Visual Studio:
    • Common 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 libusb-win32 driver files from the following location
      • #define LIBUSBK_DIR "<dir>": embed libusbK 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, LIBUSBK_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.
    • 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: .\x64\Release\)
    • DDK/WDK:
      • 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 configure libwdi to install your driver instead of libusb0/libusbK/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/cross-compilation) or set the #define USER_DIR in msvc/config.h (MS environments) to point to the directory above. You can also setup the WinUSB, libusb0 or libusbK 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.

CC-BY-SA 4.0
Copyright © 2012-2024 Pete Batard

Clone this wiki locally