Wiki Page Content

Differences between revisions 1 and 4 (spanning 3 versions)
Revision 1 as of 2014-11-26 18:33:23
Size: 6363
Editor: RyanGordon
Comment: Initial add.
Revision 4 as of 2014-11-26 21:24:00
Size: 8556
Editor: RyanGordon
Comment: More work
Deletions are marked like this. Additions are marked like this.
Line 16: Line 16:
SDL 2.0, unlike 1.2, uses the zlib license (see FAQLicensing), which means you can build a static library linked directly to your program, or just compile SDL's C code directly as part of your project. You are completely allowed to do that. However, we encourage you to ''not'' do this for various technical and moral reasons, and won't cover the details of how to in this document. SDL 2.0, unlike 1.2, uses [[FAQLicensing|the zlib license]], which means you can build a static library linked directly to your program, or just compile SDL's C code directly as part of your project. You are completely allowed to do that. However, we encourage you to ''not'' do this for various technical and moral reasons, and won't cover the details of how to in this document. You may not statically link SDL 1.2 in most cases due to its LGPL licensing, but you should really stop using SDL 1.2 anyhow.
Line 33: Line 33:
Line 62: Line 61:
SDL on Unix should only link against the C runtime (glibc). Every thing else it needs will be dynamically loaded at runtime: X11, ALSA, d-bus, etc. This means it is possible to build an SDL that has support for all sorts of targets built in, and it will examine the system at runtime to decide what should be used (for example, if Xlib isn't available, it might try to load Wayland support, etc). In that respect, if you plan to ship the SDL binary that you build, it is to your benefit to make sure your system has development headers for as many targets as possible, regardless of what you plan to personally use, so your final library is as robust as possible. See docs/README-linux.md for more details.

=== SteamOS ===

If you are shipping a Linux game on Steam, or explicitly targeting SteamOS, the system is guaranteed to provide SDL. Steam will set up the dynamic loader path so that a known-good copy of SDL is available to any program that needs it. Steam provides both SDL 1.2 and 2.0 in this manner, for both x86 and amd64, in addition to several add-on libraries like SDL_mixer. When shipping a Linux game on Steam, do not ship a build of SDL with your game. Link against SDL as normal, and expect it to be available on the player's system. This allows Valve to make fixes and improvements to their SDL and those fixes to flow on to your game.

We are obsessive about SDL2 having a backwards-compatible ABI. Whether you build your game using the Steam Runtime SDK or just about any old copy of SDL2, it ''should'' work with the one that ships with Steam.
Line 67: Line 74:

On Windows, SDL does not depend on a C runtime at all, not even for malloc(). This means it's possible to build SDL with almost any Windows compiler and have it work with a program built with any other. Furthermore, it means that SDLmain (the small static .lib file that optionally provides WinMain() does not force you to deal with Debug vs Release builds in your app, since it doesn't need either a Debug or Release C runtime. One .lib should work everywhere.
Line 84: Line 93:
!!! WRITE ME See [[Android|Building SDL2 for Android]]

Installing SDL

(This page is a work in progress.)

How to install SDL varies depending on your platform.

SDL 1.2 isn't covered here. It can be installed on legacy platforms that SDL2 doesn't support, such as Mac OS 9 or OS/2, but settling for 1.2 would not be a drop-in replacement for 2.0. Most of these installation instructions happen to work with 1.2, however, on the platforms we cover.

Static linking

SDL 2.0, unlike 1.2, uses the zlib license, which means you can build a static library linked directly to your program, or just compile SDL's C code directly as part of your project. You are completely allowed to do that. However, we encourage you to not do this for various technical and moral reasons, and won't cover the details of how to in this document. You may not statically link SDL 1.2 in most cases due to its LGPL licensing, but you should really stop using SDL 1.2 anyhow.

Supported platforms

Linux/Unix

Several other platforms will be built "the Unix way," so we'll describe this platform first.

SDL supports most popular flavors of Unix: Linux, the various BSDs, Solaris, and other things like them.

First! Do you need to compile SDL yourself? It's possible your distribution's package manager already did it for you!

Debian-based systems (including Ubuntu) can simply do "sudo apt-get install libsdl2-2.0" to get the library installed system-wide, and all sorts of other useful dependencies, too. "sudo apt-get install libsdl2-dev" will install everything necessary to build programs that use SDL. Please see docs/README-linux.md in SDL's source code for a more complete discussion of packages involved.

Red Hat-based systems (including Fedora) can simply do "sudo yum install SDL2" to get the library installed system-wide, or "sudo yum install SDL2-devel" to get headers and other build requirements ready for compiling your own SDL programs.

Gentoo users can "sudo emerge libsdl2" to get everything they need.

If you're compiling SDL yourself, here's what we refer to as "the Unix way" of building:

  • Get a copy of the source code, either from Mercurial or an official tarball or whatever.
  • Make a separate build directory (SDL will refuse to build in the base of the source tree).
  • Run the configure script to set things up.
  • Run "make" to compile SDL.
  • Run "make install" to install your new SDL build on the system.

This looks something like this:

hg clone https://hg.libsdl.org/SDL SDL
cd SDL
mkdir build
cd build
../configure
make
sudo make install

The last command says "sudo" so we can write it to /usr/local (by default). You can change this to a different location with the --prefix option to the configure script. In fact, there are a LOT of good options you can use with configure! Be sure to check out its --help option for details. SDL tries to do the right thing by default, though, so you can usually get away with no options at all.

An (experimental!) alternative to the configure script is the CMake project file. It works on similar principles to the configure script, but you might find that you enjoy it more, if this is the sort of thing you generally enjoy in the first place. Driving that is left as an exercise for the reader.

Once you have the library installed, you can use the sdl2-config program to help you compile your own code:

  • gcc -o myprogram myprogram.c `sdl2-config --cflags --libs`

SDL on Unix should only link against the C runtime (glibc). Every thing else it needs will be dynamically loaded at runtime: X11, ALSA, d-bus, etc. This means it is possible to build an SDL that has support for all sorts of targets built in, and it will examine the system at runtime to decide what should be used (for example, if Xlib isn't available, it might try to load Wayland support, etc). In that respect, if you plan to ship the SDL binary that you build, it is to your benefit to make sure your system has development headers for as many targets as possible, regardless of what you plan to personally use, so your final library is as robust as possible. See docs/README-linux.md for more details.

SteamOS

If you are shipping a Linux game on Steam, or explicitly targeting SteamOS, the system is guaranteed to provide SDL. Steam will set up the dynamic loader path so that a known-good copy of SDL is available to any program that needs it. Steam provides both SDL 1.2 and 2.0 in this manner, for both x86 and amd64, in addition to several add-on libraries like SDL_mixer. When shipping a Linux game on Steam, do not ship a build of SDL with your game. Link against SDL as normal, and expect it to be available on the player's system. This allows Valve to make fixes and improvements to their SDL and those fixes to flow on to your game.

We are obsessive about SDL2 having a backwards-compatible ABI. Whether you build your game using the Steam Runtime SDK or just about any old copy of SDL2, it should work with the one that ships with Steam.

Windows

SDL currently provides Visual Studio project files for Visual Studio 2008, 2010, 2012, and 2013 in various flavors, and the CMake files can often generate project files for other Windows compilers.

!!! WRITE ME cygwin, mingw64, cmake, buildbot pregenerated builds, etc.

On Windows, SDL does not depend on a C runtime at all, not even for malloc(). This means it's possible to build SDL with almost any Windows compiler and have it work with a program built with any other. Furthermore, it means that SDLmain (the small static .lib file that optionally provides WinMain() does not force you to deal with Debug vs Release builds in your app, since it doesn't need either a Debug or Release C runtime. One .lib should work everywhere.

Mac OS X

You can build for Mac OS X "the Unix way" with the configure or CMake scripts, and Xcode projects are also provided. You can ship an SDL.framework, or just build the .dylib file and ship it with an appropriate install_name to ship beside your program's binary.

!!! WRITE ME cmake, buildbot pregenerated builds, etc.

Haiku

Build SDL "the Unix way" with the configure or CMake scripts.

iOS

!!! WRITE ME

Android

See Building SDL2 for Android

Raspberry Pi

!!! WRITE ME

NaCL

!!! WRITE ME

HTML5

!!! WRITE ME

WinRT/Windows 8/WinPhone

!!! WRITE ME

Not supported

If your favorite system is listed here, we aren't working on it. If you send reasonable patches, we are happy to take a look, though! SDL 1.2's API and feature set is different than SDL 2 (dramatically different in some cases), but it's possible that 1.2 still supports these systems.

Consoles (PlayStation, XBox, Wii, etc)

SDL2 does not currently support these platforms, but we'd really like to! If you work for Sony, Microsoft, or Nintendo, we would like to port SDL2 to these platforms and provide support to registered developers in a separate repository. Please get in touch with us!

BeOS

This probably works, or could be made to work, using the Haiku target, but there are no plans to do so. SDL 1.2 still supports BeOS.

Nintendo DS

This worked at some point using a homebrew toolkit, but we removed it due to bitrot. There's some rudimentary support in SDL 1.2.

Sony PSP

This worked at some point using a homebrew toolkit, and while it is currently still in the source tree, no one is working on it. 1.2 did not support the PSP either.

Mac OS 9 ("Mac OS Classic")

Support was removed in SDL 2.0. SDL 1.2 still supports Mac OS Classic.

IBM OS/2 and eComStation

Support was removed in SDL 2.0. SDL 1.2 still supports OS/2.

Windows 95/98/ME

Support was removed in SDL 2.0 (Windows XP and later are supported). SDL 1.2 still supports Win9x.

QNX

Support was removed in SDL 2.0. SDL 1.2 still supports QNX.

AmigaOS and MorphOS

Support was removed in SDL 2.0 (and later versions of 1.2, too). There are forks of SDL 1.2 that support them, though.

Dreamcast

Support was removed in SDL 2.0. SDL 1.2 had homebrew support for the Dreamcast.

Atari MiNT

Support was removed in SDL 2.0. SDL 1.2 still supports it.

Symbian

Support was removed in SDL 2.0. SDL 1.2 still supports it.

None: Installation (last edited 2019-05-09 18:34:17 by RyanGordon)

Feedback
Please include your contact information if you'd like to receive a reply.
Submit