premake/README.txt
author Sam Lantinga <slouken@libsdl.org>
Fri, 28 Nov 2014 04:51:33 -0800
changeset 9246 a761913e5e91
parent 7925 f090a47eb7f7
permissions -rwxr-xr-x
Fixed bug 2786 - "UCS-2-INTERNAL" iconv encoding is not supported everywhere, use UTF-16LE instead

Jonas Kulla

src/main/windows/SDL_windows_main.c:137:
cmdline = SDL_iconv_string("UTF-8", "UCS-2-INTERNAL", (char *)(text), (SDL_wcslen(text)+1)*sizeof(WCHAR));

I'm trying to compile an SDL2 application for windows using the mingw-w64 32bit toolchain provided by my distro (Fedora 19). However, even the simplest test program that does nothing at all fails to startup with a "Fatal error - out of memory" message because the mingw iconv library provided by my distro does not support the "UCS-2-INTERNAL" encoding and the conversion returns null.

From my little bit of research, it turns out that even though this encoding is supported by the external GNU libiconv library, some glibc versions (?) don't support it with their internal iconv routines, and will instead provide the native endian encoding when "UCS-2" is specified.

Nonetheless, I wonder why the native endianness is considered in the first place when Windows doesn't even run on any big endian archs (to my knowledge). And true enough, 'WIN_StringToUTF8' from core/windows/SDL_windows.h is used everywhere else in the windows backend, which is just a macro to iconv with "UTF-16LE" as source. Therefore it would IMO make sense to use this macro here as well, which would solve my problem (patch attached).
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.