premake/README.txt
changeset 7925 f090a47eb7f7
equal deleted inserted replaced
7924:fcb86d323770 7925:f090a47eb7f7
       
     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.