premake/README.txt
author Sam Lantinga <slouken@libsdl.org>
Wed, 04 Jun 2014 10:56:56 -0700
changeset 8820 0e935d5b193a
parent 7925 f090a47eb7f7
permissions -rwxr-xr-x
Added annotations to help code analysis tools

CR: Bruce Dawson
     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.