Revision as of 21:11, 25 April 2011

This page contains information about how to contribute to the Guild of Writers fork of the CyanWorlds.com Engine.

Git

The Guild of Writers fork of the CyanWorlds.com Engine uses git for its source control needs. If you're already familiar with git, some of these instructions may seem obvious to you. If you're not familiar with git, it is recommended that you read through some of the excellent articles in the GitHub help area.

Dependencies

• CMake. When you install, make sure you tell the installer to add CMake to the system PATH.
• PhysX 2.6.4. This is available from NVIDIA's PhysX Archives
• Creative Labs' OpenAL SDK 1.1
• The June 2010 DirectX SDK
• The CWE development libraries bundle
• Microsoft Visual Studio 2008 SP1. The express edition is not supported at this time.

Building the Code

Getting the Code

If you intend to contribute to the codebase, you should follow the Getting the Code section below under Contributing.

• First, you'll need git. Follow the first section of the Windows git setup guide. You don't need a GitHub account if you just want read-only access, and you don't need to generate an SSH key. This page will assume you install both the "Git Bash" and "Git GUI" context menu options, so please do so.
• Open Git GUI from the Start menu, and click "Clone Existing Repository"
• Enter git://github.com/H-uru/Plasma.git as the source, and select your preferred destination folder.
• Click 'Clone'
• Congratulations, you've now got a copy of the CyanWorlds.com Engine sources

Configuring and Building

If you haven't already, make sure you've installed and unpacked all the files listed in the Dependencies section. If you're not using Visual Studio 2008, you may need to build some or all of these dependencies yourself.

• Open a Visual Studio 2008 command prompt
• run the command set CMAKE_PREFIX_PATH="C:\cwe-prefix\", where C:\cwe-prefix\ is the directory where you unpacked the development libraries bundle
• run the command cmake-gui in the command prompt .
• Select your clone of the Plasma repository as the source directory, and select a build directory. source_directory\build is recommended.
• Click Configure, and select either Visual Studio 9 or nmake makefiles. If you aren't sure, go with Visual Studio 9.
• CMake won't automatically find PhysX or OpenAL.
  • For PhysX, set PHYSX_SDK_PATH to C:\physx_2.6.4\SDKs\ (replace C:\physx_2.6.4 with your PhysX SDK installation path).
  • For OpenAL, you'll need to select both the include directory and the library. For a default OpenAL SDK install, these will be C:\Program Files\OpenAL 1.1 SDK\include and C:\Program Files\OpenAL 1.1 SDK\libs\Win32\OpenAL32.lib
• Click Configure again
• Click Generate

You should now have a complete Visual Studio 2008 build environment (either a solution or nmake file). You can now compile and debug the code.

Contributing

GitHub provides a robust set of tools to allow you to easily share your changes with the main Guild repository. These tools revolve around two concepts: forks and pull requests.

Using a GitHub fork, you can develop your changes in a repository that you have full access to. Once you're ready to share that change, you can issue a pull request. The GoW development team will be notified and we'll review your changeset for inclusion. After a few good patches, you will probably be offered direct access to the GoW repository, meaning faster turn around for your patches and less management work for the core dev team.

It is recommended that when you begin work on a bugfix or feature, you do so in a git branch. This will make it easier for us to merge your changes into the main repository. Try to avoid merging other branches into your work branch (including updates to master). The cleaner your branch is the easier it will be to integrate.

Code Guidelines

1. Follow whatever code style is already in the file you're working on. Plasma was developed over many years, and there are a variety of styles in the code.
2. Indentation should be 4 spaces. Never use tabs.

Forking the Code

• The first thing you'll need is an account at GitHub. Once you have an account, you should follow all the steps in the Windows git setup guide. This page will assume you install both the "Git Bash" and "Git GUI" context menu options, so please do so.
• Run git config --global core.autocrlf true Note: If you're familiar with git, you may wish to enable this on a per-repository basis instead of globally.
• Go to the Plasma repository page.
• Click the 'fork' button
• Open Git GUI from the Start Menu, and click "Clone Existing Repository"
• Enter the SSH clone URL from your GitHub This should be of the form git@github.com:username/Plasma.git, and select your preferred destination folder
• Click 'Clone'
• Congratulations, you've now got a copy of the CyanWorlds.com Engine sources

If you came here from Building the Code, you can continue with Configuration in that section now.

Sharing Changes

If you need help comitting changes and pushing them to your local GitHub repository, please read some of the excellent documentation in the GitHub help area, or join us in IRC.

When you're ready, you'll probably want to share your changes with the main Guild of Writers repository. This is very easy!

• Go to the GitHub page for your copy of the Plasma repository. This should be http://github.com/username/Plasma.
• If you're trying to share a branch (the recommended route), click the "Switch Branch" button to choose the branch you want to share.
• Click the "Pull Request" button.
• From here you can enter information about the changes you've made, and the merge approval process will begin.