Bindings for SDL2 in Rust
Rust-SDL2 is a library for talking to the new SDL2.0 libraries from Rust. Low-level C components are wrapped in Rust code to make them more idiomatic and abstract away inappropriate manual memory management.
Rust-SDL2 uses the MIT license.
If you want a library compatible with earlier versions of SDL, please see here
We currently target the latest stable release of Rust.
Install these through your favourite package management tool, or via http://www.libsdl.org/
Ubuntu example:
sudo apt-get install libsdl2-dev
Fedora example:
sudo dnf install SDL2-devel
You might also need a C compiler (gcc
).
On OSX, it's a good idea to install these via homebrew.
brew install sdl2
Then add the following to your ~/.bash_profile
if not already present.
export LIBRARY_PATH="$LIBRARY_PATH:/usr/local/lib"
You can also get sdl2 via macports
.
sudo port install libsdl2
Then add the following to your ~/.bash_profile
if not already present.
export LIBRARY_PATH="$LIBRARY_PATH:/opt/local/lib/"
If you're having issues with either homebrew or macports, see here.
You can download and install the SDL2 Mac OS X framework from: https://www.libsdl.org/download-2.0.php
To make the sdl2
crate link with the SDL2 framework, you will need to enable
the use_mac_framework
feature. To build and test the sdl2
crate with this
feature, use:
cargo test --features use_mac_framework
To depend on the sdl2
crate with this feature enabled, put the following in
your project's Cargo.toml
file:
[dependencies.sdl2]
features = ["use_mac_framework"]
version = ... # Whichever version you are using
Alternatively, you can re-export the feature in your package by putting the
following in your Cargo.toml
file:
[features]
default = []
use_sdl2_mac_framework = ["sdl2/use_mac_framework"]
-
Download mingw development libraries from http://www.libsdl.org/ (SDL2-devel-2.0.x-mingw.tar.gz).
-
Unpack to a folder of your choosing (You can delete it afterwards).
-
Copy all lib files from
SDL2-devel-2.0.x-mingw\SDL2-2.0.x\x86_64-w64-mingw32\lib
to (for Rust 1.6 and above)
C:\Program Files\Rust\lib\rustlib\x86_64-pc-windows-gnu\lib
or to (for Rust versions 1.5 and below)
C:\Program Files\Rust\bin\rustlib\x86_64-pc-windows-gnu\lib
or to your library folder of choice, and ensure you have a system environment variable of
LIBRARY_PATH = C:\your\rust\library\folder
For Rustup users, this folder will be in
C:\Users\{Your Username}.multirust\toolchains\{current toolchain}\lib\rustlib\{current toolchain}\lib
Where current toolchain is likely stable-x86_64-pc-windows-gnu
.
-
Copy SDL2.dll from
SDL2-devel-2.0.x-mingw\SDL2-2.0.x\x86_64-w64-mingw32\bin
into your cargo project, right next to your Cargo.toml.
-
Download MSVC development libraries from http://www.libsdl.org/ (SDL2-devel-2.0.x-VC.zip).
-
Unpack SDL2-devel-2.0.x-VC.zip to a folder of your choosing (You can delete it afterwards).
-
Copy all lib files from
SDL2-devel-2.0.x-VC\SDL2-2.0.x\lib\x64\
to (for Rust 1.6 and above)
C:\Program Files\Rust\lib\rustlib\x86_64-pc-windows-msvc\lib
or to (for Rust versions 1.5 and below)
C:\Program Files\Rust\bin\rustlib\x86_64-pc-windows-msvc\lib
or to your library folder of choice, and ensure you have a system environment variable of
LIB = C:\your\rust\library\folder
For Rustup users, this folder will be in
C:\Users\{Your Username}.multirust\toolchains\{current toolchain}\lib\rustlib\{current toolchain}\lib
Where current toolchain is likely stable-x86_64-pc-windows-msvc
.
-
Copy SDL2.dll from
SDL2-devel-2.0.x-VC\SDL2-2.0.x\lib\x64\
into your cargo project, right next to your Cargo.toml.
If you're using cargo to manage your project, you can download through Crates.io:
[dependencies]
sdl2 = "0.27"
Alternatively, pull it from GitHub to obtain the latest version from master
[dependencies.sdl2]
git = "https://github.com/AngryLawyer/rust-sdl2"
Otherwise, clone this repo and run cargo
cargo build
You can enable features such as ttf, image, gfx and mixer by adding this instead:
[dependencies.sdl2]
version = "0.27"
default-features = false
features = ["ttf","image","gfx","mixer"]
Those features need their respective libraries, which can be found at these locations : (the install process is the same as SDL2)
As of now, sdl2_net meaningless compared to what other crates
such as serde
and bincode
can offer.
We highly recommend using those to develop anything UDP or TCP
realted (along with futures or TCP/UDP from std).
If you still want an implementation of sdl2_net, you can try to add it in this repo as a feature via a Pull Request. A somewhat outdated version of this binding can be found here
We have several simple example projects included:
cargo run --example demo
You can see the full list in the examples/
folder
If you want to use OpenGL, you also need the gl-rs package. If you're using cargo, just add these lines to your Cargo.toml:
[dependencies.gl]
git = "https://github.com/bjz/gl-rs"
Then you need to add this initialization code to establish the bindings:
let sdl_context = sdl2::init().unwrap();
let video_subsystem = sdl_context.video().unwrap();
gl::load_with(|name| video_subsystem.gl_get_proc_address(name) as *const _);
Note that these bindings are very raw, and many of the calls will require unsafe blocks.
Rust, and Rust-SDL2, are both still heavily in development, and you may run
into teething issues when using this. Before panicking, check that you're using
the latest version of both Rust and Cargo, check that you've updated Rust-SDL2
to the latest version, and run cargo clean
. If that fails, please let us know
on the issue tracker.