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. A list of active tickets on bugs and enhancements is available on the official bug tracker.

Repository setup

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

Tigereye 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/svn/Allegiance and can easily be browsed with your web browser.

The repository contains 3 top-level folders: trunk, tag, branch. The "trunk" represents the main development line.

Currently, the trunk contains the FAZ_R6 code.

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 on February 5th, 2004.
• "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.
• "FAZ_R5" community release on November 16th, 2009.

The "branch" folder contains multiple folders as well; each points to a particular version of code that is currently in development by the FAZ Dev team. There is currently one active branch:

• FAZR6 - This branch contained the latest changes and was used for development. It was used as a "sandbox" for development & contributions (community patches). Trunk was merged with this branch and some features were dropped.

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 Development Zoneleader. He 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 source

Before you can check out the source code, you will need to install an application to work with the Subversion server, allowing you to copy the code onto your machine and send your changes back to the repository: TortoiseSVN is a windows GUI for interfacing with 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 create patches / commit 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.

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

http://svn.alleg.net/svn/Allegiance/trunk/

Most of your development will be performed from this 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.

Note The SVN servers have recently changed address. Development, additionally, has recently changed directory. If you had already checked out Allegiance from the R5 days (or before) you can get yourself up-to-date without checking out everything. First, perform a relocation from http://svn.alleg.net:8080/ to http://svn.alleg.net/. Then, perform a switch to http://svn.alleg.net/svn/Allegiance/branch/FAZR6/. If you are using the console version of Subversion, cd to the repository and perform the following: svn switch --relocate http://svn.alleg.net:8080/ http://svn.alleg.net/ svn switch http://svn.alleg.net/svn/Allegiance/trunk svn update If you are using other clients as suggested, check their documentation for instructions.

Updating your source code 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 will update files that have been changed locally since the latest update, but only if changes can be merged automatically (if lines changed locally and lines changed with the update do not overlap, also referred to as a conflict

.

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 check boxes 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, upload the patch to the relevant ticket. You can set the status of the ticket to "worksforme" and that will notify the dev team that it is ready for inclusion into the next build of the beta server/client and eventually into the release.

More information about creating patches can be found here.

Additional information

The few pictures 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! Keep your models up to date with other artists and submit new ones.

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

Should you have any questions, just post in the Art and ingame content forum and someone will be happy to answer.

Happy coding!

Building the source

If a development environment is already setup, please jump directly to the build instructions by clicking the appropriate link below:

Setup a development environment

You need installed:

• Visual Studio 2008 or 2010
• DirectX SDK
• Windows SDK

Visual Studio 2010 SP1

Warning! Please follow the following installation order: Visual Studio 2010, Windows SDK 7.1, Visual Studio 2010 SP1, Hotfix: Visual C++ 2010 SP1 Compiler Update for Windows SDK 7.1

• Double click on the VS2010\Allegiance.sln in your checkout folder.
• Find the drop down box in the toolbar near the top menu bar, make sure it says FZDebug
  • The FZRetail build flavor should only be used for releases.
• From the Build menu click Build Solution (or press F7).
• Your executables will use the Allegiance/1.1 registry keys, find them in the \objs10 folder, you're done!.

Visual Studio 2008 SP1

• Double click on the VS2008\Allegiance.sln in your checkout folder.
• Just like in #Important notes regarding Express & Starter editions, add your DirectX SDK lib\ARCH and \include.
  • Important: ARCH is either x86 or x64, you can use the $(PlatformShortName) macro, for example G:\DX9\lib\$(PlatformShortName)
• Find the drop down box in the toolbar near the top menu bar, make sure it says FZDebug
  • The FZRetail build flavor should only be used for releases.
• From the Build menu click Build Solution (or press F7).
• Your executables will use the Allegiance/1.1 registry keys, find them in the \objs9 folder, you're done!.

Express & Starter editions

Warning! This probably needs update for R6 and 2010 Express.

• You must also download and install the Windows SDK and DirectX SDK
• In your Express/Starter edition of Visual studio, you have to add the SDK files to your VC++ Directories options manually:
  • Tools->Options...
    • Expand (+) Projects and Solutions->VC++ Directories
      • Select Executable files then add your Windows & DirectX SDK \bin paths, Select Include files, add your Win & DX SDK \include paths and lastly select Library files then add your SDK & DX's \lib paths. For your DX SDK lib path be sure to append x86 to the end. (i.e. G:\DX9\Lib\x86) Pay close attention to these directories, the DX SDK ones especially!

Click on the image to view a larger version.

• ATL/MFC is no longer available in the current Windows SDK, expect errors, you won't be able to build the AllSrv, AllSrvUI or AGC projects. They have become part of none-free editions of Visual Studio 2005/2008/2010 (Standard/Professional/Team System/Premium/Ultimate). [1]
  • You can download an old Windows SDK and copy the include files from ...\include\Win64\mfc and ...\include\Win64\atl into your current Windows SDK include folder. (you can then build everything except AllServUI targeting x86)

• Solution folders are not supported, expect errors immediately when you load, they are mostly harmless.

Registry keys

FAZ Development builds use the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft Games\Allegiance\1.1

The only entry needed to run the Allegiance client is the string ArtPath, the value must point to the full path of your artwork folder and not have a trailing slash. i.e. C:\Program Files\Microsoft Games\Allegiance\Artwork.

The AllSrv server requires its own sub-key named Server inside the 1.1 key. It requires three strings, ArtPath, CfgFile and EXE File (the space between EXE and File is intentional, this is used by AllSrvUI). Perform a "clean" register /w the Component Object Model using the following commands:

regsvr32 /u AGC.dll

regsvr32 AGC.dll

AllSrv -UnRegServer

AllSrv -RegServer

An example of the registry entries found using RegEdit

Troubleshooting

Most issues can be resolved by updating to the latest versions of the Windows SDK and DirectX SDK.

If you have a problem that's not answered in this entry's discussion please feel free to post. This section will be updated with any known resolutions to common problems.

Another helpful entry to read on the WIKI is Code Documentation

Fatal error C1083

If you get this error, make sure you haven't checked out the source to a path with a space in it!

Lastly, if you get Cannot open include file: 'atlconv.h': No such file or directory or "d3dx9.h" or the like, Please read this: Express Editions.

MIDL errors

MIDL error: 'annotation'

1>C:\Program Files\Microsoft SDKs\Windows\v6.0\Include\unknwn.idl(108) : error MIDL2025 : syntax error : expecting ] or , near "annotation" 1>C:\Program Files\Microsoft SDKs\Windows\v6.0\Include\unknwn.idl(108) : error MIDL2026 : cannot recover from earlier syntax errors; aborting compilation

If you get this error, you are using a new version of the Windows headers with an older version of the MIDL compiler.

Fix:

1. Make sure you installed the MIDL compiler when you installed the latest Windows SDK. It should appear under "Program Files\Microsoft SDKs\Windows\v6.0\Bin".

Note: To install the MIDL compiler, you need to select Developer Tools / Windows Development Tools / Win32 Development Tools in the Windows SDK setup wizard. (At least, as of RC1.)

2. In Visual Studio, under Tools > Options > Projects and Solutions > VC++ Directories > Executable Files, add

   x:\Program Files\Microsoft SDKs\Windows\v6.0\bin

to the top of the list.

Thanks Mike Wasson!

Artwork

When running your fresh new shiny build you may crash because you are missing new artwork files. Check out the http://svn.alleg.net/svn/Allegiance/branch/FAZR5Dev/artwork/dev and http://svn.alleg.net/svn/Allegiance/branch/FAZR5Contrib/artwork/dev areas for any additional files you may need.

Debugging

Debugging in Visual Studio

The allegiance solution contains many projects and many of those are not executable. To debug the client or server you must right click the project in the Solution Explorer and select Debug->Start New Instance or Step Into New Instance. The main menu debug option will debug the project set as the Startup project which is not necessarily executable unless you have correctly set it to your target project.

In order to debug your local server in LAN server mode you must first debug the AllSrvUI project by right clicking it and selecting debug->Start New instance. Then from the main menu bar select Debug->Attach->AllSrv.exe

Another more reliable method of debug is Setting up local lobby and server.

Output

Where is the debug output? If you're not seeing any of the debug output you expected, it's because Radar made a command line switch to control the amount of information you get. A listing of the command line switches you need to know are:

-debug (enables output)

-mdllog (shows modeler debug)

-windowlog (shows window debug)

-multi (allows multiple instances)

-adapter <adapterid> (creates the directx device on specified video adapter)

-windowed (starts in windowed mode)

-quickstart <civid> (takes you directly to a game and if possible, sets your faction to specified civilization)

-training (takes you directly to the training menu)

Crashing

When debugging using the FZDebug build, it's important to note some differences from the FZRetail build. Knowing these differences will save you some time. You could consider these "Known Issues":

• The FZDebug builds will generally not give error messages, it will simply break into an assert.
• Some artwork may have incorrect color keys or formatting, the FZDebug build will break into an assert or crash.
• Color codes in user strings (chat, team names) will cause the FZDebug build to break into an assert.
• Visual Studio 2010 Beta 1 may crash while you are debugging with the DirectX Debug runtimes enabled. You may be unable to restart Visual Studio 2010 Beta 1 because it will keep crashing when it loads until you change back to the Retail DirectX runtimes.
• Some DirectShow filters (such as Nero) may prohibit you from debugging with the intro video, Allegiance will exit normally.

FAZ Development	About Free Allegiance Zone Releases: R1 · R2 · R3 · R4 · R5 · R6  · (current)R7 Allegiance R8: What's new? · Build it! Testing Beta: Overview · Testing procedure