Tech/LxEngine/Getting Started on Windows with Visual Studio 2010
From Athile
It may contain inaccurate, incorrect information. Use at your own risk.
LxEngine requires several tools and external in order to built properly. An effort has been made to automatically handle as many of the dependencies as possible, however the initial setup nevertheless still requires numerous downloads and a time-consuming first compilation. Please provide feedback on the forums if you have suggestions on improving the process.
Contents |
Install the Required Software
- Download Visual Studio 2010 Express (if necessary)
- Download Cygwin or msysgit (needed for using "git" for version control)
- Download CMake 2.8 or higher (necessary for setting up the build)
- Download Python 2.7 (required to build Google V8)
- Download SCons 2.0.1 (required to build Google V8)
- Download Microsoft DirectX SDK (required to build OGRE)
Visual Studio 2010
Visual Studio 2010 is required as C++0x features not available in prior versions are used by LxEngine. Note: the Professional editions of Visual Studio 2010 should also work equally well. Other compilers may be supported in the future (especially gcc), but currently VS2010 is the only supported compiler.
Cygwin or msysgit
Cygwin and msysgit both provide a Unix-like command prompts that provides a reliable version of git for version control. Cygwin provides far more services than simply git, but LxEngine requires Cygwin only for git functionality; thus, msysgit may be a preferred choice as it provides solely git functionality without many other services. There are other Windows git implementations, however Cygwin and msysgit are the recommended implementations as they provide an identical interface as with Linux builds allowing for one set of instructions to work in all environments.
More information:
Note when running the Cygwin bash shell if "git" is not a recognized command, simply run setup.exe again, search for "git", and install it to update the cygwin environment.
CMake
CMake is a cross-platform, "make"-like tool that generates build files for a host of different compilers. This allows a single build configuration file to be maintained that will work correctly with multiple compilers (as opposed to maintaining a separate set of Makefiles, Visual Studio project files, etc.). The syntax of CMake may be a bit unfamiliar at first and documentation is often difficult to track down, but ultimately it is a useful tool that is relatively straightforward to use.
More information:
Python 2.7 and SCons
SCons is a build tool (similar to CMake) that is required to build the Google V8 JavaScript Engine, a external component used by LxEngine to support Javascript. SCons in turn is written in Python and requires Python to be installed. Python 2.7 and SCons 2.0.1 are recommended as these versions have been tested with LxEngine. Neither SCons nor Python are directly required by LxEngine, but are required to properly build V8. Users of LxEngine do not need to know SCons or Python, as these are invoked only by build scripts and should not require direct modification.
Initial Source Code Setup
Clone the git respository
First, in a web browser...
- Create a github account
- Fork the 'official' repository by clicking the Fork button on http://github.com/athile/lxengine
Then, in a cygwin bash shell or msys git bash window...
- Clone your remote repository via the private read+write URL:
git clone git@github.com:yourusername/lxengine.git - Add the official branch to your local repository:
git remote add upstream http://github.com/athile/lxengine.git - Change directory to
lxenginefor the next command - Update the submodules in the repository:
git submodule update --init
Alternately, you can download the latest lxengine source via a zip file on github; however, you will also need to download the latest GLGeom zip file and extract it to lx0/dev/libs/glgeom.
Run the Dependencies Script
Warning: This step can take a long-time!
If you are using Visual Studio 2010, there is a batch file that handles downloading and building of all LxEngine dependencies. It is intended to "just work": download, build, move the built files to a standard location that LxEngine's configuration knows about, and exit.
-
cd lxengine\lx0\dev\dependencies -
build_vs10.bat
Note: the batch file must download all dependencies and build them. This can take a very long time as the dependencies include large, complex projects, so please be patient. It is only necessary to build the dependencies once, however, so this is a one time cost to the initial setup of LxEngine.
This batch file is in alpha development and has not seen much real-world testing on different configurations. Please contact us for support issues so that we can improve this batch file to make sure it really does "just work".
First Build
The source code is located in the lxengine\lx0\dev directory. The code is intended to be built from the lxengine\lx0\build directory (this is called an out of source build).
-
cd lx0\build -
gen_vs10.bat -
build_debug.bat -
build_release.bat
The gen_vs10.bat is a simple batch file that will set up the Visual Studio command-line tools and will call CMake and print added information to the user. Experienced users can should examine the batch file to see specifically what it does (which is not much).
The gen_vs10.bat file will generate a Visual Studio 2010 solution file lx0.sln. This can be opened in the IDE and built, or built directly from the command-line via the msbuild lx0.sln command. The build_debug.bat
and build_release.bat batch files are convenience files that simply invoke msbuild with the correct parameters for each build type.
Testing the Build
Assuming build_debug.bat has succeeded, try running some unit tests and samples. All the executables expect to be launched from the "build" directory in order to locate their resource files.
- Try
lxengine\lx0\build>debug\unittest_lxengine.exe. 100% of the tests should succeed - Try
lxengine\lx0\build>debug\sm_raytracer.exe media2\appdata\sm_raytracer\basic_sphere_array.xml
What's Next?
Possibly:
- Search the LxEngine web site for more samples to try
- Try the tutorials on the web site
- Modify one of the samples as a starting point for your own project
- Contribute to the engine itself by adding new core code, bug fixes, samples, unit tests, benchmarks, etc.
- Post of the forums on about the project you're going to undertake with LxEngine for suggestions and help
