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 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 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.
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 are two 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 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.
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! 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 one of the following repository URLs:
http://svn.alleg.net:8080/svn/Allegiance/branch/FAZR5Contrib/
http://svn.alleg.net:8080/svn/Allegiance/branch/FAZR5Dev/
Most of your development will be performed from one of these branches. 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 source code with the team's changes
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
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, contact any member of the FAZ development 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 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:8080/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:
#Visual Studio 2005/2008 Express
Setup a development environment
If you don't already have a development environment, you have three options:
Download & install Visual Studio 2008 Express Edition (iso) (web-install), Visual Studio 2008 Professional SP1 Trial (iso) or Visual Studio 2010 Beta 1 (iso) (web-install)
Lastly, download and install the DirectX SDK , now you're almost ready to start building.
Important notes regarding Express & Starter editions
- You must also download and install the Windows SDK (iso) (web-install)
- 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)
- Expand (+) Projects and Solutions->VC++ Directories
- Tools->Options...
|
| 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 AllSrvUI, AGC, Server or Lobby projects.
- You can download an old Windows SDK and copy the ATL/MFC lib and include files into your current Windows SDK folders. (you can then build everything targeting x86)
- You can remove the atls.lib from the linker include in the Allegiance project:
- In the Solution Explorer, right click on the Allegiance project and left click Properties. Navigate to Configuration Properties, Linker, Input. In Additional Dependencies remove atls.lib.
|
| Click on the image to view a larger version.
|
- Solution folders are not supported, expect errors immediately when you load, they are mostly harmless.
Note For 2005 Express Users Only:
| In this file (vs install location): | \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" /> |
- Skip down to the instructions for #Visual Studio 2005/2008 Express to start building. If you have an Express or Starter edition, please read the section directly below, otherwise, choose your Visual Studio version from the list above.
Visual Studio 6.0
Warning! This development environment is no longer maintained by the FAZ Development team.
The FAZ_R4 tag in SVN contains solution files suitable for building with the VS98 IDE, your millage may vary. Available also to you is the makefile build method. The root makefile reads ONE environment variable necessary for a successful build, %FEDROOT%.
- Set this variable from a command prompt, it will be cleared out when Windows reboots.
- Set it from My Computer as a System variable to get it to "stick", C:\>set FEDROOT=C:\alleg_src.
- You need your entire environment's SDK's within the FEDROOT path in a folder named extern.
Note If you set your FEDROOT as the path in the above example (C:\alleg_src) you should make a directory 'extern' in C:\alleg_src
- Verify your extern directory contains the following structure:
- DirectX SDK (Make file defaults to dx7)
dx7\
include\
lib\
- DirectX SDK (optional)
dx9\
include\
lib\
- The ICQ API
icqapi\
- Site Builder Network SDK
(MSXML includes and UUID.lib go here if not in vc\)
sbn\
include\
lib\
nt50\
- Your MS Visual Studio\Common\MSDev98\Bin files (or equivalent)
SharedIDE\
Bin\
IDE\
- Your MS Visual C++ headers and libraries (or equivalent)
vc\
atl\
inc\
bin\
inc\
sys\
lib\
MFC\
Include\
Lib\
SRC\
- Open a command prompt and navigate to the root of the src directory
- Like this Start->Run... fill the input line with cmd and press return key or click OK.
C:\> cd folder_of_source
C:\folder_of_source> cd src
C:\folder_of_source\src> nmake
- Nmake.exe can be sent a number of optional arguments/targets to build different types of the binaries:
full - specifies the default target (all) and deletes all the Objs for a complete rebuild
debug= - on by default, makes binaries with debugging/trace information
retail= - builds smallest fastest binaries possible
VERBOSE= - Shows commands (breaks MC)
ALLEGIANCE_DEV=1 - recommended you set this for any tests builds
HTTP=1 - define this to enable the auth implementation
USEASGS=1 - uses the ASGS auth stuff (Only if HTTP is defined)
USEAUTH=1 - use the Zone auth stuff (Legacy)
DXn=1 - Use DirectX n SDK instead of default (7)
- Examples from a Command shell
C:\alleg_src\src>nmake retail=
The above example will build most of everything in alleg_src. Your executables will use the Allegiance/1.1 #Registry keys, find them in the /objs folder, you're done!.
These solution and make files are removed in R5.
Visual Studio .NET 2002
Warning! This development environment is no longer maintained by the FAZ Development team.
Stub This article is incomplete This is an article about a topic that should be covered in more detail by the FreeAllegiance Wiki, but is lacking in content.
You can help by improving it!
These solution files are removed in R5.
Visual Studio .NET 2003
Warning! This development environment is no longer maintained by the FAZ Development team.
Stub This article is incomplete This is an article about a topic that should be covered in more detail by the FreeAllegiance Wiki, but is lacking in content.
You can help by improving it!
These solution files are removed in R5.
Visual Studio 2005/2008 Express
Note Download and install Service Pack 1 (2008) (exe) It's very important to keep your development environment up to date.
- Double click on the VS200n\Allegiance.sln in your checkout folder.
- Find the drop down box in the toolbar near the top menu bar, if it says Debug,change this to 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 for VS2008 or \objs for VS2005, you're done!.
Visual Studio 2005 SP1
Note Download and install Service Pack 1 (exe) It's very important to keep your development environment up to date.
- Double click on the VS2005\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, if it says Debug,change this to 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 \objs folder, you're done!.
Visual Studio 2008 SP1
Note Download and install Service Pack 1 (iso) (web-install) It's very important to keep your development environment up to date.
- 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!.
Visual Studio 2010 Beta 1
- Copy the contents of your DX SDK Include and Lib folder to your VS2010 install's VC/Include and VC/Lib folders
- At this time there is no equivalent to Projects and Solutions->VC++ Directories
- 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!.
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 ACG.dll
AllSrv -UnRegServer
AllSrv -RegServer
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
Stub This article is incomplete This is an article about a topic that should be covered in more detail by the FreeAllegiance Wiki, but is lacking in content.
You can help by improving it!
