| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] | [ Search: ] |
Originally written by Philip Wyett philipwyett@blueyonder.co.uk. Last updated 18 May 2005.
In order to successfully compile the Crystal Space 3D Software Development Kit (SDK), you will need a copy of Microsoft Developer Studio .NET or the stand alone version of Microsoft Visual C++ 7 (.NET 2002), Microsoft Visual C++ 7.1 (.NET 2003) or Microsoft Visual C++ 8 (.NET 2005). The Express Edition of MSVC 8 is perfectly suitable to compile Crystal Space, once the Platform SDK was installed (more below).
If you need help with Crystal Space and Visual C++ or just Crystal Space in general. You can subscribe and then post a message to the Crystal Space mailing list. To subscribe see the following site and fill in the form:
http://lists.sourceforge.net/lists/listinfo/crystal-main
All the following libraries and Software Development Kits (SDK) unless stated are not required. However, if you choose not to install them, at compile time you must follow the documented instructions of how to unload these projects from the Crystal Space build process.
All supported versions of Microsoft Visual C++ ship with a version of the Platform SDK that suffices to compile Crystal Space, except the Microsoft Visual C++ 2005 Express Edition, which requires a seperate setup of the Platform SDK. Follow these instructions exactly to set up the PSDK:
http://msdn2.microsoft.com/en-us/vstudio/aa700755.aspx
Before you attempt to compile Crystal Space, you must download and install the “cs-win32libs” archive. This archive contains alot of the third party header, pre-built libraries and dll files used by Crystal Space, i.e. ‘libz-cs.dll’, ‘libjpeg-cs.dll’, ‘libpng-cs.dll’, etc. See cs-win32libs.
Once you have downloaded the cs-win32libs package, execute the binary and follow the setup instructions. You may want to select “VC typical” in the “Select Components” screen. You can further adjust the selection of installed components depending on your actual set up (e.g. install MinGW-related components if you plan to also use CrystalSpace with MinGW/MSYS).
In order to compile Crystal Space at its minimum i.e. the software renderer, you must have at least some form of the DirectX Software Development Kit (SDK) on your system.
Visual C++ 7 and later come with the minimum required DirectX SDK 8.1 files in order to build Crystal Space.
The “cs-win32libs” package also come with minimum headers and libraries that suffice to compile the parts of Crystal Space that utilize DirectX. However, the version included in cs-win32libs is DirectX 7, so you may want to stick to the DirectX 8.1 shipped with VC++ 7.
You can optionally download the latest DirectX Software Development Kit (SDK), which can be obtained from:
http://www.msdn.microsoft.com/directx
Thanks, to the miracle which is Microsoft. If you download and install the latest DirectX Software Development Kit (SDK) and already have Visual C++ installed, it will ask you if you wish to add the paths to the SDK to Visual C++ so it can use it. We recommend you accept when offered this option. If it is not the latest SDK you install you will have to manually point Visual C++ to where you installed the SDK in-order for it to be used. This can be done from the Visual C++ file menu and selecting Tools->Options->Directories. You must add the paths for both the include files and libraries and being that we wish Visual C++ to see and use this new SDK before all possible others on your system, you must click on and drag both paths you have entered to the top of the list.
Crystal Space contains support for Python scripting and thus has projects within it requires that Python be installed on your system. Make sure you add the Python include and libs directories to MSVC so that the compiler can see those files. If you wish to compile with Python support you must install Python 2.2 or later, which can be obtained from:
NOTE: To have parity with one of the latest versions of msvc_libs and take full advantage of the debug elements - you should have Python 2.2.3 or 2.3.0 installed on your system. Whichever version you decide to use, make sure you download the comparable msvc_libs.
To compile Crystal Space, you'll have to perform the following steps. If anything doesn't work, see the Win32 FAQ, MSVC7 FAQ.
Build: 1 succeeded, 0 failed, 0 skipped |
The first app you should try is Walktest. This program shows many of the features of the 3D engine. You can run it by starting it from the windows explorer. It should be at ‘.../cs/walktest.exe’. Don't start it from other locations or from within Visual Studio. It won't find the required files if you do.
If you want to run a debug session, you first have to set the working directory. First select the project you wish to debug and setting it as the startup project. Next open Project->Properties->Debugging and enter the base ‘CS\’ directory as the working directory for debug sessions (for example, ‘C:\CS\’). Be sure to to this for Debug and Release builds.
You can now continue with the next platform-independent step. The remaining Windows-specific sections are only important when you want to compile your own application using Crystal Space.
Note: If you find bugs in the MSVC project or workspace files coming with Crystal Space, don't send fixes for these files to the developers. These files are generated automatically, so your fixes would be useless. Better, send a description of the bug to the mailing list.
The Crystal Space workspace is divided into several projects. They all exist as separate project files (‘*.vcproj’). The projects are collected together by workspaces ‘*.sln’. A workspace will also ensure correct linking between the various projects. There are several workspaces to choose from. Most users should choose the typical workspace, but the others are available for the adventurous.
The workspace uses a prefix system for naming contained projects:
The Libraries are C++ libraries that you can link into your own programs. Some of these libraries are part of the core of Crystal Space. Their output are ‘.lib’ files.
The Plugins are also programming libraries, but they use a special mechanism called SCF as their interface to your program. This separates their interface from the internals of the library and thus allows dynamic linking. In fact, some of the Libraries also use SCF. The rule for the MSVC workspace is simple: The Plugins are projects that build a dynamic library (‘.dll’). You can find more information in the section of this manual dealing with plug-in modules. See section Plugins, Reference counting, Interfaces (SCF).
The Applications are programs using some of these libraries, so they produce ‘.exe’ files.
There is a HOWTO which explains how to create an MSVC7 project file for your own program which utilizes Crystal Space. See section Creating an External MSVC 7, 7.1 or 8 Application.
This is the list of frequently asked questions for the Win32 port of Crystal Space. Please consult this list if you are having difficulty building or using the project.
Q2. I'm using the Visual C++ 2005 Express Edition and I get a lot of
“unresolved symbol” errors for names like
SHGetSpecialFolderLocation@12. What is wrong?
A. These errors indicate a lacking or an incomplete installation of the Platform SDK. Exactly follow the instructions given on Microsoft's “Using Visual C++ 2005 Express Edition with the Microsoft Platform SDK” page: http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/ Also, the instructions don't say that, but if you have Visual C++ open while applying those changes you need to restart it.
A. Some problems with non-latin directory names have been reported (e.g. Hebrew). If your ‘CS’ directory is under such a directory, try to move it to a directory which name has only Latin characters in it.
A. Those files are not part of the Crystal Space project, but they are required to build it. You must get a version of the following packages, most of which can be easily found on the Internet. You can download precompiled versions of these libraries i.e. cs-win32libs or grab the source code and compile it yourself if you prefer. See section External Libraries.
A. Just look above at the question about ‘zlib.h’ and ‘png.h’. It's the same problem, and if you have already done what is explained there, I can't do much for you!
A. Build only the projects you will need. You must build all the Crystal Space libraries, however those you may not need can be unloaded (Right click on the project you wish unload from the build process and click on Unload). Be very careful when unloading projects as some of Crystal Spaces projects e.g. some plugins are dependent on others.
A. Build only the projects you will need.
A. Turning off precompiled headers tends to save a large amount of file space while increasing build times somewhat.
A. For Crystal Space the MSVC project files are generated once every 24 hours, so normally all missing sources should have been added after that time. If you can't wait that long, or the file is still missing, contact one of the Crystal Space developers.
For third party projects it's usually the best idea to contact one of it's developers, they should be able to tell you which file is missing.
A. When I start ‘walktest’ I just get a black screen, maybe with some text output, but after a few seconds it drops back to the normal windows screen without an error.
This shouldn't happen any more, because in most cases now, ‘walktest’ will display proper error messages. Anyway, you should make sure you have set an appropriate directory set (see above). Make sure you have specified the map file in ‘walktest.cfg’ as ‘Walktest.Settings.WorldFile=’ (also keep in mind, that your current directory is, where the executable sits.)
WARNING: could not load plugin `crystalspace.graphics3d.software' WARNING: failed to initialize plugin `crystalspace.engine.3d' FATAL: No iGraphics3D plug-in loaded! FATAL: No iGraphics2D plug-in loaded! Error initializing system! |
A. You probably did not compile everything. Compiling only the ‘.exe’ file is not sufficient! You must also compile all plug-ins you want to use. In the above example the software renderer is missing.
If you are certain that everything is compiled, make sure your working directory is set to ‘CS\’. To do this go to the Project menu. Select Settings and go to the Debug tab. Change the debug executable to ‘X:\CS\appname’ where ‘X:’ is the drive letter where the Crystal Space project is installed. Next set the working directory to ‘X:\CS’. Click OK and you should be all set.
If after doing this, you are still getting the same error, make sure that you have the ‘libz-cs.dll’ installed, the VFS plugin is dependent upon it.
A. When working with Crystal Space, always keep in mind, that this is a multiplatform project. So sometimes not all features will work correct on all platforms. Sometimes a specific port may even be broken due to changes in other ports. Since the introduction of SVN (see SVN) this is usually only for a short time, so if you got your version out of SVN, it usually pays off, to post a message describing the problems to the Crystal Space Mailing List describing you problem and include the exact error messages. If you wait a while, this will probably be fixed, or at least be worked around. See section Mailing Lists.
A. Try sending a note to the Crystal Space mailing list and asking your question there. See section Mailing Lists. Be sure to include any pertinent information, such as the operating system you are using, the compiler, which version of Crystal Space, and any special configuration information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated using texi2html 1.76.