PyCocos2D-x : How to Properly Setup Boost.Python in Your Visual C++ 2012 Project


Welcome to the First Series of Tutorial on PyCocos2d-x Development

Welcome to the First Series of Tutorial on PyCocos2d-x Development!

Okay, for a quick background, you may skim on my previous article : How to Choose The Best Python 2D Game Engine?. I pointed out, "Although currently I am working with the Cocos2D python version, I am flirting Cocos2d-x due to its wider target platform". And my experience on working with Cocos2D Python was really impressive, but sadly .. it didn't satisfy my requirement. I need to develop an isometric game engine for my current Python teaching aid for kids, ProgrammedMe. And the current Cocos2D didn't support isometric map type that I longed for. I have tried to implement it actually, but as the forum itself is not that active (or may I say rather freeze?), I don't think I want to pursue my exploration in the Cocos2d Python field. Another reason is also about Cocos2D that only targeting desktop platform, which is a deal breaker for me (would love to develop for Android/iOS!). So, a natural direction would be to explore Cocos2D-x and try my best to implement a Python binding for it. Once it's settled, I can start developing ProgrammedMe using the aforementioned binding, named PyCocos2d-x

Quick Background on Cocos2d-x .. and its Future

Although the first Cocos2d was built with Python, but its iPhone version is the one that get much attention in game development community. Some, if not all the time, internet folks refer to Cocos2d-iPhone when they talked about Cocos2d. As Cocos2d-iPhone is only targeted at iOS/OSX platform and using Objective-C, its audience was only limited to those who would like to develop game specifically for iOS/OSX. Actually, this is not a deal breaker for common folks. Because most of the time, developer start their game development focusing on one platform and after it got success, they will port it to another platform. But, isn't it intriguing to be able to use one source  code to target all (or popular) platform ? Hence, Cocos2d-x was born.

Another important note regarding Cocos2d-iPhone and Cocos2d-x are also about its future, shown below:

The Future of Cocos2d-iPhone

The Future of Cocos2d-iPhone, from its creator

It's not a sign that the iPhone version will be death and the only version that going to succeed is its -x version. Community is the important factor that drive a technology adoption. And surely, Cocos2d-iPhone community is vibrant community that will shaped its future.

Nevertheless, placing your bet in Cocos2d-x is now the best bet for you in case an important factor in your development is about cross platform availability. And, as my personal goal is to develop a Python teaching aid for kids, I simply have to develop some kind of Python binding / interface for Cocos2d-x (I named it PyCocos2d-x), so that I can use Python to develop this application. Hence, will teach kids how to use Python.  

Core Concept of PyCocos2d-x

Got to say, this is quite funny, as the route will be :

The circle is now complete! It feels like trying to bring back Cocos2d to the Python community

My intention is that, by using PyCocos2d-x and Python interactive REPL, children can be teach on how to use Python in an interactive game development or simply in an interactive education game (ProgrammedMe). This means, we are about to expose Cocos2d-x framework into Python. The question is, is it remotely possible?

It is indeed and it really close ... Cool 

Using Boost.Python for Python Binding

Python have more than one ways to expose your C++ code to Python, have a look at its official page here or to a good question in stackoverflow here. I am choosing Boost.Python largely due to its stable support (was there a C++ programmer who didn't stumble upon Boost myriad utility in their work ?). You can develop C++ application as usual, but if you want to expose some or part of your code into Python, you simply wrap it using Boost.Python macro and templates.

But, as with almost all C/C++ library, getting it to works in your environment or on your special IDE almost took a helluva lots of time. And as I am in favour for Python Tools for Visual Studio, naturally I use Visual Studio.NET. Hence, in this article I will elaborate the steps required to make Boost.Python works in your Visual Studio environment. I am going to use Visual Studio 2012 here, but you can use any version that you want.

Download and Build Boost.Python

I listed here the steps required to setup Build.Python into Windows environment. Steps below assumed that you have already installed Visual C++ 2012 (but any version will do). 

  1. Download Boost from here. Warning ahead : it really is big. Around 100Mb. "What with the big size?", you may asked. It's because Boost comprise of many high quality C++ library. You can read more about it in one good SO question here.
  2. Extract it somewhere in your path, let just says we installed it in C:\boost, and put it into your Path variable. We need to do this, so that Visual Studio.NET will be able to run bjam from anywhere in  your system. bjam is one part of Boost own build system, called Boost.Build.
  3. Open "Developer Command Prompt for VS2012" from Visual Studio 2012 Start menu folder, and go to C:\boost. Run bootstrap.bat, to prepare Boost in building it for our system.
  4. Run b2, which will create all *.lib files required to use Boost. It will place them in the folder C:\boost\stage\lib.
  5. One unfortunate thing is, for our Python integration project to be successfully built, you have to rename C:\boost\stage\lib\libboost_python-vc110-mt-gd-1_55.lib into C:\boost\stage\lib\boost_python-vc110-mt-gd-1_55.lib. And you will have to copy it into root folder of your project. This is the obstacle that not easily spotted. Really, it gives me headaches around an hour or so.
  6. Done

Checking Boost.Build System Installation Correctness

First, let test whether our Boost installation for correctness. For this, let test the shipped Boost.Python example application. Still in Command Prompt environment, go to the folder C:\boost\libs\python\example\tutorial. There, you will see these two important files:

  1. Jamroot : system will use this file to build your application.Think of it as for your Makefile project.
  2. boost-build.jam : Mainly use to locate the installation directory of Boost distribution.
  3. hello.cpp : Main C++ file, with functions / data structure / class that ready to exposed into Python.

On important note, don't forget to copy the aforementioned C:\boost\stage\lib\boost_python-vc110-mt-gd-1_55.lib into C:\boost\libs\python\example\tutorial. Failed to do so, .. well, your build process will not success.

Run bjam.

If everything works fine, you will see a newly created (among other things) a hello_ext.pyd as the result of the build process. Actually, this is just a regular Windows DLL file, but renamed into *.pyd file. Python will not import DLL file. Instead it will import a PYD file. Test it by running Python and import this new PYD file, shown below:

Successful test of Boost.Python installation

Successful installation of Boost.Python installation

In case right now you were wondering what is inside hello.cpp, here it is:

char const* greet()
   return "hello, world";
    using namespace boost::python;
    def("greet", greet);

Pretty straightforward, right?

Your next step is to create a blank Visual C++ 2012 project and configure it to use bjam for its custom building process. Chances are you would love to develop your C++ application from within Visual Studio.NET 2012 using state of the art IDE support and other bell and whistles that aim to simplify software development process.

Configure Visual C++ Project to use Boost.Build

As Boost application will use its own Build system, so you will have to start with an Empty C++ Project.

Empty C++ Project

Empty C++ Project

And proceed with the following steps :

  1.  Add new Text (*.txt) document and renamed it into Jamroot. You can just copy the existing jamroot file from C:\boost\libs\python\example\tutorial. Just be sure to rename property of use-project boost into location of your Boost installation. It the file path contains spaces, be sure to use double quotes for it. For example, I use this is in my Jamroot file: use-project boost
      : "C:/Users/Eko Wibowo/coding/_resource/boost_1_55_0" ;
  2.  Add another Text (*.txt) document and renamed it into boost-build.jam. will use this to locate the location of Boost installation. It just need to contain these line boost-build "C:/Users/Eko Wibowo/coding/_resource/boost_1_55_0/tools/build/v2";.
  3. Create a new C++ File (*.cpp) and lets named it hello.cpp. Copy the content of the existing C:\boost\libs\python\example\tutorial. We just need to test whether our VC++ project correctly setup or not. Later, of course we will use our own code. The tutorial also include a file. You can create this file also, or if you don't want to use it, make sure to comment the line run-test hello : hello_ext ; from Jamroot file.
  4. Right click on your project, and choose Properties. Here you have to setup Include and Library directories.

    For the include directory you have to add Boost root installation directory and Python include directory.
    While for the library directory you have to add Boost stage\lib and Python libs directory.
    If you have already rename C:\boost\stage\lib\boost_python-vc110-mt-gd-1_55.lib, then you don't have to copy this lib file into your project directory. VC++ will take care of the file reference. But, if you plan to run bjam from command line, you have to copy this file into your project folder.
  5. Change your Configuration Type into Static Library.
    Actually, I am not properly satisfy with this step, as it will create useless *.lib file for us. will produce the correct *.pyd file for us. But the other configuration type will only create link error. So, let just use this configuration type.
  6. Last step, you will have to inform VC++ that we are about to use custom build tool, shown belowCustom

If everything setup correctly, you will see build output resemblance to this, and you will have the exact hello_ext.pyd ready to be use in your Python application

Output result

Successful output result of a process

 Congratulation! Cool

What's Next?

This is just the first step of my plan in trying to create a Python binding for Cocos2d-x, with the intention of using it in developing ProgrammedMe, which is a Python Teaching aid for The Kids. You can follow its development in Github Repo : PyCocos2d-x.

So, stay tuned for my initial ProgrammedMe Proof of Concept application using PyCocos2d-x!


Leave comments


Copyright(c) 2014 -
By using this website, you signify your acceptance of Terms and Conditions and Privacy Policy
All rights reserved