Downloading and building the source

Downloading the source

This entry describes how the FAZ Dev team has organized the code in their central repository, how you can get a copy of it, and how you can submit code you wrote to be included in the next release of Allegiance.

Repository Setup

Before this section explains how to do download the source code & artwork, here's a little bit of background on how we're set up.

Thalgor has graciously set up a Subversion repository on one of his servers to allow all Allegiance developers to collaboratively develop additions and enhancements to Allegiance. This repository is located at http://svn.alleg.net:8080/svn/Allegiance and can easily be browsed with your web browser.

The repository contains 3 top-level folders: trunk, tag, branch. The "trunk" will always point to the latest stable code that has been verified as being "Good." Every time the development team releases a new version, that code will be placed here for reference.

Currently, the trunk contains the FAZ_R4 code released on November 1st, 2007.

The "tag" folder contains multiple sub-folders; each points to a particular revision of Allegiance's source code throughout it's development. The purpose of the tag folder is to keep a list of milestones throughout Allegiance's history. Currently there are 5 tags within this folder:

• "msoriginal" which will always point to the original source code provided by Microsoft in 2002.
• "FAZ_R1" community release on March 1st 2006.
• "FAZ_R2" community release on August 1st, 2006.
• "FAZ_R3" community release on December 14th, 2006.
• "FAZ_R4" community release on November 1st, 2007.

The "branch" folder contains multiple folders as well; each will point to a particular version of code that is in development by the development team. Currently there are two active branches:

• FAZR5Dev - This branch is being used to test the official changes being made for the 5th release of FAZ.
• FAZR5Contrib - This branch contains the latest commits, used for "sandbox" development & contributions (community patches).

As the development team and the community works on the source code, we will copy the source code to our machines, and change it locally. When we've verified our personal changes are "good" we will create a patch file containing all changes made by us from the original, send it to Dogbones or Tigereye. They will merge it with the appropriate branch of code. Once the team agrees that we are ready for a release, we'll update the trunk to point to the "latest good" and tag the update in the tag folder.

Checking out the sourcecode

Before you can check out the source code, you will need to install two pieces of software.

Subversion is a command-line program that interfaces with the repository, allowing you to copy the code onto your machine, and send your changes back to the repository. TortoiseSVN is a windows GUI for Subversion. It makes it easy for you to keep your downloaded source up-to-date with the changes made by the rest of the team, and allows you to package your changes for submission.

Tortoise SVN's checkout screen.

Once you've downloaded and installed the necessary programs, you can check out the latest code by creating a blank folder where you want the source code to be on your machine.

Warning! Somebody forgot to escape their paths. Make sure there are no spaces in the path you are checking out to.

Open that new folder, right click within it, and click SVN Checkout. In the dialog that pops up, use the following repository URL:

http://svn.alleg.net:8080/svn/Allegiance/branch/FAZR5Dev/

Most of your development will be performed from the FAZDev branch. When you click "OK" the latest code will be copied to your computer into the folder you created.

Additional information on checking out code can be found here.

Updating your sourcecode with the team's changes

Sample output for the SVN Update command

Whenever someone submits a patch and it is applied to the repository, your code on your machine is not updated. You will need to tell Subversion to take the changes made to the collective code and apply them to your own. This is called "Updating"

To Update your code, right click the folder that has the Allegiance source and choose SVN Update.

Note This does update files that have been changed locally since the latest update only if changes can be merged automatically (lines changed locally and lines changed with the commit do not overlap.

.

More information about updating can be found here.

Fixing mistakes you've made

While changing the code, you may accidentally make mistakes and save over the "good" originals when you didn't mean to. It's okay! You don't need to re-download the whole thing to get back to the original.

Simply right-click the top-most folder that contains your checkout, and choose TortoiseSVN-->Revert... Tortoise will prompt you by warning that you will lose all changes made to the originals. When you click OK, all of your files are reverted right back to the way they were when you first checked them out.

Submitting your changes to the repository

The Create Patch screen.

When you have completed changing the checked-out code on your machine and after having tested your changes it's time to give them to the rest of the team.

Right-click the folder that contains your allegiance source, and choose Create Patch... You'll get a screen that asks you to choose all files that should be submitted with the patch.

Simply check the checkboxes beside all files that should be included, then click OK. You'll be prompted where to save the .patch file on your machine.

Once you have the patch file created, contact any member of the FAZ Dev team and get it to them. Either by email (Zip it up before emailing!!) or other file transfer. PM Dogbones to get your code into the next release.

More information about creating patches can be found here.

Additional Information

The few pictures I've used in this post came from the TortoiseSVN Documentation. It's a very thorough set of documentation that explains every function available in Subversion, and how to use them with TortoiseSVN.

Artwork Repository

For those 3D artists out there, we have a separate repository just for you guys to keep your models up to date with other artists, and submit new ones.

You can browse all of the artwork available from MS's release of the code at http://svn.alleg.net:8080/svn/AllegArt/branch/FAZDev/

Should you have any questions, just post in the Misc. Development forum and someone will be happy to answer.

Happy coding!

Building the Source

Microsoft Visual C++ 2005 Express and 2008 Express

1	Download and install the required software

You will need:

• Microsoft Visual C++ 2005 Express, the free edition of Microsoft’s Visual C++ development environment.. Make sure you tick the "Graphical IDE" during installation.
• Platform SDK
• DirectX SDK. Note that versions after June 2007 will not work.

Check out the Allegiance source code if you haven't already done so.

Note For the purposes of this explanation we will assume: You installed the Platform SDK in C:\psdk\ You installed the Direct X SDK in C:\dxsdk\ You installed Visual C++ in C:\msvc2005\ You checked out the source code in C:\alleg\ Obviously you will need to replace these with the paths you really used. This KB entry was written for the most recent versions of both SDKs, which were R2 of the Platform SDK and the April 2006 version of the DirectX SDK.

2	Configure your path

Now open C:\Alleg\Allegiance.sln. If Visual C++ installed correctly it should start, load the project and display and error about “Solution Folders”, which you can safely ignore.

We will need to add a few folders to the VC++ path. From the Tools menu, pick Options. Under Projects and Solutions go to VC++ Directories.

From Show Directories For pick:	Executable files	Include files	Library files
and add this, in order, to the top of the list:	c:\psdk\bin	c:\psdk\include c:\psdk\include\gl c:\psdk\include\mfc c:\psdk\include\atl c:\dxsdk\include	c:\dxsdk\lib\x86 (*) c:\psdk\lib

(*) Skip this if you are building on a 64 bit platform.

Confirm all changes and close all dialogs.

3	Change your build target

Now find the dropdown box in the toolbar which currently says Debug and change this to FZDebug^[1].

4	Fix the dependencies

Note Skip this step if you are using VC++ 2008 Express.

In this file:	c:\msvc2005\VC\VCProjectDefaults\corewin_express.vsprops
replace this line:	AdditionalDependencies="kernel32.lib" />
with this line:	AdditionalDependencies="kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib" />

5	Build the source

From the Build menu click Build Solution.

Warning! If you are using the R2 version of the Platform SDK (current as of September 2006), then when you build you will encounter a couple of bugs in the SDK. When you try and build, you should see a large number of errors looking something like: 'i' : undeclared identifier Double-click on one of these errors, it should take you to a line in a header file which declares a loop: for (i = 0; Declare a type for the i variable. Add the word “int” before the i so that it reads: for (int i = 0;

6	Fix more dependencies

6.1	Remove the atlthunk.lib dependency

In this file:	c:\psdk\include\atl\atlbase.h
find this line:	#pragma comment(lib, "atlthunk.lib")
and comment it out:	// #pragma comment(lib, "atlthunk.lib")

6.2	Remove atls.lib from the linker settings

In the Solution Explorer, right click on the Allegiance project and pick Properties. Navigate to Configuration Properties, Linker, Input. In Additional Dependencies remove atls.lib.

Done!

The build will still fail on the AllSrvUI project, complaining about a missing header file afxmsg_.h. However, all the other projects should build, including the client -- you should have a copy of Allegiance.exe in c:\alleg\objs\FZDebug\WinTrek.

Microsoft Visual Studio 2008

1	Download and install the required software

You will need the DirectX SDK. Note that versions after June 2007 will not work.

Check out the Allegiance source code if you haven't already done so.

Note For the purposes of this explanation we will assume: You installed the SDK in C:\dxsdk You checked out the Allegiance source in C:\alleg Obviously you will need to replace these with the paths you really used.

2	Configure your path

Now open the file C:\Alleg\VS2008\Allegiance.sln.

We will need to add a few folders to the VC++ path. From the Tools menu, pick Options. Under Projects and Solutions go to VC++ Directories.

From Show Directories For pick:	Include files	Library files
and add this, in order, to the top of the list:	c:\dxsdk\include	c:\dxsdk\lib\x86 (*)

(*) Skip this if you are building for a 64-bit platform.

Confirm the changes and close all dialogs.

Now find the dropdown box in the toolbar which currently says Debug and change this to FZDebug^[2].

3	Build the source

From the Build menu click Build Solution.

Done!

All the projects should build, including the client -- you should have a copy of Allegiance.exe in c:\alleg\objs\FZDebug\WinTrek.

Footnotes

1  ·

If you want to build optimized EXEs that cannot be debugged easily, choose FZRetail instead.

2  ·

See previous note.