Getting Started With Premake29 Oct 2016
This initial post will cover what Premake is, why you should use it, and provide an example project you can download and try out for yourself.
Future posts will expand on the provided example by walking through the process of setting up more complicated premake configurations, such as cross-platform libraries and dependencies.
Why Use a Build Configurator?
Maintaining separate Makefiles and Visual Studio Solution files for cross-platform projects, or storing Visual Studio Project files in version control such as Git can be a pain.
- Writing Makefiles for all but the simplest projects is tedious without automation, and can be difficult to debug.
- Visual Studio Solution and Project Files are pre-generated, but are not designed to be easy to edit by hand, so resolving merge conflicts with them can be frustrating.
Several build tools exist that allow us to avoid these issues. CMake is widely used, but tends to have a high learning curve and uses a Proprietary scripting language.
This post will discuss Premake5: A Lightweight, Open-source, Lua-based alternative to CMake.
What is Premake?
As with CMake, Premake allows you to define the structure and contents of your project and then dynamically generate whatever build files (Makefiles, VS Solutions, Xcode Projects, etc) you need at the time.
At the core of Premake is a premake5.lua file that describes your project (what programming language it uses, where to find source files, what dependencies it has, etc.). ‘premake5.lua’ is to Premake what is ‘Makefile’ is to GNU Make, and what ‘doxyfile’ is to Doxygen.
Because premake5.lua allows you to uniquely generate whatever build files you need in seconds, you no longer need to version them in your repository. You configure your version control to ignore the build files, and version the premake5.lua file instead. Resolving merge conflicts on a premake5.lua file is far more sane than on a Visual Studio project file.
Once you have a premake5.lua file, you can run the premake executable to generate your desired project files. For example:
- To generate a Makefile on Linux you run
- To generate a VS 2015 Solution on Windows you run
This guide will be covering Premake5, the latest version. Official documentation can be found on in a wiki on github: https://github.com/premake/premake-core/wiki.
NOTE: if you ever search the web for premake questions, and see older resources on bitbucket or the ‘Industrious One’ forums, please ignore them. They are old and almost certainly out of date, often referring to Premake 4.
A Simple Premake Example
To help with the learning curve, I’ve provided you with an example Premake5 Project that will compile a simple ‘hello world’ program for Linux, MacOS and Windows: https://github.com/JohannesMP/Premake-for-Beginners
To use premake you will need to be familiar with basic LUA syntax. You will not need to install anything to make LUA work for premake - It is entirely contained in the tiny premake5.exe executable.
If you have never used LUA before, you can refer to the LearnXinYminutes LUA page, or The Lua Crash Course. I have also included a heavily commented version of premake5.lua which covers the relevant basics. You will not need to know more than basic LUA syntax.
- Download the repository to your preferred location.
Buildcontains the premake files and binaries. Please note that the binaries are included for convenience - you can delete them if you copy the one for your OS to a location on your PATH.
Build/premake5.luadescribes the project and allows you to generate the Project files you want.
Build/premake5.lua_commented.luais the same file, but heavily commented for those that have never used LUA before, and goes into more detail explaining what premake’s functions do.
Sourcecontains the source code, in this case a simple hello world program in C++.
Build a Visual Studio project on Windows
- cd into the
dirshould list the premake5.lua file)
premake5 vs2015– this will generate a
project_vs2015folder containing the VS solution and project files.
- You can double click the
.slnfile to open the project in visual studio and compile it.
To Build a Makefile on Mac or Linux
- cd into the
ls -lashould list the premake5.lua file)
./premake5_macfor mac) – this will generate a
project_gmakefolder containing two Makefiles.
- You get one master
Makefile, and one
PROJECTNAME.makefile per project.
- If you run
make helpthe console output will tell you how to build specific configurations. For example, to build a 32bit release you run
- For debugging, you can have verbose output by running
make verbose=1 ...
- You get one master
- cd into the project folder and run
Check out the Output
- For both Windows and Linux, the output directory containing your compiled binary will be named
bin_CONFIGURATIONbased on your selected configuration (Release/Debug, 32/64 bit).
- For example, it will be named
bin_Debug_x64for 64bit Debug.
Please read through the premake5.lua_commented.lua file for a detailed breakdown of everything that is happening in the file.
- The hello world program on the official Wiki: https://github.com/premake/premake-core/wiki/Your-First-Script
- A more advanced project that uses dependencies (GLFW to render an opengl window) that should work cross-platform: https://github.com/JohannesMP/premake5_crossplatform_example