Difference between revisions of "Development:CyanWorlds.com Engine"

(→‎Building the Code)
(Video tutorial added. Rewrite lots of stuff to match it.)
Line 19: Line 19:
  
 
==Getting the Code==
 
==Getting the Code==
−
''If you intend to contribute to the codebase, you should follow the '''''Getting the Code''''' section below under '''''Contributing'''.
+
# '''Install Git''' If you are unfamiliar with git or require some additional guidance, please refer to the first section of the [http://help.github.com/win-set-up-git/ GitHub Windows Setup Guide]. ''We will assume that you install git with context menu support.''
−
* First, you'll need git. Follow the first section of the [http://help.github.com/win-set-up-git/ 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.
+
# '''Copy the URL''' of the [https://github.com/H-uru/Plasma repository] into your clipboard. If you are interested in contributing to CyanWorlds.com Engine development, then you should [http://help.github.com/fork-a-repo/ fork the repository] and use the URL of your fork.
−
* Open Git GUI from the Start menu, and click "Clone Existing Repository"
+
# '''Navigate''' to a location on your computer where you would like to place the CyanWorlds.com Engine source code.
−
* Enter <code>git://github.com/H-uru/Plasma.git</code> as the source, and select your preferred destination folder.
+
# '''Right click''' in Windows Explorer and choose the ''Git Bash'' menu option.
−
* Click 'Clone'
+
# '''Type''' ''git clone'' into the command prompt, insert a space, then '''paste''' the URL of the repository. '''Press Enter.'''
−
* Congratulations, you've now got a copy of the CyanWorlds.com Engine sources
+
  
 
==Configuring and Building==
 
==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.''
+
'''''Note''': Make sure that you have installed all of the '''dependencies''' before continuing!''
  
−
* Open a Visual Studio 2008 command prompt
+
# '''Start Cmake'''
−
* run the command <code>set CMAKE_PREFIX_PATH="C:\cwe-prefix\"</code>, where '''C:\cwe-prefix\''' is the directory where you unpacked the development libraries bundle
+
# '''Set''' the ''Where is the source code'' option to the location where you cloned the repository.
−
* run the command <code>cmake-gui</code> in the command prompt .
+
# '''Set''' the ''Where to build the binaries'' option to a subfolder of the aforementioned location called ''build''.
−
* Select your clone of the Plasma repository as the source directory, and select a build directory. <code>source_directory\build</code> is recommended.
+
# '''Check''' the ''Grouped'' and ''Advanced'' options.
−
* Click '''Configure''', and select either ''Visual Studio 9'' or ''nmake makefiles''. If you aren't sure, go with ''Visual Studio 9''.
+
# '''Press ''Configure'''''. Select ''Visual Studio 9 2008'' as the generator.
−
* CMake won't automatically find PhysX or OpenAL.
+
# '''Set''' the ''CMAKE_INSTALL_PREFIX'' option under ''Cmake'' to the ''cwe-prefix'' folder that you extracted from the [http://guildofwriters.com/tools/devlibs.zip ''development libraries bundle''].
−
**For PhysX, set '''PHYSX_SDK_PATH''' to <code>C:\physx_2.6.4\SDKs\</code> (replace <code>C:\physx_2.6.4</code> with your PhysX SDK installation path).
+
# '''Press ''Configure''''' again.
−
**For OpenAL, you'll need to select both the include directory and the library. For a default OpenAL SDK install, these will be <code>C:\Program Files\OpenAL 1.1 SDK\include</code> and <code>C:\Program Files\OpenAL 1.1 SDK\libs\Win32\OpenAL32.lib</code>
+
# '''Set''' the OpenAL include and library path options under ''OpenAL''.
−
** '''''Note:''' Only one of PhysX or OpenAL will show at a time as being missing. Fix the one that shows up, then hit '''''configure''''' again, and the other one will show up.''
+
## '''Default Include Path''': ''C:\Program Files\OpenAL 1.1 SDK\include''
−
* Click '''Configure''' again
+
## '''Default Library Path''': ''C:\Program Files\OpenAL 1.1 SDK\lib\win32\OpenAL32.lib''
−
* Click '''Generate'''
+
# '''Press ''Configure''''' again.
−
 
+
# '''Set''' the ''PHYSX_SDK_PATH'' option under ''PHYSX''. The default value is ''C:\Program Files\AGEIA Technologies\AGEIA PhysX SDK\v2.6.4\SDKs''.
−
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.
+
# '''Press ''Configure...''''' For the last time!
 +
# '''Press ''Generate.''''' You will now have a Visual Studio solution file (.sln) in the folder that you specified to build the binaries in.
 +
# '''Open the solution''' in Visual Studio. You can compile CyanWorlds.com Engine by pressing ''Build'' -> ''Build Solution''. This will take some time.
  
 
=Contributing=
 
=Contributing=
Line 49: Line 50:
  
 
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.
 
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.
 +
 +
Once you are satisfied with your work, you should go back to the issue a [http://help.github.com/pull-requests/ pull request], which will let us know that you are reafy for your changes to be merged into the main branch of development--the master branch. Once you have submitted your pull request, we will review your code and ask any applicable questions. Once your code passes our review(s), we will merge it into the master branch.
  
 
==Code Guidelines==
 
==Code Guidelines==
−
# 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.
+
To improve the chance of your contributions being accepted, please consider the following guidelines.
−
# Indentation should be 4 spaces. Never use tabs.
+
−
 
+
−
==Forking the Code==
+
−
* The first thing you'll need is an [https://github.com/signup/free account at GitHub]. Once you have an account, you should follow all the steps in the [http://help.github.com/win-set-up-git/ 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 <code>git config --global core.autocrlf true</code> '''''Note:''' If you're familiar with git, you may wish to enable this on a per-repository basis instead of globally.''
+
−
* Go  to the [http://github.com/H-uru/Plasma 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 <code>git@github.com:''username''/Plasma.git</code>, 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 [http://help.github.com/ 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 <code>http://github.com/''username''/Plasma</code>.
+
* 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. Try to maintain an average style for the file you're working in.
−
* If you're trying to share a branch (the recommended route), click the "Switch Branch" button to choose the branch you want to share.
+
* Indentation should be 4 ''spaces''. '''Tabs will not be accepted.''' Be sure to change your Visual Studio text editor settings to ''insert spaces'' if you have not already!
−
* Click the "Pull Request" button.
+
−
* From here you can enter information about the changes you've made, and the merge approval process will begin.
+
  
 
[[Category:Projects]]
 
[[Category:Projects]]

Revision as of 20:07, 26 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

Building the Code

A video tutorial is available to supplement the following instructions.

Getting the Code

  1. Install Git If you are unfamiliar with git or require some additional guidance, please refer to the first section of the GitHub Windows Setup Guide. We will assume that you install git with context menu support.
  2. Copy the URL of the repository into your clipboard. If you are interested in contributing to CyanWorlds.com Engine development, then you should fork the repository and use the URL of your fork.
  3. Navigate to a location on your computer where you would like to place the CyanWorlds.com Engine source code.
  4. Right click in Windows Explorer and choose the Git Bash menu option.
  5. Type git clone into the command prompt, insert a space, then paste the URL of the repository. Press Enter.

Configuring and Building

Note: Make sure that you have installed all of the dependencies before continuing!

  1. Start Cmake
  2. Set the Where is the source code option to the location where you cloned the repository.
  3. Set the Where to build the binaries option to a subfolder of the aforementioned location called build.
  4. Check the Grouped and Advanced options.
  5. Press Configure. Select Visual Studio 9 2008 as the generator.
  6. Set the CMAKE_INSTALL_PREFIX option under Cmake to the cwe-prefix folder that you extracted from the development libraries bundle.
  7. Press Configure again.
  8. Set the OpenAL include and library path options under OpenAL.
    1. Default Include Path: C:\Program Files\OpenAL 1.1 SDK\include
    2. Default Library Path: C:\Program Files\OpenAL 1.1 SDK\lib\win32\OpenAL32.lib
  9. Press Configure again.
  10. Set the PHYSX_SDK_PATH option under PHYSX. The default value is C:\Program Files\AGEIA Technologies\AGEIA PhysX SDK\v2.6.4\SDKs.
  11. Press Configure... For the last time!
  12. Press Generate. You will now have a Visual Studio solution file (.sln) in the folder that you specified to build the binaries in.
  13. Open the solution in Visual Studio. You can compile CyanWorlds.com Engine by pressing Build -> Build Solution. This will take some time.

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.

Once you are satisfied with your work, you should go back to the issue a pull request, which will let us know that you are reafy for your changes to be merged into the main branch of development--the master branch. Once you have submitted your pull request, we will review your code and ask any applicable questions. Once your code passes our review(s), we will merge it into the master branch.

Code Guidelines

To improve the chance of your contributions being accepted, please consider the following guidelines.

  • 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. Try to maintain an average style for the file you're working in.
  • Indentation should be 4 spaces. Tabs will not be accepted. Be sure to change your Visual Studio text editor settings to insert spaces if you have not already!