[Sxengine-devs] Source tree roadmap & Building

[TerryP <spi...@us...>]

I thought it would be a good idea to write something about what the source
tree will look like as commits move on, given that an intro to subversion
repository structure was just done lol.

There's many ways to build a project, normally it is done "In tree" or "Out
of tree". In tree typically means the compiler is told to put it's files
next to the source code. It's rather messy. Out of tree simply has the
compiler put the generated files some where else. There are even more ways
to lay out the sources.

At least for me, my "Home directory" is shared between computers and
different operating systems, I also test with several compilers; so in tree
builds don't really "Do it" for me unless it applies magic to the problem.
When you combine the process of building and distributing a larger project,
having separate directory structures for each phase starts to look pretty
sweet.


This is the kind of structure I've set things up for the "Source tree":

   - Build/
   - Dist/
   - Source/
   - Vendor/

SxEngine code goes in the Source folder and third party stuff goes in
Vendor/vendorname. Sticking with that branching example from the subversion
thread, vendors/ogre3d/release-1.7 would get merged into
branches/ogre3d-backend/Vendor/ogre3d/src. This distinction between <branch
path>/Source and <branch path>/Vendor makes it perfectly clear whether
you're looking at part of the engine or not. It also makes accidentally
merging the branches the wrong way a little harder.

Temporary files created by building the source code ends up under the
"Build" tree. Because C++ object files and what not tend to be specific to a
given CPU, OS, and compiler: all those files go in
Build/architecture/os/compiler. I.e. if you build Source/module/foo.cpp you
may get Build/x86/win32/msvc/module/foo.obj. This allows having any number
of side by side builds for an arbitrary number of configurations very easy,
as is deleting all the temporary files!

Results of compilation end up in the "Dist" tree. For the same reason as
above it follows the Dist/architecture/os/compiler structure. The concept is
when you build the project, distributing the files should be as easy as
zipping up the right folder in Dist/ and unzipping it on the users computer.
When headers and import libraries are included in the dist files, it also
makes building your own game with the engine less painful IMHO, and frees
the game of having to care about the engines build system. Releasing an SDK
becomes easier!

If you have any better ideas then the Build, Dist, Source, and Vendor trees
thing, I'm open to listening. Over the years it's the more effective way
I've found for combing C/C++ with cross platform work.



Why I chose rake over using more popular solutions like CMake or SCons, is
quite franky in my experience they make doing that kind of build
exponentially more work in filthy hacks and kludges than they actually solve
in headaches. We obviously can't use Visual C++ for Linux builds (et. al.),
so VS project files are useless beyond our workstations. Such IDEs are
however still great tools for writing the code and setups can be committed
to subversion. Maintaining separate sets of makefiles/project files per
development environment is also an *anti*-solution.


Enter rake.


It's essentially a make <http://en.wikipedia.org/wiki/Make_(software)> tool
written in Ruby and using ruby syntax. Requiring rake for a build is
certainly a lot less weight than forcing a specific development environment
(which are not all created equal). It's also faster than scratch writing a
custom program for the job. Ruby 1.9 includes rake, and it can be installed
separately as a gem for Ruby 1.8. I also used the Platform gem to make life
easier, it's all easy as pie to setup. Like traditional makefiles, rake can
also support several compiler tool sets in the sense that it can
conditionally include a separate file describing the build configuration.

Because knowing a lot of Ruby to build C++ is silly, I adapted it to use
YAML to store such settings. The Builder object automatically does this when
created. A YAML file looks like this:
http://en.wikipedia.org/wiki/YAML#Sample_document so it's child's play to
edit most compilation settings.

A little applied engineering resulted in a rake infrastructure that coops
with the desired multi-tree source/build/dist structure very well and keeps
the Ruby hacking to a bare minimal where ever possible (and is getting
steadily better).

The way this rake stuff has been done, it can actually be adapted to any
language. It's only been tested with C and C++, but the scripts can be used
just as well for projects written in languages like Java, C#, Visual Basic,
Lisp, and Go. Since it's so useful, at least to me personally, there is an
unrelated git repo  <
http://github.com/Spidey01/rake-build-infrastructure/tree/Examples > to make
using the scripts on new projects faster. When SxEngine is setup, I'll push
the updated code/docs for the build scripts back out to the hub.



In essence building the SxEngine will be a matter of running rake.

> rake target

If you've ever used make, it works the same way, e.g. make clean. Under Ruby
1.9 var=value arguments are possible, such as:

> rake toolset=mingw target

Using an IDE such as Visual Studio, NetBeans, Eclipse, Code::Blocks, an any
of the other dozen or so I've worked with, become just a matter of telling
it to run rake when you hit "Build". Vim/Emacs also work fine. If invoked
just as rake, the default settings just build the game engine and its
dependencies using the most natural toolkit. Visual C++ is assumed for
Windows.


Being able to commit IDE specific files that handle running rake is also a
handy to share IDE settings ;).

-- 
         TerryP / Spidey01
Just Another Computer Geek.