| Author: Ben Henning <b.henning@digipen.edu> |
| |
| The goal of this project is to provide a lightweight and portable meta-build |
| system for generating build systems for various platforms and architectures, all |
| for the SDL2 library and subsequently dependent executables. |
| |
| Following is a table of contents for the entire README file. |
| |
| [0] OVERVIEW |
| [1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS |
| [2] STRUCTURE |
| [3] SUPPORT ON WINDOWS AND VISUAL STUDIO |
| [4] SUPPORT ON MAC OS X AND XCODE |
| [5] SUPPORT FOR IOS |
| [6] SUPPORT FOR LINUX |
| [7] SUPPORT FOR MINGW |
| [8] SUPPORT FOR CYGWIN |
| [9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS (code samples) |
| |
| [0] OVERVIEW |
| |
| The system is capable of generating projects for many different platforms and |
| architectures. How to generically generate projects is described in the next |
| section. Subsequent sections thereafter describe more specific ways to generate |
| projects and dependencies projects have. |
| |
| All of the projects inherently have things in common, such as depending on the |
| same source tree for header and source files. All projects generated will also |
| have both debug and release configurations available to be built. More |
| information on how to build either will be provided below. |
| |
| To view a list of progress on the project, view the changelog. |
| |
| [1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS |
| |
| To receive help with various premake actions and command-line options, or to |
| view the options available for the current premake environment, run the |
| following command: |
| |
| ./premake4 --file=./path/to/premake4.lua help |
| |
| To construct the project files, run this local command from any command line: |
| |
| .\premake4 --file=.\path\to\premake4.lua --to=.\resultDirectory [opts] [vs2008/vs2010/vs2012] |
| OR |
| ./premake4 --file=./path/to/premake4.lua --to=./resultDirectory [opts] [xcode3/xcode4/gmake] |
| |
| opts may be one of: |
| --mingw |
| --cygwin |
| --ios |
| |
| opts may also include any of the following: |
| --alsa : Force the ALSA dependency on for Linux targets. |
| --dbus : Force the D-Bus dependency on for Linux targets. |
| --directx : Force the DirectX dependency on for Windows, MinGW, and Cygwin targets. |
| --dlopen : Force the DLOpen dependency on for Linux targets. |
| --esd : Force the ESD dependency on for Linux targets. |
| --nas : Force the NAS dependency on for Linux targets. |
| --opengl : Force the OpenGL dependency on for any target. |
| --oss : Force the OSS dependency on for Linux targets. |
| --pulseaudio : Force the PulseAudio dependency on for Linux targets. |
| --x11 : Force the X11 dependency on for Linux targets. |
| |
| All projects have debug and release configurations that may be built. For IDE |
| projects such as Visual Studio and Xcode, there are configurations in the former |
| and schemas in the latter to handle this. |
| |
| For make files, the following command line may be used: |
| make config=debug |
| or: |
| make config=release |
| |
| The make files also have a level of verbosity that will print all compiler and |
| linking commands to the command line. This can be enabled with the following |
| command: |
| make verbose=1 |
| |
| [2] STRUCTURE |
| |
| The structure of the meta-build system is split into three parts: |
| |
| 1. The core system which runs all of the other scripts, generates the premake |
| Lua file that is used to generate the actual build system, and sets up |
| premake to generate it. (premake4.lua) |
| |
| 2. The utility files for performing various convenience operations, ranging |
| from string operations and a file wrapper to custom project definitions and |
| complex dependency checking using CMake-esque functions. There is also a |
| file containing custom dependency functions for checked support. |
| (everything in the util folder) |
| |
| 3. The project definition files, which define each and every project related |
| to SDL2. This includes the SDL2 library itself, along with all of its |
| current tests and iOS Demos. These files also related to dependency handling |
| and help build dependency trees for the various projects. |
| (everything in the projects folder) |
| |
| The premake4.lua file is lightly documented and commented to explain how it |
| interfaces with the other utility files and project files. It is not extensively |
| documented because the actual generation process is not considered to be |
| pertinent to the overall usage of the meta-build system. |
| |
| The utility files have thorough documentation, since they are the foundation for |
| the entire project definition and dependency handling systems. |
| |
| The project definition files are lightly documented, since they are expected to |
| be self-explanatory. Look through each and every project definition file |
| (especially SDL2.lua, testgl2.lua, testshape.lua, testsprite2.lua, and |
| testnative.lua) to gain experience and familiarity with most of the project |
| definition system. |
| |
| The dependency system is very straightforward. As explained in both |
| sdl_projects.lua and sdl_dependency_checkers.lua, a function for checking the |
| actual dependency support is registered by its name and then referenced to in |
| the project definitions (such as for SDL2.lua). These definitions are allowed to |
| do anything necessary to determine whether the appropriate support exists in the |
| current build environment or not. The possibilities for checking can be seen |
| specifically in the function for checking DirectX support and any of the Linux |
| dependency functions using the sdl_check_compile.lua functions. |
| |
| As far as building the projects is concerned, the project definitions are |
| allowed to set configuration key-value pairs which will be translated and placed |
| inside a generated SDL config header file, similar to the one generated by both |
| autotools and CMake. |
| |
| [3] SUPPORT ON WINDOWS AND VISUAL STUDIO |
| |
| Check the Windows README for more information on SDL2 support on Windows and |
| Visual Studio. Current support exists for Visual Studio 2008, 2010, and 2012. |
| |
| [4] SUPPORT ON MAC OS X AND XCODE |
| |
| Check the Mac OS X README for more information on SDL2 support on Mac OS X using |
| Xcode. Current support should exist for Mac OS X 10.6, 10.7, and 10.8 (as |
| tested, but more may be supported). Supported Xcode versions are 3 and 4. It |
| supports building for both i686 and x86_64 architectures, as well as support for |
| universal 32-bit binaries, universal 64-bit binaries, and universal combined |
| binaries. |
| |
| [5] SUPPORT FOR IOS |
| |
| EXPERIMENTAL SUPPORT |
| |
| Check the iOS README for more information on SDL2 support on iOS using Xcode. |
| Current support has been tested on the iOS 6 emulators for iPhone and iPad, |
| using both Xcode 3 and Xcode 4. The iOS project will reference all the Demos |
| the manual project does. |
| |
| [6] SUPPORT FOR LINUX |
| |
| EXPERIMENTAL SUPPORT |
| |
| Check the Linux README for more information on SDL2 support on Linux. Currently, |
| only a subset of the Linux dependencies are supported, and they are supported |
| partially. Linux also builds to a static library instead of a shared library. |
| The tests run well and as expected. |
| |
| [7] SUPPORT FOR MINGW |
| |
| Check the MinGW README for more information on SDL2 support on MinGW. Currently, |
| all of the tests that work using the Visual Studio projects also seem to work |
| with MinGW, minus DirectX support. DirectX is not inherently supported, but can |
| be forcibly turned on if the user knows what they are doing. |
| |
| [8] SUPPORT FOR CYGWIN |
| |
| BROKEN SUPPORT |
| |
| Check the Cygwin README for more information on the progress of supporting SDL2 |
| on Cygwin. |
| |
| [9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS |
| |
| In order to create a new project, simply create a Lua file and place it within |
| the projects directory. The meta-build system will automatically include it. |
| It must contain a SDL_project definition. Projects *must* have source files as |
| well, otherwise they will be ignored by the meta-build system. There are a |
| plethora of examples demonstrating how to defined projects, link them to various |
| dependencies, and to create dependencies. |
| |
| Here is an example that creates a new project named foo, it's a ConsoleApp |
| (which is the default for SDL projects, look at http://industriousone.com/kind |
| for more information). Its language is C and its source directory is "../test" |
| (this path is relative to the location of premake4.lua). It's project location |
| is "tests", which means it will be placed in the ./tests/ folder of whichever |
| destination directory is set while generating the project (for example, |
| ./VisualC/tests). It is including all the files starting with "foo." from the |
| "../test" folder. |
| |
| SDL_project "foo" |
| SDL_kind "ConsoleApp" |
| SDL_language "C" |
| SDL_sourcedir "../test" |
| SDL_projectLocation "tests" |
| SDL_files { "/testrendercopyex.*" } |
| |
| Now, we can extend this project slightly: |
| |
| SDL_project "foo" |
| SDL_kind "ConsoleApp" |
| SDL_notos "ios|cygwin" |
| SDL_language "C" |
| SDL_sourcedir "../test" |
| SDL_projectLocation "tests" |
| SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" } |
| SDL_files { "/foo.*" } |
| SDL_copy { "icon.bmp", "sample.bmp" } |
| |
| We now specified that this application will not work on iOS or Cygwin targets, |
| so it will be discluded when generating projects for those platforms. We have |
| also specified that this project depends on 'SDL2main', 'SDL2test', and 'SDL2', |
| which are other projects that are already defined. We can set the dependency |
| to any projects the SDL2 meta-build system is aware of. We also have an |
| interesting SDL_copy directive, which will automatically copy the files |
| "icon.bmp" and "sample.bmp" from "<sdl_root>/test" to the directory of foo's |
| executable when it's built. |
| |
| Let's take a look at another example: |
| |
| SDL_project "testgl2" |
| SDL_kind "ConsoleApp" |
| SDL_notos "ios|cygwin" |
| SDL_language "C" |
| SDL_sourcedir "../test" |
| SDL_projectLocation "tests" |
| SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" } |
| SDL_defines { "HAVE_OPENGL" } |
| SDL_dependency "OpenGL" |
| -- opengl is platform independent |
| SDL_depfunc "OpenGL" |
| SDL_files { "/testgl2.*" } |
| |
| This is a copy of the testgl2.lua file. Most of this is already familiar, but |
| there are a few new things to point out. We can set preprocessor definitions by |
| using the 'SDL_defines' directive. We can also create a dependency for the |
| project on some varied criteria. For example, testgl2 is obviously dependent on |
| the presence of the OpenGL library. So, the only way it will include the |
| "testgl2.*" (testgl2.c/testgl2.h) files is if the dependency function "OpenGL" |
| returns information regarding the whereabouts of the OpenGL library on the |
| current system. This function is registered in sdl_dependency_checkers.lua: |
| |
| function openGLDep() |
| print("Checking OpenGL dependencies...") |
| ... |
| return { found = foundLib, libDirs = { }, libs = { libname } } |
| end |
| ... |
| SDL_registerDependencyChecker("OpenGL", openGLDep) |
| |
| This function is called when it's time to decide whether testgl2 should be |
| generated or not. openGLDep can use any and all functions to decide whether |
| OpenGL is supported. |
| |
| Dependencies and projects can become much more sophisticate, if necessary. Take |
| the following example from the SDL2.lua project definition: |
| |
| -- DirectX dependency |
| SDL_dependency "directx" |
| SDL_os "windows|mingw" |
| SDL_depfunc "DirectX" |
| SDL_config |
| { |
| ["SDL_AUDIO_DRIVER_DSOUND"] = 1, |
| ["SDL_AUDIO_DRIVER_XAUDIO2"] = 1, |
| ["SDL_JOYSTICK_DINPUT"] = 1, |
| ["SDL_HAPTIC_DINPUT"] = 1, |
| ["SDL_VIDEO_RENDER_D3D"] = 1 |
| } |
| SDL_paths |
| { |
| "/audio/directsound/", |
| "/audio/xaudio2/", |
| "/render/direct3d/", |
| -- these two depend on Xinput |
| "/haptic/windows/", |
| "/joystick/windows/", |
| } |
| |
| This dependency is, as expected, for DirectX. One thing to note here is even |
| dependencies can be dependent on an operating system. This dependency will not |
| even be resolved if SDL2 is being generated on, say, Linux or Mac OS X. Two new |
| things shown here are 'SDL_config' and 'SDL_paths' directives. SDL_config allows |
| you to set preprocessor definitions that will be pasted into |
| SDL_config_premake.h (which acts as a replacement to SDL_config.h when building |
| the project). This allows for significant flexibility (look around SDL2.lua's |
| dependencies, especially for Linux). SDL_paths works like SDL_files, except it |
| includes all .c, .h, and .m files within that directory. The directory is still |
| relative to the source directory of the project (in this case, <sdl_root>/src). |
| |
| Finally, dependency checking can be done in a huge variety of ways, ranging |
| from simply checking for an environmental variable to scanning directories on |
| Windows. Even more flexibly, the build environment itself can be checked using |
| functions similar to those provided in CMake to check if a function compiles, |
| library exists, etc. The following example comes from |
| sdl_dependency_checkers.lua and is used by the Linux dependency in the SDL2 |
| project to determine whether the OSS sound system is supported: |
| |
| function ossDep() |
| print("Checking for OSS support...") |
| if not check_cxx_source_compiles([[ |
| #include <sys/soundcard.h> |
| int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]]) |
| and not check_cxx_source_compiles([[ |
| #include <soundcard.h> |
| int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]]) then |
| print("Warning: OSS unsupported!") |
| return { found = false } |
| end |
| return { found = true } |
| end |
| |
| Notice how it uses 'check_cxx_source_compiles'. There are even more functions |
| than this to check and, rather than going in detail with them here, I encourage |
| you to look at the documented functions within ./util/sdl_check_compile.lua. |
| |
| In order to support new platforms, start with the minimal configuration template |
| provided and work off of the initial SDL2 project. You may add additional |
| dependencies to define other source files specific to that platform (see how |
| it's done with Windows and Mac OS X), or you can add special dependencies that |
| rely on dependency functions you may implement yourself (see DirectX and |
| OpenGL). Dependencies can use the 'SDL_config' directive to specify special |
| values that can be pasted into the resulting configuration header file upon |
| generation. |
| |
| For more detailed information about the functions supported and how they work, |
| look at all of the Lua files in the util directory, as well as any of the |
| example projects in the projects directory to demonstrate how many of these |
| functions are used. The information above is only a quick subset of the |
| capabilities of the meta-build system. |