Adding new Extension

psineur edited this page Jun 9, 2011 · 18 revisions
Clone this wiki locally

Thank you for your interest for contributing to cocos2d-iphone-extensions.
These guidelines will help you go down in history of cocos2d community! ;)

Requirements

  1. Your extension should be licensed under MIT License: http://www.opensource.org/licenses/mit-license.php
  2. Your extension should be compatible with latest stable cocos2d source: https://github.com/cocos2d/cocos2d-iphone
  3. Your extension should have examples, that shows all aspects of it and can be used as tests.
  4. Try to follow cocos2d develop guidelines - this will increase your karma ;)
  5. Always wrap iOS- and MacOSX dependent code with #ifdef's ( You can use __IPHONE_OS_VERSION_MAX_ALLOWED & __MAC_OS_X_VERSION_MAX_ALLOWED ). This will allow user simply add all sources of your extensions in both Mac & iOS projects, even if they are not supported.

Preparing your Pull Request

You don't need to know Git & use GitHub to add your extension to the cocos2d-iphone-extensions repo.
But this is the best approach how to collaborate with us.

  1. Switch to the latest 'bleeding edge' version of cocos2d-iphone-extensions:
    git clone git@github.com:cocos2d/cocos2d-iphone-extensions.git
    cd cocos2d-iphone-extensions
    git fetch origin
    git checkout -t origin/develop
    git submodule update --init
  1. Create new branch from latest develop state with good describing name. From now on we think that your extension is CCAndroidCollider... God knows what is this thing for in cocos2d...
   git checkout -b CCAndroidCollider
  1. Apply your changes with detailed commit messages and comments. Don't forget that "person who will maintain your code is a maniac serial killer that knows where you live".
  2. Push your branch to your fork of cocos2d-iphone-extensions. If you still don't have a fork of cocos2d-iphone-extensions - fork it: http://help.github.com/fork-a-repo/
  3. Send a pull request to develop branch: https://github.com/cocos2d/cocos2d-iphone-extensions/pull/new

Adding an Extension

  1. Copy all files needed for work of your extension to the Extensions/CCAndroidCollider folder including source & resource files, that user of your extension will need to include in his project.
  2. Copy all tests files of your extension to Tests/CCAndroidColliderTest including source & resource files. Assign your test main layer like this:
   #import "ExtensionTest.h"
   SYNTHESIZE_EXTENSION_TEST(CCAndroidColliderTestLayer)
  1. Provide all necessary info about dependencies, system requirements, compatibility and issues in README file in Extensions/CCAndroidCollider folder.

Integrating Extension to cocos2d-iphone-extensions XCode Project

  1. In cocos2d-extensions-ios.xcodeproj (and or cocos2d-extensions-mac.xcodeproj) drag n drop CCAndroidCollider to Extensions Group & CCAndroidColliderTest to Tests Groups. Uncheck 'copy files if needed' and any targets.
  2. Duplicate 'Extension Test Template' target. Note: template target will not build itself, due to no SYNTHESIZE_EXTENSION_TEST macro used. If you get Undefined symbol "ExtensionTest" building your extension - make sure you have used this macro and assigned source files to your test target.
  3. Delete Info copy.plist or (Info-Mac Copy.plist) in 'Tests/SharedResources' Group with moving to trash
  4. Rename your target to CCAndroidColliderTest
  5. Edit Info of new Target for All Configurations:
    • Set Info.plist in your test target info to 'Tests/SharedResources/Info.plist' ('Tests/SharedResources/Info-Mac.plist' for Mac)
    • Set precompiled header to 'Tests/SharedSources/cocos2d_extensions_ios_Prefix.pch' or 'Tests/SharedSources/cocos2d_extensions_mac_Prefix.pch'
    • Set product name to CCAndroidColliderTest
    • Correct Library Search Path - they can be corrupted after Duplicate Target
  6. Assign files in CCAndroidCollider & CCAndroidColliderTest Groups to CCAndroidColliderTest target.
  7. Add CCAndroidCollider to agregate target BuildAllTests.
  8. Add all needed frameworks in CCAndroidColliderTest Target Info and move these Frameworks to corresponding subgroup in Frameworks Group (i.e. Frameworks/CCAndroidCollider Frameworks)
  9. Make sure that everything builds ok and be happy.

How can I contribute without worrying about all this git stuff?

Don't have time to learn GIT or register on GitHub? No problem!
You always can send me your stuff directly on my e-mail: psi.pk.ru@gmail.com
And/Or you can just open a topic about your extension on the cocos2d forums: http://www.cocos2d-iphone.org/forum/forum/17