Building

Binary dependencies are obtained from the deps/ submodule as necessary.

Windows

Only the MinGW-w64 toolchain is supported. (Despite its name, it can build for both 32-bit and 64-bit Windows.) Building with Microsoft toolchains is completely unsupported and probably impossible.

A fully functional libantumbra build consists of:

libantumbra.dll
libusb-1.0.dll
antumbratool.exe
glowdrvinst/
  glowdrvinst.exe
  libwdi.dll
  msvcr120.dll

Darwin / OS X

libantumbra can be linked against either the system libusb (such as might be installed with MacPorts, Homebrew, etc) or a copy from deps/. Only the latter approach is supported as it is the most portable.

The target library specifies its own path (“install name”), which is then stored at build time in the binary that references it. Some voodoo must be done in order for runtime library resolution to work properly. See the Makefile if you’re interested.

libantumbra.framework

Darwin has the concept of “frameworks”. A framework bundles library headers and binaries together into a single convenient unit. These may be linked against by passing -framework SomeFrameworkName to ld(1) or adding them to an Xcode project.

The basic structure of a framework, named SomeFrameworkName in this example, is thus:

SomeFrameworkName.framework/  # (appears as a single file in Finder)
  SomeFrameworkName           # dynamic library without .dylib extension
  Headers/
    ...
  Resources/
    Info.plist

Most frameworks are more complicated and may include multiple versions or additional resources. But this is all we need for libantumbra.

On Darwin, libantumbra.framework is implied by the all target. libusb is included in the framework.

libantumbra.framework assumes it’s embedded in your application in the usual Frameworks/ bundle subdir. If it isn’t, you must change either the install name of libantumbra.framework/libantumbra or your binary’s dependency reference.

Linux

We link against system libusb using flags provided by pkg-config. No binary dependencies are pulled in from deps/.

OS requirements

Windows

No drivers are required. libusb can access USB devices using the built-in WinUSB API. However, the WinUSB driver must be “installed” (i.e. registered via INF file) for a given device before it can be used, otherwise all I/O will fail.

glowdrvinst.exe installs the WinUSB driver for Glow devices. If run multiple times, it will install multiple instances of the driver (redundant but harmless).

Darwin / OS X

No drivers are required. Ordinary users should be able to access Glow devices out of the box.

Linux

No drivers are required. However, for non-root users to access Glow devices, they must have read and write permissions on the associated USB device node (/dev/bus/usb/...).

See glow-udev.rules for one possible setup. This file can be placed in /etc/udev/rules.d. If udev does not automatically load the new rules, all rules can be manually reloaded by udevadm control --reload. It may be necessary to unplug and reconnect all Glow devices before the new configuration takes effect. Members of the usb group will have read/write access to Glow devices. To add a user to the usb group, run gpasswd -a <username> usb. If the usb group does not already exist, it must be created first (groupadd -r usb).