Using TinyXML in a Game Engine - Part 1
My last post showed some functionalities of the engine being created for Cohesion Cubed. This post is going to show you how you can set up TinyXML and explains the basic concept behind C++ libraries.
This particular DevTut assumes only basic knowledge of C++. I go through some intermediate topics, but I'm going to explain them rather in-depth, so anybody familiar with C++ should be able to follow along. If you happened to be a seasoned programmer, you may want to skip a lot of it.
What You'll Need
A compiler. I'm using Visual C++ 2008.
The TinyXML source release. You can get that here.
And like I said, a basic knowledge of C++.
Using Libraries
A library is a lot like the programs you write. It's a collection of classes, structs, functions - any sort of code, which you can re-use and implement inside other code. This is done by "including" the necessary "header files" inside your code, as shown below:
You may recognize iostream. You've included it if you've ever used commands like std::cout or std::cin. Iostream is part of what's called the Standard Library.Its design was heavily influenced by two guys named Alexander Stepanov and Meng Lee.
The Standard Library contains 72 standard headers, of which 17 are deprecated. This includes the Standard Template Library, or STL. The STL is full of useful containers that you should use; including vectors, maps, and associative arrays. You can read more about the STL here.
Types of Libraries
There are two types of libraries you'll come across in your C++ adventures. One is what's called a Static Library, and the other is called a Dynamic Library. The difference between the two is how you link them, and how the program interprets them. Since I'm going to use TinyXML as a static library, here's a quick summary of what a Dynamic Library is:
Dynamic Libraries:
A dynamically-linked library is more advanced than a static one. The name implies its advantages: a dynamic library is much more "dynamic" than a static one. This is due to the fact that a dynamic library is compiled at run-time, and a static library is compiled at compile-time. This has its obvious advantages, such as being able to use the same library for multiple applications.
Dynamic (or shared) libraries, can come in a plethora of extensions. The most common of these is the .DLL file (Dynamic Link Library), but can come in others, such as .OCX (used for libraries containing ActiveX controls), or a .DRV, which is for legacy system drivers.
Usually, a .lib file (covered shortly) is used with the .DLL file, as an import library. This can make it easier for your program to interface with it. On linux, the import library is stored within the .SO file.
Now, enough about Dynamic Libraries. Let's get on with this guide.
Implementing TinyXML
Like I said earlier, we'll be using TinyXML as a static library. I won't write a summary for it like I did for dynamic libraries. I'll explain it as we implement it. I won't waste any words; we shall begin >:3
The Steps to Success:
Compile the library.
Create Test Application
Create the proper directories.
Link headers and libraries.
Test library.
Those are the 5 steps we're going to take to accomplish our goal. Let's get started.
1. Compiling the Library:
First, we're going to create a new console application in Visual Studio. Name it TinyLib, or something to that effect. Then hit OK.
On the window after that, click Next. Then click on Application Settings (1). Then click the checkbox beside Static Library (2). Then, click the checkbox beside Precompiled Header (3). We don't want a precompiled header.
You should end up with something like this:
Visual Studio creates three project filters and one .txt file for us. The Header Files folder is for .h and .hpp files. The Source Files folder is for .cpp files. So let's add the ones we need from the TinyXML Source.
Right click on the Header Files filter and go to Add->Existing Item.
Browse to where you extracted the TinyXML source files. Example: C:\libs\tinyxml
Find tinyxml.h and tinystr.h in this folder and add them to your project.
Then do the same thing for the Source Files filter, adding in the 5 .cpp files.
To make this easier, you can right click on the explorer window and go to Arrage Icons By->Type. Most of the time, a libraries source will contain a folder called src, or something similar. TinyXML happens to encapsulate all their source files in the root folder, making it rather easy to find.
Now you should have a project that looks something like this:
Okay, so you've added in the code that our static library will contain. Now we're ready to compile it. Go to Build->Build Solution. You should see a Build Succeeded message in the bottom left-hand corner of the IDE.
Congratulations, you've compiled TinyXML and possibly, your first library. Step one accomplished. Now onto step two.
2. Creating the Test Application
Create a new project in Visual Studio just as before. But this time, go with a console application. Use a precompiled header if you wish or if you don't know how to write an entry point yourself.
Once you have a standard console project with a main source file, you've accomplished Step Two. You can check the picture below for reference:
3. Creating the Proper Directories:
As a programmer, it's good practice to be organized. This is especially true when dealing with large amounts of code, which almost always include libraries.
So what we're going to do now is create the folders that will store the library and header files we're going to use in our test application.
First, open explorer and browse to the project directory of the TinyLib project. Then, open another explorer window and browse to the project directory of Test Application. Arrange both windows so that you can see them each clearly.
Then in the Test Application project folder, make two folders: lib and include:
Next, in the TinyLib project directory, open up the Debug folder. In it, you should find TinyLib.lib. Copy and then paste this into the lib folder that you just created in your test application directory. This step is shown below:
That takes care of the library file. Now you have to add the header files. Do this by browsing to the where you unzipped the TinyXML source to. Copy the two header files into the include folder we created in the test application project directory.
Upon moving all the aforementioned files, you should now have two header files in your include folder, and one .lib file in your lib folder, in your test application directory.
If you've done this, then you've successfully completed step number 3. Congratulations.
Step 4: Linking the Headers and Libraries
Okay, this is the most tedious part. Luckily, if you do it a lot, you become super fast at it. So here we go.
First open up your test application with Visual Studio. On the upper toolbar, click Project->Test Application Properties. Then find C/C++->General. Add the include folder we created in this project's directory to the Additional Include Directories list.
The image below demonstrates this. (I've named my project XmlTest):
Now browse to Linker->Additional Library Directories. Add the lib folder we created to the list in the same way as above.
(Note: You may need to compile your project before Linker becomes visible.)
Now find Linker->Input. Click on Additional Dependencies and add TinyLib.lib, like so:
Once you have included the lib directory, the include directory, and the lib file, then you've completed step 4. Good job. Now to test the library.
Step 5: Testing the Library
You should always test whatever library you just linked so that you can be sure you did it correctly. TinyXML comes with a test file, which you can use. But we're just going to include the header and see if we get any errors.
So add "include <tinyxml.h> and include <tinystr.h> to the top of your main cpp file. Then hit F5. Your project should compile.
Congratulations, you've compiled and linked TinyXML. You can do the exact same thing to any code that you write, turning it into a static library.
Be sure to stay tuned for the next part in this series, where I'll show you ways you can implement TinyXML to help with a project like a game engine.
Have fun.