author Ryan C. Gordon Sun, 03 Jan 2016 20:52:44 -0500 changeset 10004 8f2f519d1e61 parent 7925 f090a47eb7f7 permissions -rwxr-xr-x
CMake: Don't make a libSDL2.so symlink on Mac OS X (do .dylib instead).
     1 Author: Ben Henning <b.henning@digipen.edu>

     2

     3 The goal of this project is to provide a lightweight and portable meta-build

     4 system for generating build systems for various platforms and architectures, all

     5 for the SDL2 library and subsequently dependent executables.

     6

     7 Following is a table of contents for the entire README file.

     8

     9 [0] OVERVIEW

    10 [1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS

    11 [2] STRUCTURE

    12 [3] SUPPORT ON WINDOWS AND VISUAL STUDIO

    13 [4] SUPPORT ON MAC OS X AND XCODE

    14 [5] SUPPORT FOR IOS

    15 [6] SUPPORT FOR LINUX

    16 [7] SUPPORT FOR MINGW

    17 [8] SUPPORT FOR CYGWIN

    18 [9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS (code samples)

    19

    20 [0] OVERVIEW

    21

    22 The system is capable of generating projects for many different platforms and

    23 architectures. How to generically generate projects is described in the next

    24 section. Subsequent sections thereafter describe more specific ways to generate

    25 projects and dependencies projects have.

    26

    27 All of the projects inherently have things in common, such as depending on the

    28 same source tree for header and source files. All projects generated will also

    29 have both debug and release configurations available to be built. More

    30 information on how to build either will be provided below.

    31

    32 To view a list of progress on the project, view the changelog.

    33

    34 [1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS

    35

    36 To receive help with various premake actions and command-line options, or to

    37 view the options available for the current premake environment, run the

    38 following command:

    39

    40     ./premake4 --file=./path/to/premake4.lua help

    41

    42 To construct the project files, run this local command from any command line:

    43

    44     .\premake4 --file=.\path\to\premake4.lua --to=.\resultDirectory [opts] [vs2008/vs2010/vs2012]

    45 OR

    46     ./premake4 --file=./path/to/premake4.lua --to=./resultDirectory [opts] [xcode3/xcode4/gmake]

    47

    48 opts may be one of:

    49   --mingw

    50   --cygwin

    51   --ios

    52

    53 opts may also include any of the following:

    54   --alsa        :  Force the ALSA dependency on for Linux targets.

    55   --dbus        :  Force the D-Bus dependency on for Linux targets.

    56   --directx     :  Force the DirectX dependency on for Windows, MinGW, and Cygwin targets.

    57   --dlopen      :  Force the DLOpen dependency on for Linux targets.

    58   --esd         :  Force the ESD dependency on for Linux targets.

    59   --nas         :  Force the NAS dependency on for Linux targets.

    60   --opengl      :  Force the OpenGL dependency on for any target.

    61   --oss         :  Force the OSS dependency on for Linux targets.

    62   --pulseaudio  :  Force the PulseAudio dependency on for Linux targets.

    63   --x11         :  Force the X11 dependency on for Linux targets.

    64

    65 All projects have debug and release configurations that may be built. For IDE

    66 projects such as Visual Studio and Xcode, there are configurations in the former

    67 and schemas in the latter to handle this.

    68

    69 For make files, the following command line may be used:

    70     make config=debug

    71 or:

    72     make config=release

    73

    74 The make files also have a level of verbosity that will print all compiler and

    75 linking commands to the command line. This can be enabled with the following

    76 command:

    77     make verbose=1

    78

    79 [2] STRUCTURE

    80

    81 The structure of the meta-build system is split into three parts:

    82

    83   1. The core system which runs all of the other scripts, generates the premake

    84     Lua file that is used to generate the actual build system, and sets up

    85     premake to generate it. (premake4.lua)

    86

    87   2. The utility files for performing various convenience operations, ranging

    88     from string operations and a file wrapper to custom project definitions and

    89     complex dependency checking using CMake-esque functions. There is also a

    90     file containing custom dependency functions for checked support.

    91     (everything in the util folder)

    92

    93   3. The project definition files, which define each and every project related

    94     to SDL2. This includes the SDL2 library itself, along with all of its

    95     current tests and iOS Demos. These files also related to dependency handling

    96     and help build dependency trees for the various projects.

    97     (everything in the projects folder)

    98

    99 The premake4.lua file is lightly documented and commented to explain how it

   100 interfaces with the other utility files and project files. It is not extensively

   101 documented because the actual generation process is not considered to be

   102 pertinent to the overall usage of the meta-build system.

   103

   104 The utility files have thorough documentation, since they are the foundation for

   105 the entire project definition and dependency handling systems.

   106

   107 The project definition files are lightly documented, since they are expected to

   108 be self-explanatory. Look through each and every project definition file

   109 (especially SDL2.lua, testgl2.lua, testshape.lua, testsprite2.lua, and

   110 testnative.lua) to gain experience and familiarity with most of the project

   111 definition system.

   112

   113 The dependency system is very straightforward. As explained in both

   114 sdl_projects.lua and sdl_dependency_checkers.lua, a function for checking the

   115 actual dependency support is registered by its name and then referenced to in

   116 the project definitions (such as for SDL2.lua). These definitions are allowed to

   117 do anything necessary to determine whether the appropriate support exists in the

   118 current build environment or not. The possibilities for checking can be seen

   119 specifically in the function for checking DirectX support and any of the Linux

   120 dependency functions using the sdl_check_compile.lua functions.

   121

   122 As far as building the projects is concerned, the project definitions are

   123 allowed to set configuration key-value pairs which will be translated and placed

   124 inside a generated SDL config header file, similar to the one generated by both

   125 autotools and CMake.

   126

   127 [3] SUPPORT ON WINDOWS AND VISUAL STUDIO

   128

   129 Check the Windows README for more information on SDL2 support on Windows and

   130 Visual Studio. Current support exists for Visual Studio 2008, 2010, and 2012.

   131

   132 [4] SUPPORT ON MAC OS X AND XCODE

   133

   134 Check the Mac OS X README for more information on SDL2 support on Mac OS X using

   135 Xcode. Current support should exist for Mac OS X 10.6, 10.7, and 10.8 (as

   136 tested, but more may be supported). Supported Xcode versions are 3 and 4. It

   137 supports building for both i686 and x86_64 architectures, as well as support for

   138 universal 32-bit binaries, universal 64-bit binaries, and universal combined

   139 binaries.

   140

   141 [5] SUPPORT FOR IOS

   142

   143 EXPERIMENTAL SUPPORT

   144

   145 Check the iOS README for more information on SDL2 support on iOS using Xcode.

   146 Current support has been tested on the iOS 6 emulators for iPhone and iPad,

   147 using both Xcode 3 and Xcode 4. The iOS project will reference all the Demos

   148 the manual project does.

   149

   150 [6] SUPPORT FOR LINUX

   151

   152 EXPERIMENTAL SUPPORT

   153

   154 Check the Linux README for more information on SDL2 support on Linux. Currently,

   155 only a subset of the Linux dependencies are supported, and they are supported

   156 partially. Linux also builds to a static library instead of a shared library.

   157 The tests run well and as expected.

   158

   159 [7] SUPPORT FOR MINGW

   160

   161 Check the MinGW README for more information on SDL2 support on MinGW. Currently,

   162 all of the tests that work using the Visual Studio projects also seem to work

   163 with MinGW, minus DirectX support. DirectX is not inherently supported, but can

   164 be forcibly turned on if the user knows what they are doing.

   165

   166 [8] SUPPORT FOR CYGWIN

   167

   168 BROKEN SUPPORT

   169

   170 Check the Cygwin README for more information on the progress of supporting SDL2

   171 on Cygwin.

   172

   173 [9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS

   174

   175 In order to create a new project, simply create a Lua file and place it within

   176 the projects directory. The meta-build system will automatically include it.

   177 It must contain a SDL_project definition. Projects *must* have source files as

   178 well, otherwise they will be ignored by the meta-build system. There are a

   179 plethora of examples demonstrating how to defined projects, link them to various

   180 dependencies, and to create dependencies.

   181

   182 Here is an example that creates a new project named foo, it's a ConsoleApp

   183 (which is the default for SDL projects, look at http://industriousone.com/kind

   184 for more information). Its language is C and its source directory is "../test"

   185 (this path is relative to the location of premake4.lua). It's project location

   186 is "tests", which means it will be placed in the ./tests/ folder of whichever

   187 destination directory is set while generating the project (for example,

   188 ./VisualC/tests). It is including all the files starting with "foo." from the

   189 "../test" folder.

   190

   191     SDL_project "foo"

   192     	SDL_kind "ConsoleApp"

   193     	SDL_language "C"

   194     	SDL_sourcedir "../test"

   195     	SDL_projectLocation "tests"

   196     	SDL_files { "/testrendercopyex.*" }

   197

   198 Now, we can extend this project slightly:

   199

   200     SDL_project "foo"

   201     	SDL_kind "ConsoleApp"

   202     	SDL_notos "ios|cygwin"

   203     	SDL_language "C"

   204     	SDL_sourcedir "../test"

   205     	SDL_projectLocation "tests"

   206     	SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" }

   207     	SDL_files { "/foo.*" }

   208     	SDL_copy { "icon.bmp", "sample.bmp" }

   209

   210 We now specified that this application will not work on iOS or Cygwin targets,

   211 so it will be discluded when generating projects for those platforms. We have

   212 also specified that this project depends on 'SDL2main', 'SDL2test', and 'SDL2',

   213 which are other projects that are already defined. We can set the dependency

   214 to any projects the SDL2 meta-build system is aware of. We also have an

   215 interesting SDL_copy directive, which will automatically copy the files

   216 "icon.bmp" and "sample.bmp" from "<sdl_root>/test" to the directory of foo's

   217 executable when it's built.

   218

   219 Let's take a look at another example:

   220

   221     SDL_project "testgl2"

   222     	SDL_kind "ConsoleApp"

   223     	SDL_notos "ios|cygwin"

   224     	SDL_language "C"

   225     	SDL_sourcedir "../test"

   226     	SDL_projectLocation "tests"

   227     	SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" }

   228     	SDL_defines { "HAVE_OPENGL" }

   229     	SDL_dependency "OpenGL"

   230     		-- opengl is platform independent

   231     		SDL_depfunc "OpenGL"

   232     		SDL_files { "/testgl2.*" }

   233

   234 This is a copy of the testgl2.lua file. Most of this is already familiar, but

   235 there are a few new things to point out. We can set preprocessor definitions by

   236 using the 'SDL_defines' directive. We can also create a dependency for the

   237 project on some varied criteria. For example, testgl2 is obviously dependent on

   238 the presence of the OpenGL library. So, the only way it will include the

   239 "testgl2.*" (testgl2.c/testgl2.h) files is if the dependency function "OpenGL"

   240 returns information regarding the whereabouts of the OpenGL library on the

   241 current system. This function is registered in sdl_dependency_checkers.lua:

   242

   243     function openGLDep()

   244     	print("Checking OpenGL dependencies...")

   245     	...

   246     	return { found = foundLib, libDirs = { }, libs = { libname } }

   247     end

   248     ...

   249     SDL_registerDependencyChecker("OpenGL", openGLDep)

   250

   251 This function is called when it's time to decide whether testgl2 should be

   252 generated or not. openGLDep can use any and all functions to decide whether

   253 OpenGL is supported.

   254

   255 Dependencies and projects can become much more sophisticate, if necessary. Take

   256 the following example from the SDL2.lua project definition:

   257

   258     -- DirectX dependency

   259     SDL_dependency "directx"

   260     	SDL_os "windows|mingw"

   261     	SDL_depfunc "DirectX"

   262     	SDL_config

   263     	{

   264     		["SDL_AUDIO_DRIVER_DSOUND"] = 1,

   265     		["SDL_AUDIO_DRIVER_XAUDIO2"] = 1,

   266     		["SDL_JOYSTICK_DINPUT"] = 1,

   267     		["SDL_HAPTIC_DINPUT"] = 1,

   268     		["SDL_VIDEO_RENDER_D3D"] = 1

   269     	}

   270     	SDL_paths

   271     	{

   272     		"/audio/directsound/",

   273     		"/audio/xaudio2/",

   274     		"/render/direct3d/",

   275     		-- these two depend on Xinput

   276     		"/haptic/windows/",

   277     		"/joystick/windows/",

   278     	}

   279

   280 This dependency is, as expected, for DirectX. One thing to note here is even

   281 dependencies can be dependent on an operating system. This dependency will not

   282 even be resolved if SDL2 is being generated on, say, Linux or Mac OS X. Two new

   283 things shown here are 'SDL_config' and 'SDL_paths' directives. SDL_config allows

   284 you to set preprocessor definitions that will be pasted into

   285 SDL_config_premake.h (which acts as a replacement to SDL_config.h when building

   286 the project). This allows for significant flexibility (look around SDL2.lua's

   287 dependencies, especially for Linux). SDL_paths works like SDL_files, except it

   288 includes all .c, .h, and .m files within that directory. The directory is still

   289 relative to the source directory of the project (in this case, <sdl_root>/src).

   290

   291 Finally, dependency checking can be done in a huge variety of ways, ranging

   292 from simply checking for an environmental variable to scanning directories on

   293 Windows. Even more flexibly, the build environment itself can be checked using

   294 functions similar to those provided in CMake to check if a function compiles,

   295 library exists, etc. The following example comes from

   296 sdl_dependency_checkers.lua and is used by the Linux dependency in the SDL2

   297 project to determine whether the OSS sound system is supported:

   298

   299     function ossDep()

   300     	print("Checking for OSS support...")

   301     	if not check_cxx_source_compiles([[

   302     				#include <sys/soundcard.h>

   303     				int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]])

   304     			and not check_cxx_source_compiles([[

   305     				#include <soundcard.h>

   306     				int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]]) then

   307     		print("Warning: OSS unsupported!")

   308     		return { found = false }

   309     	end

   310     	return { found = true }

   311     end

   312

   313 Notice how it uses 'check_cxx_source_compiles'. There are even more functions

   314 than this to check and, rather than going in detail with them here, I encourage

   315 you to look at the documented functions within ./util/sdl_check_compile.lua.

   316

   317 In order to support new platforms, start with the minimal configuration template

   318 provided and work off of the initial SDL2 project. You may add additional

   319 dependencies to define other source files specific to that platform (see how

   320 it's done with Windows and Mac OS X), or you can add special dependencies that

   321 rely on dependency functions you may implement yourself (see DirectX and

   322 OpenGL). Dependencies can use the 'SDL_config' directive to specify special

   323 values that can be pasted into the resulting configuration header file upon

   324 generation.

   325

   326 For more detailed information about the functions supported and how they work,

   327 look at all of the Lua files in the util directory, as well as any of the

   328 example projects in the projects directory to demonstrate how many of these

   329 functions are used. The information above is only a quick subset of the

   330 capabilities of the meta-build system.