premake/README.txt
changeset 7925 f090a47eb7f7
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/premake/README.txt	Sun Nov 10 00:38:37 2013 -0500
     1.3 @@ -0,0 +1,330 @@
     1.4 +Author: Ben Henning <b.henning@digipen.edu>
     1.5 +
     1.6 +The goal of this project is to provide a lightweight and portable meta-build
     1.7 +system for generating build systems for various platforms and architectures, all
     1.8 +for the SDL2 library and subsequently dependent executables.
     1.9 +
    1.10 +Following is a table of contents for the entire README file.
    1.11 +
    1.12 +[0] OVERVIEW
    1.13 +[1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS
    1.14 +[2] STRUCTURE
    1.15 +[3] SUPPORT ON WINDOWS AND VISUAL STUDIO
    1.16 +[4] SUPPORT ON MAC OS X AND XCODE
    1.17 +[5] SUPPORT FOR IOS
    1.18 +[6] SUPPORT FOR LINUX
    1.19 +[7] SUPPORT FOR MINGW
    1.20 +[8] SUPPORT FOR CYGWIN
    1.21 +[9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS (code samples)
    1.22 +
    1.23 +[0] OVERVIEW
    1.24 +
    1.25 +The system is capable of generating projects for many different platforms and
    1.26 +architectures. How to generically generate projects is described in the next
    1.27 +section. Subsequent sections thereafter describe more specific ways to generate
    1.28 +projects and dependencies projects have.
    1.29 +
    1.30 +All of the projects inherently have things in common, such as depending on the
    1.31 +same source tree for header and source files. All projects generated will also
    1.32 +have both debug and release configurations available to be built. More
    1.33 +information on how to build either will be provided below.
    1.34 +
    1.35 +To view a list of progress on the project, view the changelog.
    1.36 +
    1.37 +[1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS
    1.38 +
    1.39 +To receive help with various premake actions and command-line options, or to
    1.40 +view the options available for the current premake environment, run the
    1.41 +following command:
    1.42 +
    1.43 +    ./premake4 --file=./path/to/premake4.lua help
    1.44 +
    1.45 +To construct the project files, run this local command from any command line:
    1.46 +
    1.47 +    .\premake4 --file=.\path\to\premake4.lua --to=.\resultDirectory [opts] [vs2008/vs2010/vs2012]
    1.48 +OR
    1.49 +    ./premake4 --file=./path/to/premake4.lua --to=./resultDirectory [opts] [xcode3/xcode4/gmake]
    1.50 +
    1.51 +opts may be one of:
    1.52 +  --mingw
    1.53 +  --cygwin
    1.54 +  --ios
    1.55 +
    1.56 +opts may also include any of the following:
    1.57 +  --alsa        :  Force the ALSA dependency on for Linux targets.
    1.58 +  --dbus        :  Force the D-Bus dependency on for Linux targets.
    1.59 +  --directx     :  Force the DirectX dependency on for Windows, MinGW, and Cygwin targets.
    1.60 +  --dlopen      :  Force the DLOpen dependency on for Linux targets.
    1.61 +  --esd         :  Force the ESD dependency on for Linux targets.
    1.62 +  --nas         :  Force the NAS dependency on for Linux targets.
    1.63 +  --opengl      :  Force the OpenGL dependency on for any target.
    1.64 +  --oss         :  Force the OSS dependency on for Linux targets.
    1.65 +  --pulseaudio  :  Force the PulseAudio dependency on for Linux targets.
    1.66 +  --x11         :  Force the X11 dependency on for Linux targets.
    1.67 +
    1.68 +All projects have debug and release configurations that may be built. For IDE
    1.69 +projects such as Visual Studio and Xcode, there are configurations in the former
    1.70 +and schemas in the latter to handle this.
    1.71 +
    1.72 +For make files, the following command line may be used:
    1.73 +    make config=debug
    1.74 +or:
    1.75 +    make config=release
    1.76 +
    1.77 +The make files also have a level of verbosity that will print all compiler and
    1.78 +linking commands to the command line. This can be enabled with the following
    1.79 +command:
    1.80 +    make verbose=1
    1.81 +
    1.82 +[2] STRUCTURE
    1.83 +
    1.84 +The structure of the meta-build system is split into three parts:
    1.85 +
    1.86 +  1. The core system which runs all of the other scripts, generates the premake
    1.87 +    Lua file that is used to generate the actual build system, and sets up
    1.88 +    premake to generate it. (premake4.lua)
    1.89 +
    1.90 +  2. The utility files for performing various convenience operations, ranging
    1.91 +    from string operations and a file wrapper to custom project definitions and
    1.92 +    complex dependency checking using CMake-esque functions. There is also a
    1.93 +    file containing custom dependency functions for checked support.
    1.94 +    (everything in the util folder)
    1.95 +
    1.96 +  3. The project definition files, which define each and every project related
    1.97 +    to SDL2. This includes the SDL2 library itself, along with all of its
    1.98 +    current tests and iOS Demos. These files also related to dependency handling
    1.99 +    and help build dependency trees for the various projects.
   1.100 +    (everything in the projects folder)
   1.101 +
   1.102 +The premake4.lua file is lightly documented and commented to explain how it
   1.103 +interfaces with the other utility files and project files. It is not extensively
   1.104 +documented because the actual generation process is not considered to be
   1.105 +pertinent to the overall usage of the meta-build system.
   1.106 +
   1.107 +The utility files have thorough documentation, since they are the foundation for
   1.108 +the entire project definition and dependency handling systems.
   1.109 +
   1.110 +The project definition files are lightly documented, since they are expected to
   1.111 +be self-explanatory. Look through each and every project definition file
   1.112 +(especially SDL2.lua, testgl2.lua, testshape.lua, testsprite2.lua, and
   1.113 +testnative.lua) to gain experience and familiarity with most of the project
   1.114 +definition system.
   1.115 +
   1.116 +The dependency system is very straightforward. As explained in both
   1.117 +sdl_projects.lua and sdl_dependency_checkers.lua, a function for checking the
   1.118 +actual dependency support is registered by its name and then referenced to in
   1.119 +the project definitions (such as for SDL2.lua). These definitions are allowed to
   1.120 +do anything necessary to determine whether the appropriate support exists in the
   1.121 +current build environment or not. The possibilities for checking can be seen
   1.122 +specifically in the function for checking DirectX support and any of the Linux
   1.123 +dependency functions using the sdl_check_compile.lua functions.
   1.124 +
   1.125 +As far as building the projects is concerned, the project definitions are
   1.126 +allowed to set configuration key-value pairs which will be translated and placed
   1.127 +inside a generated SDL config header file, similar to the one generated by both
   1.128 +autotools and CMake.
   1.129 +
   1.130 +[3] SUPPORT ON WINDOWS AND VISUAL STUDIO
   1.131 +
   1.132 +Check the Windows README for more information on SDL2 support on Windows and
   1.133 +Visual Studio. Current support exists for Visual Studio 2008, 2010, and 2012.
   1.134 +
   1.135 +[4] SUPPORT ON MAC OS X AND XCODE
   1.136 +
   1.137 +Check the Mac OS X README for more information on SDL2 support on Mac OS X using
   1.138 +Xcode. Current support should exist for Mac OS X 10.6, 10.7, and 10.8 (as
   1.139 +tested, but more may be supported). Supported Xcode versions are 3 and 4. It
   1.140 +supports building for both i686 and x86_64 architectures, as well as support for
   1.141 +universal 32-bit binaries, universal 64-bit binaries, and universal combined
   1.142 +binaries.
   1.143 +
   1.144 +[5] SUPPORT FOR IOS
   1.145 +
   1.146 +EXPERIMENTAL SUPPORT
   1.147 +
   1.148 +Check the iOS README for more information on SDL2 support on iOS using Xcode.
   1.149 +Current support has been tested on the iOS 6 emulators for iPhone and iPad,
   1.150 +using both Xcode 3 and Xcode 4. The iOS project will reference all the Demos
   1.151 +the manual project does.
   1.152 +
   1.153 +[6] SUPPORT FOR LINUX
   1.154 +
   1.155 +EXPERIMENTAL SUPPORT
   1.156 +
   1.157 +Check the Linux README for more information on SDL2 support on Linux. Currently,
   1.158 +only a subset of the Linux dependencies are supported, and they are supported
   1.159 +partially. Linux also builds to a static library instead of a shared library.
   1.160 +The tests run well and as expected.
   1.161 +
   1.162 +[7] SUPPORT FOR MINGW
   1.163 +
   1.164 +Check the MinGW README for more information on SDL2 support on MinGW. Currently,
   1.165 +all of the tests that work using the Visual Studio projects also seem to work
   1.166 +with MinGW, minus DirectX support. DirectX is not inherently supported, but can
   1.167 +be forcibly turned on if the user knows what they are doing.
   1.168 +
   1.169 +[8] SUPPORT FOR CYGWIN
   1.170 +
   1.171 +BROKEN SUPPORT
   1.172 +
   1.173 +Check the Cygwin README for more information on the progress of supporting SDL2
   1.174 +on Cygwin.
   1.175 +
   1.176 +[9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS
   1.177 +
   1.178 +In order to create a new project, simply create a Lua file and place it within
   1.179 +the projects directory. The meta-build system will automatically include it.
   1.180 +It must contain a SDL_project definition. Projects *must* have source files as
   1.181 +well, otherwise they will be ignored by the meta-build system. There are a
   1.182 +plethora of examples demonstrating how to defined projects, link them to various
   1.183 +dependencies, and to create dependencies.
   1.184 +
   1.185 +Here is an example that creates a new project named foo, it's a ConsoleApp
   1.186 +(which is the default for SDL projects, look at http://industriousone.com/kind
   1.187 +for more information). Its language is C and its source directory is "../test"
   1.188 +(this path is relative to the location of premake4.lua). It's project location
   1.189 +is "tests", which means it will be placed in the ./tests/ folder of whichever
   1.190 +destination directory is set while generating the project (for example,
   1.191 +./VisualC/tests). It is including all the files starting with "foo." from the
   1.192 +"../test" folder.
   1.193 +
   1.194 +    SDL_project "foo"
   1.195 +    	SDL_kind "ConsoleApp"
   1.196 +    	SDL_language "C"
   1.197 +    	SDL_sourcedir "../test"
   1.198 +    	SDL_projectLocation "tests"
   1.199 +    	SDL_files { "/testrendercopyex.*" }
   1.200 +
   1.201 +Now, we can extend this project slightly:
   1.202 +
   1.203 +    SDL_project "foo"
   1.204 +    	SDL_kind "ConsoleApp"
   1.205 +    	SDL_notos "ios|cygwin"
   1.206 +    	SDL_language "C"
   1.207 +    	SDL_sourcedir "../test"
   1.208 +    	SDL_projectLocation "tests"
   1.209 +    	SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" }
   1.210 +    	SDL_files { "/foo.*" }
   1.211 +    	SDL_copy { "icon.bmp", "sample.bmp" }
   1.212 +
   1.213 +We now specified that this application will not work on iOS or Cygwin targets,
   1.214 +so it will be discluded when generating projects for those platforms. We have
   1.215 +also specified that this project depends on 'SDL2main', 'SDL2test', and 'SDL2',
   1.216 +which are other projects that are already defined. We can set the dependency
   1.217 +to any projects the SDL2 meta-build system is aware of. We also have an
   1.218 +interesting SDL_copy directive, which will automatically copy the files
   1.219 +"icon.bmp" and "sample.bmp" from "<sdl_root>/test" to the directory of foo's
   1.220 +executable when it's built.
   1.221 +
   1.222 +Let's take a look at another example:
   1.223 +
   1.224 +    SDL_project "testgl2"
   1.225 +    	SDL_kind "ConsoleApp"
   1.226 +    	SDL_notos "ios|cygwin"
   1.227 +    	SDL_language "C"
   1.228 +    	SDL_sourcedir "../test"
   1.229 +    	SDL_projectLocation "tests"
   1.230 +    	SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" }
   1.231 +    	SDL_defines { "HAVE_OPENGL" }
   1.232 +    	SDL_dependency "OpenGL"
   1.233 +    		-- opengl is platform independent
   1.234 +    		SDL_depfunc "OpenGL"
   1.235 +    		SDL_files { "/testgl2.*" }
   1.236 +
   1.237 +This is a copy of the testgl2.lua file. Most of this is already familiar, but
   1.238 +there are a few new things to point out. We can set preprocessor definitions by
   1.239 +using the 'SDL_defines' directive. We can also create a dependency for the
   1.240 +project on some varied criteria. For example, testgl2 is obviously dependent on
   1.241 +the presence of the OpenGL library. So, the only way it will include the
   1.242 +"testgl2.*" (testgl2.c/testgl2.h) files is if the dependency function "OpenGL"
   1.243 +returns information regarding the whereabouts of the OpenGL library on the
   1.244 +current system. This function is registered in sdl_dependency_checkers.lua:
   1.245 +
   1.246 +    function openGLDep()
   1.247 +    	print("Checking OpenGL dependencies...")
   1.248 +    	...
   1.249 +    	return { found = foundLib, libDirs = { }, libs = { libname } }
   1.250 +    end
   1.251 +    ...
   1.252 +    SDL_registerDependencyChecker("OpenGL", openGLDep)
   1.253 +
   1.254 +This function is called when it's time to decide whether testgl2 should be
   1.255 +generated or not. openGLDep can use any and all functions to decide whether
   1.256 +OpenGL is supported.
   1.257 +
   1.258 +Dependencies and projects can become much more sophisticate, if necessary. Take
   1.259 +the following example from the SDL2.lua project definition:
   1.260 +
   1.261 +    -- DirectX dependency
   1.262 +    SDL_dependency "directx"
   1.263 +    	SDL_os "windows|mingw"
   1.264 +    	SDL_depfunc "DirectX"
   1.265 +    	SDL_config
   1.266 +    	{
   1.267 +    		["SDL_AUDIO_DRIVER_DSOUND"] = 1,
   1.268 +    		["SDL_AUDIO_DRIVER_XAUDIO2"] = 1,
   1.269 +    		["SDL_JOYSTICK_DINPUT"] = 1,
   1.270 +    		["SDL_HAPTIC_DINPUT"] = 1,
   1.271 +    		["SDL_VIDEO_RENDER_D3D"] = 1
   1.272 +    	}
   1.273 +    	SDL_paths
   1.274 +    	{
   1.275 +    		"/audio/directsound/",
   1.276 +    		"/audio/xaudio2/",
   1.277 +    		"/render/direct3d/",
   1.278 +    		-- these two depend on Xinput
   1.279 +    		"/haptic/windows/",
   1.280 +    		"/joystick/windows/",
   1.281 +    	}
   1.282 +
   1.283 +This dependency is, as expected, for DirectX. One thing to note here is even
   1.284 +dependencies can be dependent on an operating system. This dependency will not
   1.285 +even be resolved if SDL2 is being generated on, say, Linux or Mac OS X. Two new
   1.286 +things shown here are 'SDL_config' and 'SDL_paths' directives. SDL_config allows
   1.287 +you to set preprocessor definitions that will be pasted into
   1.288 +SDL_config_premake.h (which acts as a replacement to SDL_config.h when building
   1.289 +the project). This allows for significant flexibility (look around SDL2.lua's
   1.290 +dependencies, especially for Linux). SDL_paths works like SDL_files, except it
   1.291 +includes all .c, .h, and .m files within that directory. The directory is still
   1.292 +relative to the source directory of the project (in this case, <sdl_root>/src).
   1.293 +
   1.294 +Finally, dependency checking can be done in a huge variety of ways, ranging
   1.295 +from simply checking for an environmental variable to scanning directories on
   1.296 +Windows. Even more flexibly, the build environment itself can be checked using
   1.297 +functions similar to those provided in CMake to check if a function compiles,
   1.298 +library exists, etc. The following example comes from
   1.299 +sdl_dependency_checkers.lua and is used by the Linux dependency in the SDL2
   1.300 +project to determine whether the OSS sound system is supported:
   1.301 +
   1.302 +    function ossDep()
   1.303 +    	print("Checking for OSS support...")
   1.304 +    	if not check_cxx_source_compiles([[
   1.305 +    				#include <sys/soundcard.h>
   1.306 +    				int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]])
   1.307 +    			and not check_cxx_source_compiles([[
   1.308 +    				#include <soundcard.h>
   1.309 +    				int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]]) then
   1.310 +    		print("Warning: OSS unsupported!")
   1.311 +    		return { found = false }
   1.312 +    	end
   1.313 +    	return { found = true }
   1.314 +    end
   1.315 +
   1.316 +Notice how it uses 'check_cxx_source_compiles'. There are even more functions
   1.317 +than this to check and, rather than going in detail with them here, I encourage
   1.318 +you to look at the documented functions within ./util/sdl_check_compile.lua.
   1.319 +
   1.320 +In order to support new platforms, start with the minimal configuration template
   1.321 +provided and work off of the initial SDL2 project. You may add additional
   1.322 +dependencies to define other source files specific to that platform (see how
   1.323 +it's done with Windows and Mac OS X), or you can add special dependencies that
   1.324 +rely on dependency functions you may implement yourself (see DirectX and
   1.325 +OpenGL). Dependencies can use the 'SDL_config' directive to specify special
   1.326 +values that can be pasted into the resulting configuration header file upon
   1.327 +generation.
   1.328 +
   1.329 +For more detailed information about the functions supported and how they work,
   1.330 +look at all of the Lua files in the util directory, as well as any of the
   1.331 +example projects in the projects directory to demonstrate how many of these
   1.332 +functions are used. The information above is only a quick subset of the
   1.333 +capabilities of the meta-build system.
   1.334 \ No newline at end of file