|
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. |