premake/BUILD.txt

PREMAKE BUILD INSTRUCTIONS

 Premake is written in a mix of C and Lua. This mix enables many new 
 features, but also makes building Premake a bit more complicated than
 your typical application.
 
 If you downloaded a source code package from SourceForge (as opposed
 to pulling the sources from the repository), you will find project 
 files for all of the currently supported toolsets in the build/ folder. 
 Build the release configuration (the default for the makefiles) and you 
 will find the executable in bin/release ready to go.
 
 If you want to use a debug build instead, or if you pulled the sources
 from BitBucket instead of a SourceForge release, or if you plan on 
 making changes to Premake, read the next section to learn how to 
 prepare the project files.
 
 If you find all of this very confusing and need some help, see the end 
 of this document for contact information. I'll be glad to help. And if 
 you have any suggestions for improving this process, we'd be glad to 
 hear them too.
 

GENERATING THE PROJECT FILES

 If you downloaded a source code package from SourceForge, the project
 files are already included (in build/) and you can skip ahead to the 
 next section. 
 
 If you pulled the sources from BitBucket, you'll need to generate your 
 own project files before you can build. 

 We use Premake to generate the project files for Premake (bootstrapping,
 or eating our own dog food). So in order to generate the project files, 
 you need to have a working version of Premake 4.x installed on your 
 system. You can get it as source code (with pre-generated project files 
 ready to build) or a prebuilt binary from the SourceForge download page.
 
 Once you have a working Premake 4.x installed, the first thing you need 
 to do is to embed the Lua scripts into the application by running this 
 command in the top-level Premake directory:

   premake4 embed
   
 This creates a C file (at src/host/scripts.c) which contains all of the 
 Lua scripts as static string buffers. These then get compiled into the
 executable, which is how we get away with shipping a single file instead
 of one executable and whole bunch of scripts. See EMBEDDING THE SCRIPTS,
 below, for more information.
 
 Now you can generate project files for your toolset of choice by running 
 a command like: 
 
   premake4 gmake    -- for GNU makefiles using GCC
   premake4 vs2008   -- for a Visual Studio 2008 solution
   
 Use the "--help" option to see all of the available targets.
 
 This will create a solution/makefile/workspace in the top-level folder,
 which you can now go ahead and build.


RELEASE vs. DEBUG BUILDS

 Premake can be built in either "release" or "debug" modes. Makefile users
 can choose which configuration to build with the "config" argument:
 
   make config=debug    -- build in debug mode
   make config=release  -- build in release mode
 
 IDEs like Visual Studio provide their own mechanism for switching build
 configurations.
 
 In release mode you can build and run Premake like any other C application
 (once you've embedded the scripts, see the next section).
 
 In debug mode, Premake ignores the embedded Lua scripts and instead reads the 
 latest versions from the disk at runtime. This allows you to change a script,
 and then immediately test it without having to embed or compile first. Speedy!
 But Premake needs some help to find the scripts. 
 
 You can specify the location of the scripts in one of two ways: using
 the /scripts command line argument, like so:
 
   premake4 /scripts=~/Code/premake4/src gmake
   
 Or by setting a PREMAKE_PATH environment variable.
 
   PREMAKE_PATH=~/Code/premake4/src
   
 As you can see, you need to specify the location of the Premake "src"
 directory, the one containing "_premake_main.lua".
 
 
EMBEDDING THE SCRIPTS

 One of the nice things about Premake is that it comes as a single file,
 easy to install or move around. To manage this, we need to embed all of
 the Lua scripts into the executable, so we can deliver just the one file,
 rather than an executable and a whole bunch of scripts.

 Scripts are embedded by running the command
 
   premake4 embed
   
 This copies all of the scripts listed in _manifest.lua into the file
 src/host/scripts.c, where they are represented as a set of static C
 string buffers. This file is then compiled as part of Premake's release
 builds.
 
 So: very important to embed the scripts before each release build!
 
 
CONFUSED?

 I'll be glad to help you out. Stop by the main project website where
 you can leave a note in the forums (the preferred approach), join the 
 mailing list, or contact me directly.
 
   http://industriousone.com/premake

 Enjoy!