icculus@7925  1 Author: Ben Henning  icculus@7925  2 icculus@7925  3 The goal of this project is to provide a lightweight and portable meta-build  icculus@7925  4 system for generating build systems for various platforms and architectures, all  icculus@7925  5 for the SDL2 library and subsequently dependent executables.  icculus@7925  6 icculus@7925  7 Following is a table of contents for the entire README file.  icculus@7925  8 icculus@7925  9 [0] OVERVIEW  icculus@7925  10 [1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS  icculus@7925  11 [2] STRUCTURE  icculus@7925  12 [3] SUPPORT ON WINDOWS AND VISUAL STUDIO  icculus@7925  13 [4] SUPPORT ON MAC OS X AND XCODE  icculus@7925  14 [5] SUPPORT FOR IOS  icculus@7925  15 [6] SUPPORT FOR LINUX  icculus@7925  16 [7] SUPPORT FOR MINGW  icculus@7925  17 [8] SUPPORT FOR CYGWIN  icculus@7925  18 [9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS (code samples)  icculus@7925  19 icculus@7925  20 [0] OVERVIEW  icculus@7925  21 icculus@7925  22 The system is capable of generating projects for many different platforms and  icculus@7925  23 architectures. How to generically generate projects is described in the next  icculus@7925  24 section. Subsequent sections thereafter describe more specific ways to generate  icculus@7925  25 projects and dependencies projects have.  icculus@7925  26 icculus@7925  27 All of the projects inherently have things in common, such as depending on the  icculus@7925  28 same source tree for header and source files. All projects generated will also  icculus@7925  29 have both debug and release configurations available to be built. More  icculus@7925  30 information on how to build either will be provided below.  icculus@7925  31 icculus@7925  32 To view a list of progress on the project, view the changelog.  icculus@7925  33 icculus@7925  34 [1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS  icculus@7925  35 icculus@7925  36 To receive help with various premake actions and command-line options, or to  icculus@7925  37 view the options available for the current premake environment, run the  icculus@7925  38 following command:  icculus@7925  39 icculus@7925  40  ./premake4 --file=./path/to/premake4.lua help  icculus@7925  41 icculus@7925  42 To construct the project files, run this local command from any command line:  icculus@7925  43 icculus@7925  44  .\premake4 --file=.\path\to\premake4.lua --to=.\resultDirectory [opts] [vs2008/vs2010/vs2012]  icculus@7925  45 OR  icculus@7925  46  ./premake4 --file=./path/to/premake4.lua --to=./resultDirectory [opts] [xcode3/xcode4/gmake]  icculus@7925  47 icculus@7925  48 opts may be one of:  icculus@7925  49  --mingw  icculus@7925  50  --cygwin  icculus@7925  51  --ios  icculus@7925  52 icculus@7925  53 opts may also include any of the following:  icculus@7925  54  --alsa : Force the ALSA dependency on for Linux targets.  icculus@7925  55  --dbus : Force the D-Bus dependency on for Linux targets.  icculus@7925  56  --directx : Force the DirectX dependency on for Windows, MinGW, and Cygwin targets.  icculus@7925  57  --dlopen : Force the DLOpen dependency on for Linux targets.  icculus@7925  58  --esd : Force the ESD dependency on for Linux targets.  icculus@7925  59  --nas : Force the NAS dependency on for Linux targets.  icculus@7925  60  --opengl : Force the OpenGL dependency on for any target.  icculus@7925  61  --oss : Force the OSS dependency on for Linux targets.  icculus@7925  62  --pulseaudio : Force the PulseAudio dependency on for Linux targets.  icculus@7925  63  --x11 : Force the X11 dependency on for Linux targets.  icculus@7925  64 icculus@7925  65 All projects have debug and release configurations that may be built. For IDE  icculus@7925  66 projects such as Visual Studio and Xcode, there are configurations in the former  icculus@7925  67 and schemas in the latter to handle this.  icculus@7925  68 icculus@7925  69 For make files, the following command line may be used:  icculus@7925  70  make config=debug  icculus@7925  71 or:  icculus@7925  72  make config=release  icculus@7925  73 icculus@7925  74 The make files also have a level of verbosity that will print all compiler and  icculus@7925  75 linking commands to the command line. This can be enabled with the following  icculus@7925  76 command:  icculus@7925  77  make verbose=1  icculus@7925  78 icculus@7925  79 [2] STRUCTURE  icculus@7925  80 icculus@7925  81 The structure of the meta-build system is split into three parts:  icculus@7925  82 icculus@7925  83  1. The core system which runs all of the other scripts, generates the premake  icculus@7925  84  Lua file that is used to generate the actual build system, and sets up  icculus@7925  85  premake to generate it. (premake4.lua)  icculus@7925  86 icculus@7925  87  2. The utility files for performing various convenience operations, ranging  icculus@7925  88  from string operations and a file wrapper to custom project definitions and  icculus@7925  89  complex dependency checking using CMake-esque functions. There is also a  icculus@7925  90  file containing custom dependency functions for checked support.  icculus@7925  91  (everything in the util folder)  icculus@7925  92 icculus@7925  93  3. The project definition files, which define each and every project related  icculus@7925  94  to SDL2. This includes the SDL2 library itself, along with all of its  icculus@7925  95  current tests and iOS Demos. These files also related to dependency handling  icculus@7925  96  and help build dependency trees for the various projects.  icculus@7925  97  (everything in the projects folder)  icculus@7925  98 icculus@7925  99 The premake4.lua file is lightly documented and commented to explain how it  icculus@7925  100 interfaces with the other utility files and project files. It is not extensively  icculus@7925  101 documented because the actual generation process is not considered to be  icculus@7925  102 pertinent to the overall usage of the meta-build system.  icculus@7925  103 icculus@7925  104 The utility files have thorough documentation, since they are the foundation for  icculus@7925  105 the entire project definition and dependency handling systems.  icculus@7925  106 icculus@7925  107 The project definition files are lightly documented, since they are expected to  icculus@7925  108 be self-explanatory. Look through each and every project definition file  icculus@7925  109 (especially SDL2.lua, testgl2.lua, testshape.lua, testsprite2.lua, and  icculus@7925  110 testnative.lua) to gain experience and familiarity with most of the project  icculus@7925  111 definition system.  icculus@7925  112 icculus@7925  113 The dependency system is very straightforward. As explained in both  icculus@7925  114 sdl_projects.lua and sdl_dependency_checkers.lua, a function for checking the  icculus@7925  115 actual dependency support is registered by its name and then referenced to in  icculus@7925  116 the project definitions (such as for SDL2.lua). These definitions are allowed to  icculus@7925  117 do anything necessary to determine whether the appropriate support exists in the  icculus@7925  118 current build environment or not. The possibilities for checking can be seen  icculus@7925  119 specifically in the function for checking DirectX support and any of the Linux  icculus@7925  120 dependency functions using the sdl_check_compile.lua functions.  icculus@7925  121 icculus@7925  122 As far as building the projects is concerned, the project definitions are  icculus@7925  123 allowed to set configuration key-value pairs which will be translated and placed  icculus@7925  124 inside a generated SDL config header file, similar to the one generated by both  icculus@7925  125 autotools and CMake.  icculus@7925  126 icculus@7925  127 [3] SUPPORT ON WINDOWS AND VISUAL STUDIO  icculus@7925  128 icculus@7925  129 Check the Windows README for more information on SDL2 support on Windows and  icculus@7925  130 Visual Studio. Current support exists for Visual Studio 2008, 2010, and 2012.  icculus@7925  131 icculus@7925  132 [4] SUPPORT ON MAC OS X AND XCODE  icculus@7925  133 icculus@7925  134 Check the Mac OS X README for more information on SDL2 support on Mac OS X using  icculus@7925  135 Xcode. Current support should exist for Mac OS X 10.6, 10.7, and 10.8 (as  icculus@7925  136 tested, but more may be supported). Supported Xcode versions are 3 and 4. It  icculus@7925  137 supports building for both i686 and x86_64 architectures, as well as support for  icculus@7925  138 universal 32-bit binaries, universal 64-bit binaries, and universal combined  icculus@7925  139 binaries.  icculus@7925  140 icculus@7925  141 [5] SUPPORT FOR IOS  icculus@7925  142 icculus@7925  143 EXPERIMENTAL SUPPORT  icculus@7925  144 icculus@7925  145 Check the iOS README for more information on SDL2 support on iOS using Xcode.  icculus@7925  146 Current support has been tested on the iOS 6 emulators for iPhone and iPad,  icculus@7925  147 using both Xcode 3 and Xcode 4. The iOS project will reference all the Demos  icculus@7925  148 the manual project does.  icculus@7925  149 icculus@7925  150 [6] SUPPORT FOR LINUX  icculus@7925  151 icculus@7925  152 EXPERIMENTAL SUPPORT  icculus@7925  153 icculus@7925  154 Check the Linux README for more information on SDL2 support on Linux. Currently,  icculus@7925  155 only a subset of the Linux dependencies are supported, and they are supported  icculus@7925  156 partially. Linux also builds to a static library instead of a shared library.  icculus@7925  157 The tests run well and as expected.  icculus@7925  158 icculus@7925  159 [7] SUPPORT FOR MINGW  icculus@7925  160 icculus@7925  161 Check the MinGW README for more information on SDL2 support on MinGW. Currently,  icculus@7925  162 all of the tests that work using the Visual Studio projects also seem to work  icculus@7925  163 with MinGW, minus DirectX support. DirectX is not inherently supported, but can  icculus@7925  164 be forcibly turned on if the user knows what they are doing.  icculus@7925  165 icculus@7925  166 [8] SUPPORT FOR CYGWIN  icculus@7925  167 icculus@7925  168 BROKEN SUPPORT  icculus@7925  169 icculus@7925  170 Check the Cygwin README for more information on the progress of supporting SDL2  icculus@7925  171 on Cygwin.  icculus@7925  172 icculus@7925  173 [9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS  icculus@7925  174 icculus@7925  175 In order to create a new project, simply create a Lua file and place it within  icculus@7925  176 the projects directory. The meta-build system will automatically include it.  icculus@7925  177 It must contain a SDL_project definition. Projects *must* have source files as  icculus@7925  178 well, otherwise they will be ignored by the meta-build system. There are a  icculus@7925  179 plethora of examples demonstrating how to defined projects, link them to various  icculus@7925  180 dependencies, and to create dependencies.  icculus@7925  181 icculus@7925  182 Here is an example that creates a new project named foo, it's a ConsoleApp  icculus@7925  183 (which is the default for SDL projects, look at http://industriousone.com/kind  icculus@7925  184 for more information). Its language is C and its source directory is "../test"  icculus@7925  185 (this path is relative to the location of premake4.lua). It's project location  icculus@7925  186 is "tests", which means it will be placed in the ./tests/ folder of whichever  icculus@7925  187 destination directory is set while generating the project (for example,  icculus@7925  188 ./VisualC/tests). It is including all the files starting with "foo." from the  icculus@7925  189 "../test" folder.  icculus@7925  190 icculus@7925  191  SDL_project "foo"  icculus@7925  192  SDL_kind "ConsoleApp"  icculus@7925  193  SDL_language "C"  icculus@7925  194  SDL_sourcedir "../test"  icculus@7925  195  SDL_projectLocation "tests"  icculus@7925  196  SDL_files { "/testrendercopyex.*" }  icculus@7925  197 icculus@7925  198 Now, we can extend this project slightly:  icculus@7925  199 icculus@7925  200  SDL_project "foo"  icculus@7925  201  SDL_kind "ConsoleApp"  icculus@7925  202  SDL_notos "ios|cygwin"  icculus@7925  203  SDL_language "C"  icculus@7925  204  SDL_sourcedir "../test"  icculus@7925  205  SDL_projectLocation "tests"  icculus@7925  206  SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" }  icculus@7925  207  SDL_files { "/foo.*" }  icculus@7925  208  SDL_copy { "icon.bmp", "sample.bmp" }  icculus@7925  209 icculus@7925  210 We now specified that this application will not work on iOS or Cygwin targets,  icculus@7925  211 so it will be discluded when generating projects for those platforms. We have  icculus@7925  212 also specified that this project depends on 'SDL2main', 'SDL2test', and 'SDL2',  icculus@7925  213 which are other projects that are already defined. We can set the dependency  icculus@7925  214 to any projects the SDL2 meta-build system is aware of. We also have an  icculus@7925  215 interesting SDL_copy directive, which will automatically copy the files  icculus@7925  216 "icon.bmp" and "sample.bmp" from "/test" to the directory of foo's  icculus@7925  217 executable when it's built.  icculus@7925  218 icculus@7925  219 Let's take a look at another example:  icculus@7925  220 icculus@7925  221  SDL_project "testgl2"  icculus@7925  222  SDL_kind "ConsoleApp"  icculus@7925  223  SDL_notos "ios|cygwin"  icculus@7925  224  SDL_language "C"  icculus@7925  225  SDL_sourcedir "../test"  icculus@7925  226  SDL_projectLocation "tests"  icculus@7925  227  SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" }  icculus@7925  228  SDL_defines { "HAVE_OPENGL" }  icculus@7925  229  SDL_dependency "OpenGL"  icculus@7925  230  -- opengl is platform independent  icculus@7925  231  SDL_depfunc "OpenGL"  icculus@7925  232  SDL_files { "/testgl2.*" }  icculus@7925  233 icculus@7925  234 This is a copy of the testgl2.lua file. Most of this is already familiar, but  icculus@7925  235 there are a few new things to point out. We can set preprocessor definitions by  icculus@7925  236 using the 'SDL_defines' directive. We can also create a dependency for the  icculus@7925  237 project on some varied criteria. For example, testgl2 is obviously dependent on  icculus@7925  238 the presence of the OpenGL library. So, the only way it will include the  icculus@7925  239 "testgl2.*" (testgl2.c/testgl2.h) files is if the dependency function "OpenGL"  icculus@7925  240 returns information regarding the whereabouts of the OpenGL library on the  icculus@7925  241 current system. This function is registered in sdl_dependency_checkers.lua:  icculus@7925  242 icculus@7925  243  function openGLDep()  icculus@7925  244  print("Checking OpenGL dependencies...")  icculus@7925  245  ...  icculus@7925  246  return { found = foundLib, libDirs = { }, libs = { libname } }  icculus@7925  247  end  icculus@7925  248  ...  icculus@7925  249  SDL_registerDependencyChecker("OpenGL", openGLDep)  icculus@7925  250 icculus@7925  251 This function is called when it's time to decide whether testgl2 should be  icculus@7925  252 generated or not. openGLDep can use any and all functions to decide whether  icculus@7925  253 OpenGL is supported.  icculus@7925  254 icculus@7925  255 Dependencies and projects can become much more sophisticate, if necessary. Take  icculus@7925  256 the following example from the SDL2.lua project definition:  icculus@7925  257 icculus@7925  258  -- DirectX dependency  icculus@7925  259  SDL_dependency "directx"  icculus@7925  260  SDL_os "windows|mingw"  icculus@7925  261  SDL_depfunc "DirectX"  icculus@7925  262  SDL_config  icculus@7925  263  {  icculus@7925  264  ["SDL_AUDIO_DRIVER_DSOUND"] = 1,  icculus@7925  265  ["SDL_AUDIO_DRIVER_XAUDIO2"] = 1,  icculus@7925  266  ["SDL_JOYSTICK_DINPUT"] = 1,  icculus@7925  267  ["SDL_HAPTIC_DINPUT"] = 1,  icculus@7925  268  ["SDL_VIDEO_RENDER_D3D"] = 1  icculus@7925  269  }  icculus@7925  270  SDL_paths  icculus@7925  271  {  icculus@7925  272  "/audio/directsound/",  icculus@7925  273  "/audio/xaudio2/",  icculus@7925  274  "/render/direct3d/",  icculus@7925  275  -- these two depend on Xinput  icculus@7925  276  "/haptic/windows/",  icculus@7925  277  "/joystick/windows/",  icculus@7925  278  }  icculus@7925  279 icculus@7925  280 This dependency is, as expected, for DirectX. One thing to note here is even  icculus@7925  281 dependencies can be dependent on an operating system. This dependency will not  icculus@7925  282 even be resolved if SDL2 is being generated on, say, Linux or Mac OS X. Two new  icculus@7925  283 things shown here are 'SDL_config' and 'SDL_paths' directives. SDL_config allows  icculus@7925  284 you to set preprocessor definitions that will be pasted into  icculus@7925  285 SDL_config_premake.h (which acts as a replacement to SDL_config.h when building  icculus@7925  286 the project). This allows for significant flexibility (look around SDL2.lua's  icculus@7925  287 dependencies, especially for Linux). SDL_paths works like SDL_files, except it  icculus@7925  288 includes all .c, .h, and .m files within that directory. The directory is still  icculus@7925  289 relative to the source directory of the project (in this case, /src).  icculus@7925  290 icculus@7925  291 Finally, dependency checking can be done in a huge variety of ways, ranging  icculus@7925  292 from simply checking for an environmental variable to scanning directories on  icculus@7925  293 Windows. Even more flexibly, the build environment itself can be checked using  icculus@7925  294 functions similar to those provided in CMake to check if a function compiles,  icculus@7925  295 library exists, etc. The following example comes from  icculus@7925  296 sdl_dependency_checkers.lua and is used by the Linux dependency in the SDL2  icculus@7925  297 project to determine whether the OSS sound system is supported:  icculus@7925  298 icculus@7925  299  function ossDep()  icculus@7925  300  print("Checking for OSS support...")  icculus@7925  301  if not check_cxx_source_compiles([[  icculus@7925  302  #include  icculus@7925  303  int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]])  icculus@7925  304  and not check_cxx_source_compiles([[  icculus@7925  305  #include  icculus@7925  306  int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]]) then  icculus@7925  307  print("Warning: OSS unsupported!")  icculus@7925  308  return { found = false }  icculus@7925  309  end  icculus@7925  310  return { found = true }  icculus@7925  311  end  icculus@7925  312 icculus@7925  313 Notice how it uses 'check_cxx_source_compiles'. There are even more functions  icculus@7925  314 than this to check and, rather than going in detail with them here, I encourage  icculus@7925  315 you to look at the documented functions within ./util/sdl_check_compile.lua.  icculus@7925  316 icculus@7925  317 In order to support new platforms, start with the minimal configuration template  icculus@7925  318 provided and work off of the initial SDL2 project. You may add additional  icculus@7925  319 dependencies to define other source files specific to that platform (see how  icculus@7925  320 it's done with Windows and Mac OS X), or you can add special dependencies that  icculus@7925  321 rely on dependency functions you may implement yourself (see DirectX and  icculus@7925  322 OpenGL). Dependencies can use the 'SDL_config' directive to specify special  icculus@7925  323 values that can be pasted into the resulting configuration header file upon  icculus@7925  324 generation.  icculus@7925  325 icculus@7925  326 For more detailed information about the functions supported and how they work,  icculus@7925  327 look at all of the Lua files in the util directory, as well as any of the  icculus@7925  328 example projects in the projects directory to demonstrate how many of these  icculus@7925  329 functions are used. The information above is only a quick subset of the  icculus@7925  330 capabilities of the meta-build system.