SWG:ANH - Contributor's Guide

SWG:ANH Server Documentation Discussion Board

SWG:ANH - Contributor's Guide

Postby apathy » June 23rd, 2010, 10:21 pm

The SWG:ANH flagship project, MMOServer, is a beast spanning hundreds of files and over 145,000 lines of code, for anyone interested in getting involved those are some daunting figures. It also poses a question for many developer's who are just getting their start: "Where do I start?"

This guide will help to answer that question by providing a step-by-step path to setting up the SWG:ANH developer environment. When all is said anyone who has followed this guide will have a checkout of the latest development version of the source code and all of the tools necessary to start the server and log in. Now, enough with the forward introduction, time to get started!

Part I: Installing Software

To get started a number of applications need to be installed and configured in order to check out and build the source, in addition to managing the database that runs alongside the server itself. Thankfully, all of the tools used by the SWG:ANH team are free (as in beer) and easily downloaded off the web. Some of these applications require specific settings during installation so be sure to follow along carefully!

1] Microsoft Visual Studio 2010

Any edition of Visual Studio 2010 can be used for SWG:ANH development, including the freely available Express edition:

http://www.microsoft.com/express/

Install Visual Studio 2010 with the default settings and that's all there is to this step!

2] MySQL Community Server

MySQL is a freely available database server that is used extensively by the MMOServer project. Download the latest edition for Windows from the following location:

http://www.mysql.com/downloads/mysql/

During the installation select the "Typical" setup type, this will install all of the necessary MySQL components needed to run the server. Once the installation has completed an option to "Configure the MySQL Server now" will be automatically selected (if it is not automatically selected then check the box accordingly) and clicking finish will bring up the configuration utility.

All of the default settings should be left "as-is" during this configuration save one: the "Include Bin Directory in Windows PATH" option MUST be selected. After selecting a root password the custom configuration will be installed and the MySQL service started.

* Be sure to select a root password that is both secure and something you can remember!


3] MySQL GUI Tools

In order to work with the MySQL database used by the MMOServer project you'll need the MySQL GUI Tools (or a similar application). MySQL GUI Tools can be downloaded freely from:

http://dev.mysql.com/downloads/gui-tools/5.0.html

4] Git on Windows (msysgit)

The last piece of software needed is the Git client. Git is the Source Control Management tool used by the SWG:ANH to collaborate on this expansive project. Download the latest full version of the installer at:

http://code.google.com/p/msysgit/downloads/list

There are a number of available downloads so be sure to find the latest version that's marked as "Full installer for official Git" in order to get the correct one.

During the installation follow the screens below to ensure all the appropriate options are selected. Options not shown on these screens should be left at their default settings.

Image

Image


5] Star Wars Galaxies and the SWG:ANH Client

The use of the SWGANH client requires a valid live installation of the Star Wars Galaxies game client: http://www.starwarsgalaxies.com/

Next download and install the official SWG:ANH client: http://github.com/downloads/swganh/mmoserver/anhclient_setup.exe

If using an older version of the Star Wars Galaxies game client or if the install being used was copied over from another machine the installer may ask for an Star Wars Galaxies installation directory. Navigate to the directory with the SwgClient_r.exe file and select Continue (by default this is generally C:\Program Files\StarWarsGalaxies\).

Once the SWG:ANH client is installed, navigate to the installation directory and modify the swg2uu_login.cfg file and set the loginServerAddress0 setting to localhost.

Part II: Fork, Checkout and Build the Server

The SWG:ANH team uses GitHub as the central source of collaboration for development of the MMOServer project. In order to contribute to the project a GitHub account is required. In addition, GitHub uses SSH for authentication when committing and checking out from private repositories. Be sure to follow these two quick guides from GitHub's help section to avoid any issues later on:

http://help.github.com/msysgit-key-setup/
http://help.github.com/working-with-key-passphrases/

Next, while signed into a working GitHub account navigate to the main SWG:ANH Project at: http://github.com/swganh/mmoserver

Near the top of this page is a Fork button, hit this to make a personal fork of the SWG:ANH project. These forks are how all members of the team and the community developers collaborate with each other and share their code. Once the fork of the MMOServer project is complete navigate to http://github.com/swganh/mmoserverdb and create a fork from it as well. This is the database used by the MMOServer as it's name suggests.

With a GitHub account and both of the main projects forked it's time to get started! To do that, open the Git -> Git Bash application from the Start Menu. This will open a command prompt which is the main interface for interacting with Git.

* For more information on Git and how to use it see the resources available at the end of this guide for further information! The guide from this point expects a basic working knowledge of Git and is not a complete guide to using an understanding it.


* NOTE: These commands only need to be run during the initial setup. Please see the referenced Git documentation at the end of this guide for information on the day-to-day commands.


Next run the following commands to clone the main SWG:ANH MMOServer project and build it.

Code: Select all
git clone git@github.com:USERNAME/mmoserver.git
cd mmoserver
git remote add swganh git://github.com/swganh/mmoserver.git
git fetch swganh
git branch --track develop swganh/develop
git checkout develop
cmd
BuildServer.bat
exit


Below is a line-by-line explanation of the above commands.

1) Clones the forked project. Be sure to replace USERNAME with the login name selected for GitHub!
2) Changes to the mmoserver directory
3) Add's the main SWG:ANH mmoserver project as a remote source to pull changes from.
4) Retrieves the latest changes from the main SWG:ANH mmoserver project
5) Creates a tracking branch which is used to track the latest changes to the main SWG:ANH MMOServer development branch.
6) Switches branches to the newly created develop branch.
7) Switches the command line environment to the Windows environment which is needed to build the project.
8) Kick's off the build script which builds the MMOServer project, this can take anywhere from 10 to 30 minutes depending on the PC configuration that is building it.
9) Exit from the Windows environment back to the Bash prompt.

Now that the main project has been built it's time to check out the database that was forked earlier and install it as well. The following commands will assist:

Code: Select all
git clone git@github.com:USERNAME/mmoserverdb.git
cd mmoserverdb
git remote add swganh git://github.com/swganh/mmoserverdb.git
git fetch swganh
git branch --track develop swganh/develop
git checkout develop
explorer .


These commands should all be familiar from the previous section with exception of the last one, which opens an Explorer instance in the current directory.

Next the configuration file for the database installer needs to be set up, just copy the file from setup.cfg-example to setup.cfg. Edit the setup.cfg to match the username and password that was set during the MySQL Server installation.

* Be sure to COPY and NOT rename the setup.cfg-example file!


Once done, close the folder window and enter the following commands in the prompt:

Code: Select all
cmd
setup.bat /install all
exit


The above will switch to the Windows environment and then kick off the database installer. The server is now setup and ready to be used!

Part III: Updating and Sharing Changes

Keeping a local clone updated with the latest changes from the main SWG:ANH project is easy, just open up your Git Bash prompt and navigate to the project directory and run the following commands:

Code: Select all
git checkout develop
git pull


1) This switches to the develop branch that was created in Part II of this guide.
2) Pull's down changes for all branches of the MMOServer project and updates the current develop branch.

Sharing changes made to the source is easy. Once changes have been committed and pushed up to your GitHub fork open a browser and go to your GitHub fork page:

http://github.com/USERNAME/mmoserver

* Be sure to replace USERNAME with your own GitHub username!


On this page use the Switch Branches option to select the branch you just pushed and then hit the Pull Request button at the top of the page. Enter in a message that describes the changes that were made, leave the recipients as they are, and hit Send Pull Request. This will notify the team to review your changes and, if accepted, merge them into the main source.

Part IV: Reference Materials

For those just starting out with Git and/or are not familiar with the command line Git can seem pretty daunting. Below are some excellent materials to help getting started with Git and understanding the basic's of what happens behind the scenes. This understanding is crucial to getting the most out of Git so reading through these resources is highly recommended!

1) GitHub Help - http://help.github.com/

This is an excellent resource for getting a GitHub account setup and Git configured to work with it. Any issues that may come up during this guide related to connecting to GitHub (authentication and SSH issues primarily) can be resolved by following the guides here or through the Support provided by GitHub:
http://support.github.com/

2) Git Reference - http://gitref.org/

For those just coming into Git the initial page of this site should be considered required reading. Those with Git experience should bookmark the site as well as it serves as an excellent reference for commands.

3) Pro Git - http://progit.org/

This is an online book that is recommended for anyone and everyone, especially those who wish to get a firm understanding of the Git internals and master concepts like branching, merging and rebasing.
Image
~ May the Source be with you ~
apathy
Retired SWG:ANH Staff
 
Posts: 57
Joined: July 16th, 2009, 12:36 am
SWG Official Server: Naritus

Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest