{"payload":{"allShortcutsEnabled":false,"path":"premake","repo":{"id":330008801,"defaultBranch":"main","name":"SDL","ownerLogin":"libsdl-org","currentUserCanPush":false,"isFork":false,"isEmpty":false,"createdAt":"2021-01-15T19:55:54.000Z","ownerAvatar":"https://avatars.githubusercontent.com/u/77683370?v=4","public":true,"private":false,"isOrgOwned":true},"currentUser":null,"refInfo":{"name":"f0c061d141d014031c0962a828344fdfc4c91c32","listCacheKey":"v0:1709678518.0","canEdit":false,"refType":"tree","currentOid":"f0c061d141d014031c0962a828344fdfc4c91c32"},"tree":{"items":[{"name":"Cygwin/build-scripts","path":"premake/Cygwin/build-scripts","contentType":"directory","hasSimplifiedPath":true},{"name":"Linux","path":"premake/Linux","contentType":"directory"},{"name":"MinGW","path":"premake/MinGW","contentType":"directory"},{"name":"VisualC","path":"premake/VisualC","contentType":"directory"},{"name":"Xcode-iOS","path":"premake/Xcode-iOS","contentType":"directory"},{"name":"Xcode","path":"premake/Xcode","contentType":"directory"},{"name":"config","path":"premake/config","contentType":"directory"},{"name":"patches","path":"premake/patches","contentType":"directory"},{"name":"projects","path":"premake/projects","contentType":"directory"},{"name":"util","path":"premake/util","contentType":"directory"},{"name":"README-cygwin.txt","path":"premake/README-cygwin.txt","contentType":"file"},{"name":"README-ios.txt","path":"premake/README-ios.txt","contentType":"file"},{"name":"README-linux.txt","path":"premake/README-linux.txt","contentType":"file"},{"name":"README-macosx.txt","path":"premake/README-macosx.txt","contentType":"file"},{"name":"README-mingw.txt","path":"premake/README-mingw.txt","contentType":"file"},{"name":"README-windows.txt","path":"premake/README-windows.txt","contentType":"file"},{"name":"README.txt","path":"premake/README.txt","contentType":"file"},{"name":"changelog","path":"premake/changelog","contentType":"file"},{"name":"premake4.lua","path":"premake/premake4.lua","contentType":"file"}],"templateDirectorySuggestionUrl":null,"readme":{"displayName":"README.txt","richText":"
Author: Ben Henning <b.henning@digipen.edu>\n\nThe goal of this project is to provide a lightweight and portable meta-build\nsystem for generating build systems for various platforms and architectures, all\nfor the SDL2 library and subsequently dependent executables.\n\nFollowing is a table of contents for the entire README file.\n\n[0] OVERVIEW\n[1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS\n[2] STRUCTURE\n[3] SUPPORT ON WINDOWS AND VISUAL STUDIO\n[4] SUPPORT ON MAC OS X AND XCODE\n[5] SUPPORT FOR IOS\n[6] SUPPORT FOR LINUX\n[7] SUPPORT FOR MINGW\n[8] SUPPORT FOR CYGWIN\n[9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS (code samples)\n\n[0] OVERVIEW\n\nThe system is capable of generating projects for many different platforms and\narchitectures. How to generically generate projects is described in the next\nsection. Subsequent sections thereafter describe more specific ways to generate\nprojects and dependencies projects have.\n\nAll of the projects inherently have things in common, such as depending on the\nsame source tree for header and source files. All projects generated will also\nhave both debug and release configurations available to be built. More\ninformation on how to build either will be provided below.\n\nTo view a list of progress on the project, view the changelog.\n\n[1] GENERATING PROJECTS AND COMMAND-LINE OPTIONS\n\nTo receive help with various premake actions and command-line options, or to\nview the options available for the current premake environment, run the\nfollowing command:\n\n ./premake4 --file=./path/to/premake4.lua help\n\nTo construct the project files, run this local command from any command line:\n\n .\\premake4 --file=.\\path\\to\\premake4.lua --to=.\\resultDirectory [opts] [vs2008/vs2010/vs2012]\nOR\n ./premake4 --file=./path/to/premake4.lua --to=./resultDirectory [opts] [xcode3/xcode4/gmake]\n\nopts may be one of:\n --mingw\n --cygwin\n --ios\n\nopts may also include any of the following:\n --alsa : Force the ALSA dependency on for Linux targets.\n --dbus : Force the D-Bus dependency on for Linux targets.\n --directx : Force the DirectX dependency on for Windows, MinGW, and Cygwin targets.\n --dlopen : Force the DLOpen dependency on for Linux targets.\n --esd : Force the ESD dependency on for Linux targets.\n --nas : Force the NAS dependency on for Linux targets.\n --opengl : Force the OpenGL dependency on for any target.\n --oss : Force the OSS dependency on for Linux targets.\n --pulseaudio : Force the PulseAudio dependency on for Linux targets.\n --x11 : Force the X11 dependency on for Linux targets.\n\nAll projects have debug and release configurations that may be built. For IDE\nprojects such as Visual Studio and Xcode, there are configurations in the former\nand schemas in the latter to handle this.\n\nFor make files, the following command line may be used:\n make config=debug\nor:\n make config=release\n\nThe make files also have a level of verbosity that will print all compiler and\nlinking commands to the command line. This can be enabled with the following\ncommand:\n make verbose=1\n\n[2] STRUCTURE\n\nThe structure of the meta-build system is split into three parts:\n\n 1. The core system which runs all of the other scripts, generates the premake\n Lua file that is used to generate the actual build system, and sets up\n premake to generate it. (premake4.lua)\n\n 2. The utility files for performing various convenience operations, ranging\n from string operations and a file wrapper to custom project definitions and\n complex dependency checking using CMake-esque functions. There is also a\n file containing custom dependency functions for checked support.\n (everything in the util folder)\n\n 3. The project definition files, which define each and every project related\n to SDL2. This includes the SDL2 library itself, along with all of its\n current tests and iOS Demos. These files also related to dependency handling\n and help build dependency trees for the various projects.\n (everything in the projects folder)\n\nThe premake4.lua file is lightly documented and commented to explain how it\ninterfaces with the other utility files and project files. It is not extensively\ndocumented because the actual generation process is not considered to be\npertinent to the overall usage of the meta-build system.\n\nThe utility files have thorough documentation, since they are the foundation for\nthe entire project definition and dependency handling systems.\n\nThe project definition files are lightly documented, since they are expected to\nbe self-explanatory. Look through each and every project definition file\n(especially SDL2.lua, testgl2.lua, testshape.lua, testsprite2.lua, and\ntestnative.lua) to gain experience and familiarity with most of the project\ndefinition system.\n\nThe dependency system is very straightforward. As explained in both\nsdl_projects.lua and sdl_dependency_checkers.lua, a function for checking the\nactual dependency support is registered by its name and then referenced to in\nthe project definitions (such as for SDL2.lua). These definitions are allowed to\ndo anything necessary to determine whether the appropriate support exists in the\ncurrent build environment or not. The possibilities for checking can be seen\nspecifically in the function for checking DirectX support and any of the Linux\ndependency functions using the sdl_check_compile.lua functions.\n\nAs far as building the projects is concerned, the project definitions are\nallowed to set configuration key-value pairs which will be translated and placed\ninside a generated SDL config header file, similar to the one generated by both\nautotools and CMake.\n\n[3] SUPPORT ON WINDOWS AND VISUAL STUDIO\n\nCheck the Windows README for more information on SDL2 support on Windows and\nVisual Studio. Current support exists for Visual Studio 2008, 2010, and 2012.\n\n[4] SUPPORT ON MAC OS X AND XCODE\n\nCheck the Mac OS X README for more information on SDL2 support on Mac OS X using\nXcode. Current support should exist for Mac OS X 10.6, 10.7, and 10.8 (as\ntested, but more may be supported). Supported Xcode versions are 3 and 4. It\nsupports building for both i686 and x86_64 architectures, as well as support for\nuniversal 32-bit binaries, universal 64-bit binaries, and universal combined\nbinaries.\n\n[5] SUPPORT FOR IOS\n\nEXPERIMENTAL SUPPORT\n\nCheck the iOS README for more information on SDL2 support on iOS using Xcode.\nCurrent support has been tested on the iOS 6 emulators for iPhone and iPad,\nusing both Xcode 3 and Xcode 4. The iOS project will reference all the Demos\nthe manual project does.\n\n[6] SUPPORT FOR LINUX\n\nEXPERIMENTAL SUPPORT\n\nCheck the Linux README for more information on SDL2 support on Linux. Currently,\nonly a subset of the Linux dependencies are supported, and they are supported\npartially. Linux also builds to a static library instead of a shared library.\nThe tests run well and as expected.\n\n[7] SUPPORT FOR MINGW\n\nCheck the MinGW README for more information on SDL2 support on MinGW. Currently,\nall of the tests that work using the Visual Studio projects also seem to work\nwith MinGW, minus DirectX support. DirectX is not inherently supported, but can\nbe forcibly turned on if the user knows what they are doing.\n\n[8] SUPPORT FOR CYGWIN\n\nBROKEN SUPPORT\n\nCheck the Cygwin README for more information on the progress of supporting SDL2\non Cygwin.\n\n[9] EXTENDING THE SYSTEM TO NEW PROJECTS OR PLATFORMS\n\nIn order to create a new project, simply create a Lua file and place it within\nthe projects directory. The meta-build system will automatically include it.\nIt must contain a SDL_project definition. Projects *must* have source files as\nwell, otherwise they will be ignored by the meta-build system. There are a\nplethora of examples demonstrating how to defined projects, link them to various\ndependencies, and to create dependencies.\n\nHere is an example that creates a new project named foo, it's a ConsoleApp\n(which is the default for SDL projects, look at http://industriousone.com/kind\nfor more information). Its language is C and its source directory is \"../test\"\n(this path is relative to the location of premake4.lua). It's project location\nis \"tests\", which means it will be placed in the ./tests/ folder of whichever\ndestination directory is set while generating the project (for example,\n./VisualC/tests). It is including all the files starting with \"foo.\" from the\n\"../test\" folder.\n\n SDL_project \"foo\"\n \tSDL_kind \"ConsoleApp\"\n \tSDL_language \"C\"\n \tSDL_sourcedir \"../test\"\n \tSDL_projectLocation \"tests\"\n \tSDL_files { \"/testrendercopyex.*\" }\n\nNow, we can extend this project slightly:\n\n SDL_project \"foo\"\n \tSDL_kind \"ConsoleApp\"\n \tSDL_notos \"ios|cygwin\"\n \tSDL_language \"C\"\n \tSDL_sourcedir \"../test\"\n \tSDL_projectLocation \"tests\"\n \tSDL_projectDependencies { \"SDL2main\", \"SDL2test\", \"SDL2\" }\n \tSDL_files { \"/foo.*\" }\n \tSDL_copy { \"icon.bmp\", \"sample.bmp\" }\n\nWe now specified that this application will not work on iOS or Cygwin targets,\nso it will be discluded when generating projects for those platforms. We have\nalso specified that this project depends on 'SDL2main', 'SDL2test', and 'SDL2',\nwhich are other projects that are already defined. We can set the dependency\nto any projects the SDL2 meta-build system is aware of. We also have an\ninteresting SDL_copy directive, which will automatically copy the files\n\"icon.bmp\" and \"sample.bmp\" from \"<sdl_root>/test\" to the directory of foo's\nexecutable when it's built.\n\nLet's take a look at another example:\n\n SDL_project \"testgl2\"\n \tSDL_kind \"ConsoleApp\"\n \tSDL_notos \"ios|cygwin\"\n \tSDL_language \"C\"\n \tSDL_sourcedir \"../test\"\n \tSDL_projectLocation \"tests\"\n \tSDL_projectDependencies { \"SDL2main\", \"SDL2test\", \"SDL2\" }\n \tSDL_defines { \"HAVE_OPENGL\" }\n \tSDL_dependency \"OpenGL\"\n \t\t-- opengl is platform independent\n \t\tSDL_depfunc \"OpenGL\"\n \t\tSDL_files { \"/testgl2.*\" }\n\nThis is a copy of the testgl2.lua file. Most of this is already familiar, but\nthere are a few new things to point out. We can set preprocessor definitions by\nusing the 'SDL_defines' directive. We can also create a dependency for the\nproject on some varied criteria. For example, testgl2 is obviously dependent on\nthe presence of the OpenGL library. So, the only way it will include the\n\"testgl2.*\" (testgl2.c/testgl2.h) files is if the dependency function \"OpenGL\"\nreturns information regarding the whereabouts of the OpenGL library on the\ncurrent system. This function is registered in sdl_dependency_checkers.lua:\n\n function openGLDep()\n \tprint(\"Checking OpenGL dependencies...\")\n \t...\n \treturn { found = foundLib, libDirs = { }, libs = { libname } }\n end\n ...\n SDL_registerDependencyChecker(\"OpenGL\", openGLDep)\n\nThis function is called when it's time to decide whether testgl2 should be\ngenerated or not. openGLDep can use any and all functions to decide whether\nOpenGL is supported.\n\nDependencies and projects can become much more sophisticate, if necessary. Take\nthe following example from the SDL2.lua project definition:\n\n -- DirectX dependency\n SDL_dependency \"directx\"\n \tSDL_os \"windows|mingw\"\n \tSDL_depfunc \"DirectX\"\n \tSDL_config\n \t{\n \t\t[\"SDL_AUDIO_DRIVER_DSOUND\"] = 1,\n \t\t[\"SDL_AUDIO_DRIVER_XAUDIO2\"] = 1,\n \t\t[\"SDL_JOYSTICK_DINPUT\"] = 1,\n \t\t[\"SDL_HAPTIC_DINPUT\"] = 1,\n \t\t[\"SDL_VIDEO_RENDER_D3D\"] = 1\n \t}\n \tSDL_paths\n \t{\n \t\t\"/audio/directsound/\",\n \t\t\"/audio/xaudio2/\",\n \t\t\"/render/direct3d/\",\n \t\t-- these two depend on Xinput\n \t\t\"/haptic/windows/\",\n \t\t\"/joystick/windows/\",\n \t}\n\nThis dependency is, as expected, for DirectX. One thing to note here is even\ndependencies can be dependent on an operating system. This dependency will not\neven be resolved if SDL2 is being generated on, say, Linux or Mac OS X. Two new\nthings shown here are 'SDL_config' and 'SDL_paths' directives. SDL_config allows\nyou to set preprocessor definitions that will be pasted into\nSDL_config_premake.h (which acts as a replacement to SDL_config.h when building\nthe project). This allows for significant flexibility (look around SDL2.lua's\ndependencies, especially for Linux). SDL_paths works like SDL_files, except it\nincludes all .c, .h, and .m files within that directory. The directory is still\nrelative to the source directory of the project (in this case, <sdl_root>/src).\n\nFinally, dependency checking can be done in a huge variety of ways, ranging\nfrom simply checking for an environmental variable to scanning directories on\nWindows. Even more flexibly, the build environment itself can be checked using\nfunctions similar to those provided in CMake to check if a function compiles,\nlibrary exists, etc. The following example comes from\nsdl_dependency_checkers.lua and is used by the Linux dependency in the SDL2\nproject to determine whether the OSS sound system is supported:\n\n function ossDep()\n \tprint(\"Checking for OSS support...\")\n \tif not check_cxx_source_compiles([[\n \t\t\t\t#include <sys/soundcard.h>\n \t\t\t\tint main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]])\n \t\t\tand not check_cxx_source_compiles([[\n \t\t\t\t#include <soundcard.h>\n \t\t\t\tint main() { int arg = SNDCTL_DSP_SETFRAGMENT; return 0; }]]) then\n \t\tprint(\"Warning: OSS unsupported!\")\n \t\treturn { found = false }\n \tend\n \treturn { found = true }\n end\n\nNotice how it uses 'check_cxx_source_compiles'. There are even more functions\nthan this to check and, rather than going in detail with them here, I encourage\nyou to look at the documented functions within ./util/sdl_check_compile.lua.\n\nIn order to support new platforms, start with the minimal configuration template\nprovided and work off of the initial SDL2 project. You may add additional\ndependencies to define other source files specific to that platform (see how\nit's done with Windows and Mac OS X), or you can add special dependencies that\nrely on dependency functions you may implement yourself (see DirectX and\nOpenGL). Dependencies can use the 'SDL_config' directive to specify special\nvalues that can be pasted into the resulting configuration header file upon\ngeneration.\n\nFor more detailed information about the functions supported and how they work,\nlook at all of the Lua files in the util directory, as well as any of the\nexample projects in the projects directory to demonstrate how many of these\nfunctions are used. The information above is only a quick subset of the\ncapabilities of the meta-build system.