AuroraPipeline/premake
1
0
Fork 0
Code Issues 1 Pull Requests Projects Releases 1 Wiki Activity

Update build instructions for new embedding logic

Browse Source
This commit is contained in:
Jason Perkins 2014-10-06 16:13:44 -04:00
parent 67f6fba149
commit 37e564b23c
1 changed files with 60 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
BUILD.txt
View File

@ -1,127 +1,90 @@
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.
Premake is written in a mix of C and Lua. A small host executable,
written in C, launches the app and prepares the environment, at which
point control is handed off to a Lua script. Almost all of Premake is
written in Lua scripts, which allow it to be easily extended and
customized. The catch is that it is slightly more complicated to build
it than your typical C/C++ 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 find all of this very confusing and need some help, visit the
Premake website for help and community links. We will be glad to help!
BUILDING FROM A SOURCE PACKAGE
If you downloaded a source code package (as opposed to pulling the sources
directory from the repository) you will find project files for all of the
officially supported toolsets in the build/ folder. Build the release
configuration and you will be ready to go. For makefiles:
$ cd build/gmake.unix
$ make
$ make config=release
The binaries will be left in the bin/release directory.
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, I'd be glad to
hear them too.
The binaries will be placed in the ./bin/release directory.
GENERATING THE PROJECT FILES
BUILDING FROM THE REPOSITORY
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 have pulled sources from the Premake source repository, you will need
to embed the scripts into a C source file so they may be built into the
executable, and also generate the project files for your chosen toolset. In
order do either of these things, you will need a working Premake executable.
If you pulled the sources from BitBucket, you'll need to generate your
own project files before you can build.
The easiest way to get an executable is to download one of the prebuilt
binaries from the project website. If that isn't possible, or if not binary
is provided for your platform, you can build from a source package as
described above, as they also include pre-generated project files.
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 5.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 available, you can generate the project
files for your toolset by running a command like the following in the
top-level Premake directory:
Once you have a working Premake 5.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:
$ premake5 gmake # for makefiles
$ premake5 vs2012 # for a Visual Studio 2012 solution
$ premake --help # to see a list of supported toolsets
premake5 embed
If this is the first time you have built Premake, or if you have made
changes to the Lua scripts, you should prepare them to be embedded into the
Premake executable.
$ premake5 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.
of a whole bunch of scripts.
Now you can generate project files for your toolset of choice by running
a command like:
premake5 gmake -- for GNU makefiles using GCC
premake5 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.
You should now have a solution/makefile/workspace in the top-level folder,
which you can go ahead and build.
RELEASE vs. DEBUG BUILDS
RUNNING THE TESTS
Premake can be built in either "release" or "debug" modes. Makefile users
can choose which configuration to build with the "config" argument:
Once you have built an executable, you can verify it by running Premake's
unit test suites. From the top-level Premake folder, run:
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:
premake5 /scripts=~/Code/premake5/src gmake
Or by setting a PREMAKE_PATH environment variable.
PREMAKE_PATH=~/Code/premake5/src
As you can see, you need to specify the location of the Premake "src"
directory, the one containing "_premake_main.lua".
$ bin/release/premake5 test
EMBEDDING THE SCRIPTS
RUNTIME SCRIPT LOADING
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.
If you are modifying or extending Premake, you can skip the embedding
and compilation steps and run the scripts directly from the disk. This
removes the build from the change-build-test cycle and really speeds up
development.
Scripts are embedded by running the command
Assuming you have already built an executable, you just need to tell
Premake where to look for the scripts. If, for example, you wanted to
run from the top-level Premake folder, you could do this:
premake5 embed
$ bin/release/premake5 --scripts=src test
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.
If you are running from a different location, adjust value for the scripts
argument accordingly.
So: very important to embed the scripts before each release build!
If you find yourself doing this repeatedly, or if you want Premake to be
able to find other, custom scripts, you can also set a search path with the
PREMAKE_PATH environment variable. Set it just like you would set your
system PATH variable.
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!