SDL/premake/README.txt

Author: Ben Henning <b.henning@digipen.edu>

The goal of this project is to provide a lightweight and portable meta-build
system for generating build systems for various platforms and architectures, all
for the SDL2 library and subsequently dependent executables.

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

[0] OVERVIEW
[1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS
[2] STRUCTURE
[3] SUPPORT ON WINDOWS AND VISUAL STUDIO
[4] SUPPORT ON MAC OS X AND XCODE
[5] SUPPORT FOR IOS
[6] SUPPORT FOR LINUX
[7] SUPPORT FOR MINGW
[8] SUPPORT FOR CYGWIN
[9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS (code samples)

[0] OVERVIEW

The system is capable of generating projects for many different platforms and
architectures. How to generically generate projects is described in the next
section. Subsequent sections thereafter describe more specific ways to generate
projects and dependencies projects have.

All of the projects inherently have things in common, such as depending on the
same source tree for header and source files. All projects generated will also
have both debug and release configurations available to be built. More
information on how to build either will be provided below.

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

[1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS

To receive help with various premake actions and command-line options, or to
view the options available for the current premake environment, run the
following command:

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

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

    .\premake4 --file=.\path\to\premake4.lua --to=.\resultDirectory [opts] [vs2008/vs2010/vs2012]
OR
    ./premake4 --file=./path/to/premake4.lua --to=./resultDirectory [opts] [xcode3/xcode4/gmake]

opts may be one of:
  --mingw
  --cygwin
  --ios

opts may also include any of the following:
  --alsa        :  Force the ALSA dependency on for Linux targets.
  --dbus        :  Force the D-Bus dependency on for Linux targets.
  --directx     :  Force the DirectX dependency on for Windows, MinGW, and Cygwin targets.
  --dlopen      :  Force the DLOpen dependency on for Linux targets.
  --esd         :  Force the ESD dependency on for Linux targets.
  --nas         :  Force the NAS dependency on for Linux targets.
  --opengl      :  Force the OpenGL dependency on for any target.
  --oss         :  Force the OSS dependency on for Linux targets.
  --pulseaudio  :  Force the PulseAudio dependency on for Linux targets.
  --x11         :  Force the X11 dependency on for Linux targets.

All projects have debug and release configurations that may be built. For IDE
projects such as Visual Studio and Xcode, there are configurations in the former
and schemas in the latter to handle this.

For make files, the following command line may be used:
    make config=debug
or:
    make config=release

The make files also have a level of verbosity that will print all compiler and
linking commands to the command line. This can be enabled with the following
command:
    make verbose=1

[2] STRUCTURE

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

  1. The core system which runs all of the other scripts, generates the premake
    Lua file that is used to generate the actual build system, and sets up
    premake to generate it. (premake4.lua)

  2. The utility files for performing various convenience operations, ranging
    from string operations and a file wrapper to custom project definitions and
    complex dependency checking using CMake-esque functions. There is also a
    file containing custom dependency functions for checked support.
    (everything in the util folder)

  3. The project definition files, which define each and every project related
    to SDL2. This includes the SDL2 library itself, along with all of its
    current tests and iOS Demos. These files also related to dependency handling
    and help build dependency trees for the various projects.
    (everything in the projects folder)

The premake4.lua file is lightly documented and commented to explain how it
interfaces with the other utility files and project files. It is not extensively
documented because the actual generation process is not considered to be
pertinent to the overall usage of the meta-build system.

The utility files have thorough documentation, since they are the foundation for
the entire project definition and dependency handling systems.

The project definition files are lightly documented, since they are expected to
be self-explanatory. Look through each and every project definition file
(especially SDL2.lua, testgl2.lua, testshape.lua, testsprite2.lua, and
testnative.lua) to gain experience and familiarity with most of the project
definition system.

The dependency system is very straightforward. As explained in both
sdl_projects.lua and sdl_dependency_checkers.lua, a function for checking the
actual dependency support is registered by its name and then referenced to in
the project definitions (such as for SDL2.lua). These definitions are allowed to
do anything necessary to determine whether the appropriate support exists in the
current build environment or not. The possibilities for checking can be seen
specifically in the function for checking DirectX support and any of the Linux
dependency functions using the sdl_check_compile.lua functions.

As far as building the projects is concerned, the project definitions are
allowed to set configuration key-value pairs which will be translated and placed
inside a generated SDL config header file, similar to the one generated by both
autotools and CMake.

[3] SUPPORT ON WINDOWS AND VISUAL STUDIO

Check the Windows README for more information on SDL2 support on Windows and
Visual Studio. Current support exists for Visual Studio 2008, 2010, and 2012.

[4] SUPPORT ON MAC OS X AND XCODE

Check the Mac OS X README for more information on SDL2 support on Mac OS X using
Xcode. Current support should exist for Mac OS X 10.6, 10.7, and 10.8 (as
tested, but more may be supported). Supported Xcode versions are 3 and 4. It
supports building for both i686 and x86_64 architectures, as well as support for
universal 32-bit binaries, universal 64-bit binaries, and universal combined
binaries.

[5] SUPPORT FOR IOS

EXPERIMENTAL SUPPORT

Check the iOS README for more information on SDL2 support on iOS using Xcode.
Current support has been tested on the iOS 6 emulators for iPhone and iPad,
using both Xcode 3 and Xcode 4. The iOS project will reference all the Demos
the manual project does.

[6] SUPPORT FOR LINUX

EXPERIMENTAL SUPPORT

Check the Linux README for more information on SDL2 support on Linux. Currently,
only a subset of the Linux dependencies are supported, and they are supported
partially. Linux also builds to a static library instead of a shared library.
The tests run well and as expected.

[7] SUPPORT FOR MINGW

Check the MinGW README for more information on SDL2 support on MinGW. Currently,
all of the tests that work using the Visual Studio projects also seem to work
with MinGW, minus DirectX support. DirectX is not inherently supported, but can
be forcibly turned on if the user knows what they are doing.

[8] SUPPORT FOR CYGWIN

BROKEN SUPPORT

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

[9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS

In order to create a new project, simply create a Lua file and place it within
the projects directory. The meta-build system will automatically include it.
It must contain a SDL_project definition. Projects *must* have source files as
well, otherwise they will be ignored by the meta-build system. There are a
plethora of examples demonstrating how to defined projects, link them to various
dependencies, and to create dependencies.

Here is an example that creates a new project named foo, it's a ConsoleApp
(which is the default for SDL projects, look at http://industriousone.com/kind
for more information). Its language is C and its source directory is "../test"
(this path is relative to the location of premake4.lua). It's project location
is "tests", which means it will be placed in the ./tests/ folder of whichever
destination directory is set while generating the project (for example,
./VisualC/tests). It is including all the files starting with "foo." from the
"../test" folder.

    SDL_project "foo"
    	SDL_kind "ConsoleApp"
    	SDL_language "C"
    	SDL_sourcedir "../test"
    	SDL_projectLocation "tests"
    	SDL_files { "/testrendercopyex.*" }

Now, we can extend this project slightly:

    SDL_project "foo"
    	SDL_kind "ConsoleApp"
    	SDL_notos "ios|cygwin"
    	SDL_language "C"
    	SDL_sourcedir "../test"
    	SDL_projectLocation "tests"
    	SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" }
    	SDL_files { "/foo.*" }
    	SDL_copy { "icon.bmp", "sample.bmp" }

We now specified that this application will not work on iOS or Cygwin targets,
so it will be discluded when generating projects for those platforms. We have
also specified that this project depends on 'SDL2main', 'SDL2test', and 'SDL2',
which are other projects that are already defined. We can set the dependency
to any projects the SDL2 meta-build system is aware of. We also have an
interesting SDL_copy directive, which will automatically copy the files
"icon.bmp" and "sample.bmp" from "<sdl_root>/test" to the directory of foo's
executable when it's built.

Let's take a look at another example:

    SDL_project "testgl2"
    	SDL_kind "ConsoleApp"
    	SDL_notos "ios|cygwin"
    	SDL_language "C"
    	SDL_sourcedir "../test"
    	SDL_projectLocation "tests"
    	SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" }
    	SDL_defines { "HAVE_OPENGL" }
    	SDL_dependency "OpenGL"
    		-- opengl is platform independent
    		SDL_depfunc "OpenGL"
    		SDL_files { "/testgl2.*" }

This is a copy of the testgl2.lua file. Most of this is already familiar, but
there are a few new things to point out. We can set preprocessor definitions by
using the 'SDL_defines' directive. We can also create a dependency for the
project on some varied criteria. For example, testgl2 is obviously dependent on
the presence of the OpenGL library. So, the only way it will include the
"testgl2.*" (testgl2.c/testgl2.h) files is if the dependency function "OpenGL"
returns information regarding the whereabouts of the OpenGL library on the
current system. This function is registered in sdl_dependency_checkers.lua:

    function openGLDep()
    	print("Checking OpenGL dependencies...")
    	...
    	return { found = foundLib, libDirs = { }, libs = { libname } }
    end
    ...
    SDL_registerDependencyChecker("OpenGL", openGLDep)

This function is called when it's time to decide whether testgl2 should be
generated or not. openGLDep can use any and all functions to decide whether
OpenGL is supported.

Dependencies and projects can become much more sophisticate, if necessary. Take
the following example from the SDL2.lua project definition:

    -- DirectX dependency
    SDL_dependency "directx"
    	SDL_os "windows|mingw"
    	SDL_depfunc "DirectX"
    	SDL_config
    	{
    		["SDL_AUDIO_DRIVER_DSOUND"] = 1,
    		["SDL_AUDIO_DRIVER_XAUDIO2"] = 1,
    		["SDL_JOYSTICK_DINPUT"] = 1,
    		["SDL_HAPTIC_DINPUT"] = 1,
    		["SDL_VIDEO_RENDER_D3D"] = 1
    	}
    	SDL_paths
    	{
    		"/audio/directsound/",
    		"/audio/xaudio2/",
    		"/render/direct3d/",
    		-- these two depend on Xinput
    		"/haptic/windows/",
    		"/joystick/windows/",
    	}

This dependency is, as expected, for DirectX. One thing to note here is even
dependencies can be dependent on an operating system. This dependency will not
even be resolved if SDL2 is being generated on, say, Linux or Mac OS X. Two new
things shown here are 'SDL_config' and 'SDL_paths' directives. SDL_config allows
you to set preprocessor definitions that will be pasted into
SDL_config_premake.h (which acts as a replacement to SDL_config.h when building
the project). This allows for significant flexibility (look around SDL2.lua's
dependencies, especially for Linux). SDL_paths works like SDL_files, except it
includes all .c, .h, and .m files within that directory. The directory is still
relative to the source directory of the project (in this case, <sdl_root>/src).

Finally, dependency checking can be done in a huge variety of ways, ranging
from simply checking for an environmental variable to scanning directories on
Windows. Even more flexibly, the build environment itself can be checked using
functions similar to those provided in CMake to check if a function compiles,
library exists, etc. The following example comes from
sdl_dependency_checkers.lua and is used by the Linux dependency in the SDL2
project to determine whether the OSS sound system is supported:

    function ossDep()
    	print("Checking for OSS support...")
    	if not check_cxx_source_compiles([[
    				#include <sys/soundcard.h>
    				int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]])
    			and not check_cxx_source_compiles([[
    				#include <soundcard.h>
    				int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]]) then
    		print("Warning: OSS unsupported!")
    		return { found = false }
    	end
    	return { found = true }
    end

Notice how it uses 'check_cxx_source_compiles'. There are even more functions
than this to check and, rather than going in detail with them here, I encourage
you to look at the documented functions within ./util/sdl_check_compile.lua.

In order to support new platforms, start with the minimal configuration template
provided and work off of the initial SDL2 project. You may add additional
dependencies to define other source files specific to that platform (see how
it's done with Windows and Mac OS X), or you can add special dependencies that
rely on dependency functions you may implement yourself (see DirectX and
OpenGL). Dependencies can use the 'SDL_config' directive to specify special
values that can be pasted into the resulting configuration header file upon
generation.

For more detailed information about the functions supported and how they work,
look at all of the Lua files in the util directory, as well as any of the
example projects in the projects directory to demonstrate how many of these
functions are used. The information above is only a quick subset of the
capabilities of the meta-build system.