Skip to content

Latest commit

 

History

History
179 lines (132 loc) · 5.85 KB

README.md

File metadata and controls

179 lines (132 loc) · 5.85 KB
Raw

SDL2 CMake modules

This repository contains CMake modules for finding and using the SDL2 library as well as other related libraries:

These modules are based on the SDL (1.2) modules, with the same names, distributed with the CMake project. The SDL2_gfx module is also based on the SDL_image module.

Details and Improvements

The improvements made to these modules are as follows:

FindSDL2.cmake

  • Adapt FindSDL.cmake to SDL2 (FindSDL2.cmake).
  • Add cache variables for more flexibility:
    SDL2_PATH, SDL2_NO_DEFAULT_PATH
  • Mark Threads as a required dependency for non-OSX systems.
  • Modernize the FindSDL2.cmake module by creating specific targets:
    • SDL2::Core : Library project should link to SDL2::Core
    • SDL2::Main : Application project should link to SDL2::Main

For more details, please see the embedded documentation in FindSDL2.cmake file.

FindSDL2_<COMPONENT>.cmake

  • Adapt FindSDL_<COMPONENT>.cmake to SDL2_<COMPONENT> (FindSDL2_<COMPONENT>.cmake).
  • Add cache variables for more flexibility:
    SDL2_<COMPONENT>_PATH, SDL2_<COMPONENT>_NO_DEFAULT_PATH
  • Add SDL2 as a required dependency.
  • Modernize the FindSDL2_<COMPONENT>.cmake modules by creating specific targets:
    SDL2::Image, SDL2::TTF, SDL2::Net, SDL2::Mixer and SDL2::GFX.

For more details, please see the embedded documentation in FindSDL2_<COMPONENT>.cmake file.

Usage

In order to use the SDL2 CMake modules, we have to clone this repository in a sud-directory cmake/sdl2 in our project as follows:

cd <PROJECT_DIR>
git clone https://gitlab.com/aminosbh/sdl2-cmake-modules.git cmake/sdl2
rm -rf cmake/sdl2/.git

Or if we are using git for our project, we can add this repository as a submodule as follows:

cd <PROJECT_DIR>
git submodule add https://gitlab.com/aminosbh/sdl2-cmake-modules.git cmake/sdl2
git commit -m "Add SDL2 CMake modules"

Then we should specify the modules path in the main CMakeLists.txt file like the following:

list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/sdl2)

Finally, we can use the SDL2 modules. There is two approaches that can be adopted: A legacy approach and a modern approach. Both of them are supported.

Modern CMake

We can link to the SDL2:: targets like the following example:
This example requires the SDL2, SDL2_image and the SDL2_gfx libraries

# Find SDL2, SDL2_image and SDL2_gfx libraries
find_package(SDL2 REQUIRED)
find_package(SDL2_image REQUIRED)
find_package(SDL2_gfx REQUIRED)

# Link SDL2::Main, SDL2::Image and SDL2::GFX to our project
target_link_libraries(${PROJECT_NAME} SDL2::Main SDL2::Image SDL2::GFX)

Use the appropriate packages for you project.
Please see above, for the whole list of packages
For more details, please see the embedded documentation in modules files

Legacy CMake

We can also specify manually the include directories and libraries to link to:

# Find and link SDL2
find_package(SDL2 REQUIRED)
target_include_directories(${PROJECT_NAME} PRIVATE ${SDL2_INCLUDE_DIRS})
target_link_libraries(${PROJECT_NAME} ${SDL2_LIBRARIES})

# Find and link SDL2_image
find_package(SDL2_image REQUIRED)
target_include_directories(${PROJECT_NAME} PRIVATE ${SDL2_IMAGE_INCLUDE_DIRS})
target_link_libraries(${PROJECT_NAME} ${SDL2_IMAGE_LIBRARIES})

# Find and link SDL2_gfx
find_package(SDL2_gfx REQUIRED)
target_include_directories(${PROJECT_NAME} PRIVATE ${SDL2_GFX_INCLUDE_DIRS})
target_link_libraries(${PROJECT_NAME} ${SDL2_GFX_LIBRARIES})

For more details, please see the embedded documentation in modules files

Special customization variables

Each module have special customization cache variables that can be used to help the modules find the appropriate libraries:

  • SDL2_PATH and SDL2_<COMPONENT>_PATH:
    Can be specified to set the root search path for the SDL2 and SDL2_<COMPONENT>
  • SDL2_NO_DEFAULT_PATH and SDL2_<COMPONENT>_NO_DEFAULT_PATH:
    Disable search SDL2/SDL2_<COMPONENT> library in default path:
    If SDL2[_<COMPONENT>]_PATH is set, defaults to ON
    Else defaults to OFF
  • SDL2_INCLUDE_DIR and SDL2_<COMPONENT>_INCLUDE_DIR:
    Set headers path. (Override)
  • SDL2_LIBRARY and SDL2_<COMPONENT>_LIBRARY:
    Set the library (.dll, .so, .a, etc) path. (Override)
  • SDL2MAIN_LIBRAY:
    Set the SDL2main library (.a) path. (Override)

These variables could be used in case of Windows projects, and when the libraries are not localized in a standard pathes. They can be specified when executing the cmake command or when using the CMake GUI (They are marked as advanced).

cmake command example:

mkdir build
cd build
cmake .. -DSDL2_PATH="/path/to/sdl2"

CMakeLists.txt example:

If we embed, for example, binaries of the SDL2_ttf in our project, we can specify the cache variables values just before calling the find_package command as follows:

set(SDL2_TTF_PATH "/path/to/sdl2_ttf" CACHE BOOL "" FORCE)
find_package(SDL2_ttf REQUIRED)

License

Maintainer: Amine B. Hassouna @aminosbh

The SDL2 CMake modules are based on the SDL (1.2) modules available with the CMake project which is distributed under the OSI-approved BSD 3-Clause License.

The SDL2 CMake modules are also distributed under the OSI-approved BSD 3-Clause License. See accompanying file Copyright.txt.