fermium
This is always no_std
.The bindings use libc
for the C type declarations.
Currently only supports the desktop platforms: Windows, Mac, and Linux.
Why Not Use sdl2-sys
?
Fair question. I'd say that between that crate and this crate there's two notable differences:
- A change they could easily make (at the flip of a switch):
Debug
andPartialEq
impls for all the types. - A change that would probably require a long fiddly refactor for their higher
level wrapper crate: All the SDL2 enums are just
const
values, instead of Rustenum
types.
If those don't sound like a good enough reason to switch to this crate, keep
using sdl2-sys
.
How To Use This Crate
-
Before Building: Since this crate is about SDL2 bindings, it obviously requires SDL2. You will need the latest stable version of SDL2 (currently
2.0.9
).- For Windows, the crate packages the MSVC development libraries from the SDL2 download page
- For Linux, there are no provided downloads, they tell you to just install using your package manager. However, the version that's usually in package managers is often not up to date, so honestly just build it from source. The travis file of this repository has an example.
- For Mac you can download the dmg installer from the SDL2 website, or use Homebrew, or build from source. Note that if you build from source yourself there's a few special flags you need to use or you'll get build errors. The travis file has an example of how to use the gcc-fat.sh script to make things build properly.
-
Building: This library uses bindgen as a
build-dependency
. By default it will attempt to invoke the CLI version of the program, but if you enable theuse_bindgen_lib
feature then it will buildbindgen
as a library and use it that way. Either as a cli program or as a library,bindgen
requires a working copy ofclang
(3.9 or later) to be installed. Thebindgen
requirements page has instructions for installing clang for each major OS. Windows Users: after installing LLVM you must manually make an environment variable forLIBCLANG_PATH
pointing to the install directory that haslibclang.dll
(eg:D:\programs\LLVM\bin
)- When building you can also activate the
static_link_sdl2_use_with_caution
feature if you would like to staticly link SDL2 instead of the normal dynamic link. - On non-Windows platforms, this feature requires that your copy of SDL2 was
compiled wih the
-fPIC
flag. - On non-Windows platforms this feature will add every directory in the
LD_LIBRARY_PATH
list to be searched for the static lib files (which should find SDL2 just fine). - As the name implies, you should generally not statically link SDL2, unless your target platform absolutely requires it.
- When building you can also activate the
-
Running: Once you've compiled your program using this library, you'll need to have the SDL2 dynamic library somewhere that the OS can find for your program to run.
- For Windows, the SDL2 download page has both a 32-bit
version and
64-bit version of
SDL2.dll
available. It's also in the lib directory of this repository. - On Mac and Linux, generally whatever you used to install SDL2 will have
placed the shared library in the correct system directory for all the shared
libraries to go. If this is somehow not the case, you can set
LD_LIBRARY_PATH
to point to an appropriate directory.
- For Windows, the SDL2 download page has both a 32-bit
version and
64-bit version of
-
Shipping: When you're ready to send a program out the door, how should you package SDL2 along with your program? Well, it depends.
- For Windows, you should probably just send your
SDL2.dll
file along side yourprogram.exe
. DLL loading starts by checking the same directory as the executable, so it's sure to find the correct DLL that way. If the user really needs to they can replace the DLL later. Having one copy ofSDL2.dll
per program isn't a huge deal, it's only about 1.4 megabytes. - For Mac and Linux you could ship a copy of the SDL2 shared library with your program, but it's honestly better to assume that the user already has it correctly installed they way that they want things setup, and just give them instructions to install it if they somehow don't have SDL2 at all.
- For Steam OS you literally aren't allowed to ship your own version of SDL2, they keep the latest version installed as part of the OS setup, and you're not allowed to mess with it.
- For Windows, you should probably just send your
License
This crate uses the Zlib license (the same license that SDL2 itself uses).