premake/README.txt
author Ryan C. Gordon <icculus@icculus.org>
Sun, 10 Nov 2013 00:38:37 -0500
changeset 7925 f090a47eb7f7
permissions -rwxr-xr-x
Added Ben Henning's GSoC2013 work: premake build system.
icculus@7925
     1
Author: Ben Henning <b.henning@digipen.edu>
icculus@7925
     2
icculus@7925
     3
The goal of this project is to provide a lightweight and portable meta-build
icculus@7925
     4
system for generating build systems for various platforms and architectures, all
icculus@7925
     5
for the SDL2 library and subsequently dependent executables.
icculus@7925
     6
icculus@7925
     7
Following is a table of contents for the entire README file.
icculus@7925
     8
icculus@7925
     9
[0] OVERVIEW
icculus@7925
    10
[1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS
icculus@7925
    11
[2] STRUCTURE
icculus@7925
    12
[3] SUPPORT ON WINDOWS AND VISUAL STUDIO
icculus@7925
    13
[4] SUPPORT ON MAC OS X AND XCODE
icculus@7925
    14
[5] SUPPORT FOR IOS
icculus@7925
    15
[6] SUPPORT FOR LINUX
icculus@7925
    16
[7] SUPPORT FOR MINGW
icculus@7925
    17
[8] SUPPORT FOR CYGWIN
icculus@7925
    18
[9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS (code samples)
icculus@7925
    19
icculus@7925
    20
[0] OVERVIEW
icculus@7925
    21
icculus@7925
    22
The system is capable of generating projects for many different platforms and
icculus@7925
    23
architectures. How to generically generate projects is described in the next
icculus@7925
    24
section. Subsequent sections thereafter describe more specific ways to generate
icculus@7925
    25
projects and dependencies projects have.
icculus@7925
    26
icculus@7925
    27
All of the projects inherently have things in common, such as depending on the
icculus@7925
    28
same source tree for header and source files. All projects generated will also
icculus@7925
    29
have both debug and release configurations available to be built. More
icculus@7925
    30
information on how to build either will be provided below.
icculus@7925
    31
icculus@7925
    32
To view a list of progress on the project, view the changelog.
icculus@7925
    33
icculus@7925
    34
[1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS
icculus@7925
    35
icculus@7925
    36
To receive help with various premake actions and command-line options, or to
icculus@7925
    37
view the options available for the current premake environment, run the
icculus@7925
    38
following command:
icculus@7925
    39
icculus@7925
    40
    ./premake4 --file=./path/to/premake4.lua help
icculus@7925
    41
icculus@7925
    42
To construct the project files, run this local command from any command line:
icculus@7925
    43
icculus@7925
    44
    .\premake4 --file=.\path\to\premake4.lua --to=.\resultDirectory [opts] [vs2008/vs2010/vs2012]
icculus@7925
    45
OR
icculus@7925
    46
    ./premake4 --file=./path/to/premake4.lua --to=./resultDirectory [opts] [xcode3/xcode4/gmake]
icculus@7925
    47
icculus@7925
    48
opts may be one of:
icculus@7925
    49
  --mingw
icculus@7925
    50
  --cygwin
icculus@7925
    51
  --ios
icculus@7925
    52
icculus@7925
    53
opts may also include any of the following:
icculus@7925
    54
  --alsa        :  Force the ALSA dependency on for Linux targets.
icculus@7925
    55
  --dbus        :  Force the D-Bus dependency on for Linux targets.
icculus@7925
    56
  --directx     :  Force the DirectX dependency on for Windows, MinGW, and Cygwin targets.
icculus@7925
    57
  --dlopen      :  Force the DLOpen dependency on for Linux targets.
icculus@7925
    58
  --esd         :  Force the ESD dependency on for Linux targets.
icculus@7925
    59
  --nas         :  Force the NAS dependency on for Linux targets.
icculus@7925
    60
  --opengl      :  Force the OpenGL dependency on for any target.
icculus@7925
    61
  --oss         :  Force the OSS dependency on for Linux targets.
icculus@7925
    62
  --pulseaudio  :  Force the PulseAudio dependency on for Linux targets.
icculus@7925
    63
  --x11         :  Force the X11 dependency on for Linux targets.
icculus@7925
    64
icculus@7925
    65
All projects have debug and release configurations that may be built. For IDE
icculus@7925
    66
projects such as Visual Studio and Xcode, there are configurations in the former
icculus@7925
    67
and schemas in the latter to handle this.
icculus@7925
    68
icculus@7925
    69
For make files, the following command line may be used:
icculus@7925
    70
    make config=debug
icculus@7925
    71
or:
icculus@7925
    72
    make config=release
icculus@7925
    73
icculus@7925
    74
The make files also have a level of verbosity that will print all compiler and
icculus@7925
    75
linking commands to the command line. This can be enabled with the following
icculus@7925
    76
command:
icculus@7925
    77
    make verbose=1
icculus@7925
    78
icculus@7925
    79
[2] STRUCTURE
icculus@7925
    80
icculus@7925
    81
The structure of the meta-build system is split into three parts:
icculus@7925
    82
icculus@7925
    83
  1. The core system which runs all of the other scripts, generates the premake
icculus@7925
    84
    Lua file that is used to generate the actual build system, and sets up
icculus@7925
    85
    premake to generate it. (premake4.lua)
icculus@7925
    86
icculus@7925
    87
  2. The utility files for performing various convenience operations, ranging
icculus@7925
    88
    from string operations and a file wrapper to custom project definitions and
icculus@7925
    89
    complex dependency checking using CMake-esque functions. There is also a
icculus@7925
    90
    file containing custom dependency functions for checked support.
icculus@7925
    91
    (everything in the util folder)
icculus@7925
    92
icculus@7925
    93
  3. The project definition files, which define each and every project related
icculus@7925
    94
    to SDL2. This includes the SDL2 library itself, along with all of its
icculus@7925
    95
    current tests and iOS Demos. These files also related to dependency handling
icculus@7925
    96
    and help build dependency trees for the various projects.
icculus@7925
    97
    (everything in the projects folder)
icculus@7925
    98
icculus@7925
    99
The premake4.lua file is lightly documented and commented to explain how it
icculus@7925
   100
interfaces with the other utility files and project files. It is not extensively
icculus@7925
   101
documented because the actual generation process is not considered to be
icculus@7925
   102
pertinent to the overall usage of the meta-build system.
icculus@7925
   103
icculus@7925
   104
The utility files have thorough documentation, since they are the foundation for
icculus@7925
   105
the entire project definition and dependency handling systems.
icculus@7925
   106
icculus@7925
   107
The project definition files are lightly documented, since they are expected to
icculus@7925
   108
be self-explanatory. Look through each and every project definition file
icculus@7925
   109
(especially SDL2.lua, testgl2.lua, testshape.lua, testsprite2.lua, and
icculus@7925
   110
testnative.lua) to gain experience and familiarity with most of the project
icculus@7925
   111
definition system.
icculus@7925
   112
icculus@7925
   113
The dependency system is very straightforward. As explained in both
icculus@7925
   114
sdl_projects.lua and sdl_dependency_checkers.lua, a function for checking the
icculus@7925
   115
actual dependency support is registered by its name and then referenced to in
icculus@7925
   116
the project definitions (such as for SDL2.lua). These definitions are allowed to
icculus@7925
   117
do anything necessary to determine whether the appropriate support exists in the
icculus@7925
   118
current build environment or not. The possibilities for checking can be seen
icculus@7925
   119
specifically in the function for checking DirectX support and any of the Linux
icculus@7925
   120
dependency functions using the sdl_check_compile.lua functions.
icculus@7925
   121
icculus@7925
   122
As far as building the projects is concerned, the project definitions are
icculus@7925
   123
allowed to set configuration key-value pairs which will be translated and placed
icculus@7925
   124
inside a generated SDL config header file, similar to the one generated by both
icculus@7925
   125
autotools and CMake.
icculus@7925
   126
icculus@7925
   127
[3] SUPPORT ON WINDOWS AND VISUAL STUDIO
icculus@7925
   128
icculus@7925
   129
Check the Windows README for more information on SDL2 support on Windows and
icculus@7925
   130
Visual Studio. Current support exists for Visual Studio 2008, 2010, and 2012.
icculus@7925
   131
icculus@7925
   132
[4] SUPPORT ON MAC OS X AND XCODE
icculus@7925
   133
icculus@7925
   134
Check the Mac OS X README for more information on SDL2 support on Mac OS X using
icculus@7925
   135
Xcode. Current support should exist for Mac OS X 10.6, 10.7, and 10.8 (as
icculus@7925
   136
tested, but more may be supported). Supported Xcode versions are 3 and 4. It
icculus@7925
   137
supports building for both i686 and x86_64 architectures, as well as support for
icculus@7925
   138
universal 32-bit binaries, universal 64-bit binaries, and universal combined
icculus@7925
   139
binaries.
icculus@7925
   140
icculus@7925
   141
[5] SUPPORT FOR IOS
icculus@7925
   142
icculus@7925
   143
EXPERIMENTAL SUPPORT
icculus@7925
   144
icculus@7925
   145
Check the iOS README for more information on SDL2 support on iOS using Xcode.
icculus@7925
   146
Current support has been tested on the iOS 6 emulators for iPhone and iPad,
icculus@7925
   147
using both Xcode 3 and Xcode 4. The iOS project will reference all the Demos
icculus@7925
   148
the manual project does.
icculus@7925
   149
icculus@7925
   150
[6] SUPPORT FOR LINUX
icculus@7925
   151
icculus@7925
   152
EXPERIMENTAL SUPPORT
icculus@7925
   153
icculus@7925
   154
Check the Linux README for more information on SDL2 support on Linux. Currently,
icculus@7925
   155
only a subset of the Linux dependencies are supported, and they are supported
icculus@7925
   156
partially. Linux also builds to a static library instead of a shared library.
icculus@7925
   157
The tests run well and as expected.
icculus@7925
   158
icculus@7925
   159
[7] SUPPORT FOR MINGW
icculus@7925
   160
icculus@7925
   161
Check the MinGW README for more information on SDL2 support on MinGW. Currently,
icculus@7925
   162
all of the tests that work using the Visual Studio projects also seem to work
icculus@7925
   163
with MinGW, minus DirectX support. DirectX is not inherently supported, but can
icculus@7925
   164
be forcibly turned on if the user knows what they are doing.
icculus@7925
   165
icculus@7925
   166
[8] SUPPORT FOR CYGWIN
icculus@7925
   167
icculus@7925
   168
BROKEN SUPPORT
icculus@7925
   169
icculus@7925
   170
Check the Cygwin README for more information on the progress of supporting SDL2
icculus@7925
   171
on Cygwin.
icculus@7925
   172
icculus@7925
   173
[9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS
icculus@7925
   174
icculus@7925
   175
In order to create a new project, simply create a Lua file and place it within
icculus@7925
   176
the projects directory. The meta-build system will automatically include it.
icculus@7925
   177
It must contain a SDL_project definition. Projects *must* have source files as
icculus@7925
   178
well, otherwise they will be ignored by the meta-build system. There are a
icculus@7925
   179
plethora of examples demonstrating how to defined projects, link them to various
icculus@7925
   180
dependencies, and to create dependencies.
icculus@7925
   181
icculus@7925
   182
Here is an example that creates a new project named foo, it's a ConsoleApp
icculus@7925
   183
(which is the default for SDL projects, look at http://industriousone.com/kind
icculus@7925
   184
for more information). Its language is C and its source directory is "../test"
icculus@7925
   185
(this path is relative to the location of premake4.lua). It's project location
icculus@7925
   186
is "tests", which means it will be placed in the ./tests/ folder of whichever
icculus@7925
   187
destination directory is set while generating the project (for example,
icculus@7925
   188
./VisualC/tests). It is including all the files starting with "foo." from the
icculus@7925
   189
"../test" folder.
icculus@7925
   190
icculus@7925
   191
    SDL_project "foo"
icculus@7925
   192
    	SDL_kind "ConsoleApp"
icculus@7925
   193
    	SDL_language "C"
icculus@7925
   194
    	SDL_sourcedir "../test"
icculus@7925
   195
    	SDL_projectLocation "tests"
icculus@7925
   196
    	SDL_files { "/testrendercopyex.*" }
icculus@7925
   197
icculus@7925
   198
Now, we can extend this project slightly:
icculus@7925
   199
icculus@7925
   200
    SDL_project "foo"
icculus@7925
   201
    	SDL_kind "ConsoleApp"
icculus@7925
   202
    	SDL_notos "ios|cygwin"
icculus@7925
   203
    	SDL_language "C"
icculus@7925
   204
    	SDL_sourcedir "../test"
icculus@7925
   205
    	SDL_projectLocation "tests"
icculus@7925
   206
    	SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" }
icculus@7925
   207
    	SDL_files { "/foo.*" }
icculus@7925
   208
    	SDL_copy { "icon.bmp", "sample.bmp" }
icculus@7925
   209
icculus@7925
   210
We now specified that this application will not work on iOS or Cygwin targets,
icculus@7925
   211
so it will be discluded when generating projects for those platforms. We have
icculus@7925
   212
also specified that this project depends on 'SDL2main', 'SDL2test', and 'SDL2',
icculus@7925
   213
which are other projects that are already defined. We can set the dependency
icculus@7925
   214
to any projects the SDL2 meta-build system is aware of. We also have an
icculus@7925
   215
interesting SDL_copy directive, which will automatically copy the files
icculus@7925
   216
"icon.bmp" and "sample.bmp" from "<sdl_root>/test" to the directory of foo's
icculus@7925
   217
executable when it's built.
icculus@7925
   218
icculus@7925
   219
Let's take a look at another example:
icculus@7925
   220
icculus@7925
   221
    SDL_project "testgl2"
icculus@7925
   222
    	SDL_kind "ConsoleApp"
icculus@7925
   223
    	SDL_notos "ios|cygwin"
icculus@7925
   224
    	SDL_language "C"
icculus@7925
   225
    	SDL_sourcedir "../test"
icculus@7925
   226
    	SDL_projectLocation "tests"
icculus@7925
   227
    	SDL_projectDependencies { "SDL2main", "SDL2test", "SDL2" }
icculus@7925
   228
    	SDL_defines { "HAVE_OPENGL" }
icculus@7925
   229
    	SDL_dependency "OpenGL"
icculus@7925
   230
    		-- opengl is platform independent
icculus@7925
   231
    		SDL_depfunc "OpenGL"
icculus@7925
   232
    		SDL_files { "/testgl2.*" }
icculus@7925
   233
icculus@7925
   234
This is a copy of the testgl2.lua file. Most of this is already familiar, but
icculus@7925
   235
there are a few new things to point out. We can set preprocessor definitions by
icculus@7925
   236
using the 'SDL_defines' directive. We can also create a dependency for the
icculus@7925
   237
project on some varied criteria. For example, testgl2 is obviously dependent on
icculus@7925
   238
the presence of the OpenGL library. So, the only way it will include the
icculus@7925
   239
"testgl2.*" (testgl2.c/testgl2.h) files is if the dependency function "OpenGL"
icculus@7925
   240
returns information regarding the whereabouts of the OpenGL library on the
icculus@7925
   241
current system. This function is registered in sdl_dependency_checkers.lua:
icculus@7925
   242
icculus@7925
   243
    function openGLDep()
icculus@7925
   244
    	print("Checking OpenGL dependencies...")
icculus@7925
   245
    	...
icculus@7925
   246
    	return { found = foundLib, libDirs = { }, libs = { libname } }
icculus@7925
   247
    end
icculus@7925
   248
    ...
icculus@7925
   249
    SDL_registerDependencyChecker("OpenGL", openGLDep)
icculus@7925
   250
icculus@7925
   251
This function is called when it's time to decide whether testgl2 should be
icculus@7925
   252
generated or not. openGLDep can use any and all functions to decide whether
icculus@7925
   253
OpenGL is supported.
icculus@7925
   254
icculus@7925
   255
Dependencies and projects can become much more sophisticate, if necessary. Take
icculus@7925
   256
the following example from the SDL2.lua project definition:
icculus@7925
   257
icculus@7925
   258
    -- DirectX dependency
icculus@7925
   259
    SDL_dependency "directx"
icculus@7925
   260
    	SDL_os "windows|mingw"
icculus@7925
   261
    	SDL_depfunc "DirectX"
icculus@7925
   262
    	SDL_config
icculus@7925
   263
    	{
icculus@7925
   264
    		["SDL_AUDIO_DRIVER_DSOUND"] = 1,
icculus@7925
   265
    		["SDL_AUDIO_DRIVER_XAUDIO2"] = 1,
icculus@7925
   266
    		["SDL_JOYSTICK_DINPUT"] = 1,
icculus@7925
   267
    		["SDL_HAPTIC_DINPUT"] = 1,
icculus@7925
   268
    		["SDL_VIDEO_RENDER_D3D"] = 1
icculus@7925
   269
    	}
icculus@7925
   270
    	SDL_paths
icculus@7925
   271
    	{
icculus@7925
   272
    		"/audio/directsound/",
icculus@7925
   273
    		"/audio/xaudio2/",
icculus@7925
   274
    		"/render/direct3d/",
icculus@7925
   275
    		-- these two depend on Xinput
icculus@7925
   276
    		"/haptic/windows/",
icculus@7925
   277
    		"/joystick/windows/",
icculus@7925
   278
    	}
icculus@7925
   279
icculus@7925
   280
This dependency is, as expected, for DirectX. One thing to note here is even
icculus@7925
   281
dependencies can be dependent on an operating system. This dependency will not
icculus@7925
   282
even be resolved if SDL2 is being generated on, say, Linux or Mac OS X. Two new
icculus@7925
   283
things shown here are 'SDL_config' and 'SDL_paths' directives. SDL_config allows
icculus@7925
   284
you to set preprocessor definitions that will be pasted into
icculus@7925
   285
SDL_config_premake.h (which acts as a replacement to SDL_config.h when building
icculus@7925
   286
the project). This allows for significant flexibility (look around SDL2.lua's
icculus@7925
   287
dependencies, especially for Linux). SDL_paths works like SDL_files, except it
icculus@7925
   288
includes all .c, .h, and .m files within that directory. The directory is still
icculus@7925
   289
relative to the source directory of the project (in this case, <sdl_root>/src).
icculus@7925
   290
icculus@7925
   291
Finally, dependency checking can be done in a huge variety of ways, ranging
icculus@7925
   292
from simply checking for an environmental variable to scanning directories on
icculus@7925
   293
Windows. Even more flexibly, the build environment itself can be checked using
icculus@7925
   294
functions similar to those provided in CMake to check if a function compiles,
icculus@7925
   295
library exists, etc. The following example comes from
icculus@7925
   296
sdl_dependency_checkers.lua and is used by the Linux dependency in the SDL2
icculus@7925
   297
project to determine whether the OSS sound system is supported:
icculus@7925
   298
icculus@7925
   299
    function ossDep()
icculus@7925
   300
    	print("Checking for OSS support...")
icculus@7925
   301
    	if not check_cxx_source_compiles([[
icculus@7925
   302
    				#include <sys/soundcard.h>
icculus@7925
   303
    				int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]])
icculus@7925
   304
    			and not check_cxx_source_compiles([[
icculus@7925
   305
    				#include <soundcard.h>
icculus@7925
   306
    				int main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]]) then
icculus@7925
   307
    		print("Warning: OSS unsupported!")
icculus@7925
   308
    		return { found = false }
icculus@7925
   309
    	end
icculus@7925
   310
    	return { found = true }
icculus@7925
   311
    end
icculus@7925
   312
icculus@7925
   313
Notice how it uses 'check_cxx_source_compiles'. There are even more functions
icculus@7925
   314
than this to check and, rather than going in detail with them here, I encourage
icculus@7925
   315
you to look at the documented functions within ./util/sdl_check_compile.lua.
icculus@7925
   316
icculus@7925
   317
In order to support new platforms, start with the minimal configuration template
icculus@7925
   318
provided and work off of the initial SDL2 project. You may add additional
icculus@7925
   319
dependencies to define other source files specific to that platform (see how
icculus@7925
   320
it's done with Windows and Mac OS X), or you can add special dependencies that
icculus@7925
   321
rely on dependency functions you may implement yourself (see DirectX and
icculus@7925
   322
OpenGL). Dependencies can use the 'SDL_config' directive to specify special
icculus@7925
   323
values that can be pasted into the resulting configuration header file upon
icculus@7925
   324
generation.
icculus@7925
   325
icculus@7925
   326
For more detailed information about the functions supported and how they work,
icculus@7925
   327
look at all of the Lua files in the util directory, as well as any of the
icculus@7925
   328
example projects in the projects directory to demonstrate how many of these
icculus@7925
   329
functions are used. The information above is only a quick subset of the
icculus@7925
   330
capabilities of the meta-build system.