fermium

The fermium crate is raw bindings to the SDL2 C API. For the "high-level wrapper" crate, please see beryllium.

Currently this targets SDL2-2.0.12.

It uses a bundled copy of SDL2 on Windows, and the system version on Mac/Linux.

The bindings are not generated at compile time, and you do not need to have bindgen or any of its dependencies installed. Instead, bindings files have been pre-generated for select common build targets (and I'm happy to accept PRs for more!).

For the bindings to work the program obviously has to be linked against the SDL2 library written in C. You have to select if you want to perform a dynamic link or a static link.

• By default the dynamic_link feature is active.
  • When a dynamic link is performed your program will depend on having the SDL2 shared library available at runtime. This means that the user will have to have it installed. On Windows you can place SDL2.dll directly into the same directory as the binary you send to people.
  • If you're on Windows and feeling lazy you can cargo install fermium and then you'll get a binary named fermium available and it'll write the 32-bit or 64-bit SDL2.dll file into the current directory, so setting up a new project is a snap. If you have SDL2.dll in the project root then cargo run will work normally, you only have to fiddle with moving files around when you go to do your final release.
• If you'd like to do a static link then you can disable default features and enable the static_link feature.
  • If you enable static linking on Windows then you will need to have cmake installed for it to build the SDL2 static library. The source code is already bundled into the crate, but unfortunately Visual Studio doesn't keep stability between versions so you have to actually build the library with your own version of Visual Studio.
• If both link modes are selected then the crate will refuse to build, so only select one or the other.
• Yes, this does mean that those two features are not "purely additive" like how cargo features are supposed to be. However, this is a truly "one or the other" decision, and cargo has no support for such a thing right now. Don't blame me, blame cargo.

Platforms Supported

On Windows MSVC, this crate will "just work" all on its own. The necessary files are packaged into the crate and you don't need to do anything special. Windows is the platform for video games, so naturally gamedev library developers should make sure that gamedev libraries have top quality support on Windows. They absolutely shouldn't require you to get files and unpack them yourselves into a bunch of special directories and then use a custom build script, that would obviously just be a terrible user experience.

On Mac or Linux you'll need to already have SDL2 installed via your method of choice. Homebrew or apt-get or pacman or whatever other thing. It's been tested with Mac/Homebrew and Debian/apt-get. The location of the files varies from system to system, but the build.rs will do its best to guess. If it doesn't build on your flavor of Linux send in a PR.

This does not work with iOS, Android, or Emscripten. Mostly because I don't know anything about setting up those dev environments at all. PRs accepted if you want to throw stuff my way.

Versioning Explanation

SDL2 as a library doesn't follow semver, so this crate can't quite follow semver either.

• With standard SemVer, a version is given as major.minor.patch
• With SDL2, a version is basically 2.major.minor
  • Also, starting with 2.0.10, even minor versions are "release" and odd minor versions are "dev", similar to how the Linux kernel works.
  • They update the final value when there's new functions or improvements to old functions. In this case, there's no actual ABI breaks to any part of the library. Sometimes hints or other constants get added and removed, but they explicitly don't consider such a small thing to be a breaking change even if it does mean you have to edit your source a tiny bit.
  • Not that there ever has been, but if there were to be an ABI break to the library, then they would update the major version.

To try and make the fermium version indicate the SDL2 version that it's trying to bind to, while also trying to play nice with cargo's semver expectations, we'll have a major version of 200 to represent the 2.0. part of things, and then we'll set the minor version to be the SDL2 minor version (such as 12), and then we'll use patch releases if we need to put out an update in between when SDL2 does releases.

Project Logo