cocos2d-x 3.0 beta의 개발 환경 설치 및 빌드 : win32, android

이 글은 2014년 1월 V3.0 beta0 기준으로 작성되어 있습니다. cocos2d-x는 나날이 버젼이 바뀌고있으며 그에 따른 변화도 만만치 않습니다. 따라서 이 글의 내용이 언제까지 유효할 지 보장하지 못합니다. 미래에서 오신분이라면 이 점 감안하시고 봐주시길 바랍니다.

작년 말 cocos2d-x Ver.3이 공개되었고 업데이트가 거듭되면서 얼마 전 beta0가 릴리즈되었습니다. 버젼 메이져 넘버가 바뀐 만큼 Ver.2.x와는 코드 및 기능 상 많은 차이점들이 존재합니다. 뿐만 아니라 빌드 환경도 많이 바뀌었습니다. 물론 아직 beta인만큼 본격적으로 상용 프로젝트에 사용하기에는 무리가 있을 것입니다. 하지만 매력적인 기능이 많아 슬슬 살펴보기 시작하긴 해야겠습니다. 물론 cocos2d-x를 입문하시는 분이라면 당연히 Ver.3부터 보는게 나을것이구요.

coco2d-x의 설치 환경에 대한 글을 많긴 하지만 모두 Ver.2.x 기준으로 되어있어서 Ver.3에서는 다소 다른 부분들이 많습니다. 그런 반면에 Ver.3의 설치 환경에 대한 글이 없어 따로 정리해둡니다. 다만, 윈도우즈와 안드로이드(android)에 대한 내용만 있고 맥과 iOS빌드에 관한 내용은 빠져있는 점 양해부탁드립니다.

우선 coco2d-x를 다운받습니다. 아래 링크로 가면 v2.2.2와 v3.0 beta이 있는데 이 글은 v3 기준이므로 v3.0 beta를 받읍시다. 바탕화면에 두면 경로에 공백이나 한글이 섞이게 될 소지가 있으므로 c:나 d: 적당한 곳에 폴더를 만들어서 압축을 풀어줍니다. 이제부터 바탕화면은 잊읍시다. 바탕화면은 죄악입니다. c:\program files도 죄악입니다. 폴더명에 한글이랑 공백이 섞여서 좋을거 하나두 없어요. 

http://www.cocos2d-x.org/download

프로젝트 생성

이제 프로젝트를 하나 생성해봅시다. 그러려면 우선 파이썬(python)이 필요합니다. 아래 사이트에서 파이썬을 다운받습니다. 파이썬은 Ver. 2.x대와 3.x대가 공존합니다. 하지만 Ver. 2.x대가 주로 사용되고 V.3은 미운오리새끼 취급받으므로 Ver. 2.x.x대에서 최신버젼을 설치합시다. 

http://www.python.org/download/

설치 후 어디 서든 파이썬을 수행 할 수 있도록 환경 변수를 등록해줘야 합니다. 아마 설치 후에 기본적으로 등록되어 있을 테지만 혹시 모르니 확인을 해봅시다. 컴퓨터 >속성 > 시스템설정 > 고급 > 환경변수를 통해 환경 변수 편집 창을 열거나  시작> 프로그램 파일 검색 > 시템의환경변수를 입력하여 창을 열 수 있습니다.

시스템변수의 목록 중 Path를 선택하고 편집합니다. 설정되어 있는 값 뒤에 ;로 구분하여 파이썬이 설치 된 위치를 입력해줍니다. 기존 값을 덮어쓰지 않게 주의합시다.

이제 프로젝트를 생성해봅시다. 이는 간단합니다. 파이선 스크립트 하나만 실행시켜주면 됩니다. 코코스 폴더의 tools\project-creator에 있는 create_project.py를 실행시켜줍시다. alpha에서는 커맨드툴이였는데 beta에서는 GUI로 바뀌었네요. 빈칸을 입력하고 create를 누르면 생성이 완료됩니다.

projectName : 말 그대로 프로젝트의 이름을 써줍니다. 디바이스에 설치하는 앱의 노출 이름이 됩니다. 하지만 앱이 노출 이름은 바꿀 수 있으므로 너무 고심해서 만들 필요는 없습니다.

packageName : 앱의 고유 이름이라고 생각하시면 됩니다. 스토어에 등록 시 구분이름이 되므로 겹칠 일이 없게 만들어줍시다. 강제적인 포맷은 없지만 일반적으로 회사 프로젝트면 com.회사명.프로젝트명 형식으로 만들고 개인 프로젝트면 pe.이름.프로젝트명 형식으로 네이밍합니다.

projectPath : 프로젝트가 만들어질 위치를 지정합니다. 예전 버전까지는 project폴더에 자동으로 만들어지는 걸로 강제되었었는데 v.3 beta부터는 원하는 위치에 만들 수 있게 되었습니다. 대신 프로젝트 폴더에 cocos2d가 통채로 같이 복사됩니다.

language : C++로 진행할 것이므로 cpp를 선택해줍니다.

win32 빌드

이제 프로젝트를 만들었으니 빌드하고 실행해봅시다. 우선 win32용은 간단합니다 그냥 비주얼스튜디오(visual studio, 이하 VS)만 있으면 됩니다. MS 페이지에 가서 VS 2013을 받아서 설치합시다

http://www.visualstudio.com/

win32 프로젝트는 생성한 프로젝트의 proj.win32 디렉터리에 있습니다. 프젝트명.sln 솔루션 파일을 수행합니다. 그러면 아래와 같은 메시지가 뜹니다. cocos에서 생성한 프로젝트는 VS2012기준으로 만들어져 있기때문에 VS2013에서 사용하기 위해서 업그레이드 한다는 뜻이므로 군말없이 OK해 줍니다.

그러고나서 sloution explorer에서 프로젝트가 시작프로젝트로 설정되어 있는 것을 확인합니다. 이미지와 같이 lib프로젝트가 아니라 생성한 프로젝트가 bold처리 되어 있으면 정상적으로 된 것입니다. 

F5를 눌러서 빌드하고 실행해주면 끝!

안드로이드 빌드

실행이 복잡하지 않은 win32에 비해서 안드로이드 프로젝트는 설치해야 할 것이 몇 개 추가적으로 필요합니다. 그나마 V.3.0 beta가 되면서 많이 간소화되었긴 하지만 여전히 귀챦은 것이 많은 게 사실입니다. 개발 플랫폼과 타겟 플랫폼이 다른지라 어쩔 수 없으니 숙명이라 생각하고 그냥 해봅시다 ㄱㄱ 

JDK 설치

일단 안드로이드는 자바로 개발합니다. cocos2d-x는 c++로 개발하긴 합니다만 최종적으로는 java로 만들어집니다. 그러므로 JDK(Java Development Kit)를 설치하여야합니다. 아래 링크로 가서 windows 버젼을 설치합니다. 본인의 PC에 맞게 x86 x64 잘 구분해서 받습니다. 설치 시 디렉터리 위치를 C:\Java 등 간단하게 설정해주는 것이 좋습니다. 앞서 언급했다시피 디렉터리 이름 사이에 공백이나 한글 등이 들어가면 꼬일 소지가 많습니다.

http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html

ADT 설치

안드로이드 프로젝트이므로 안드로이드 SDK를 설치합니다. ADT(Android Develper Tool)라고 불리는 것이 안드로이드 SDK입니다. 아래 링크에서 다운로드 후 c:나 d:등 적당한 위치에 압축을 풀어줍니다. 

http://developer.android.com/sdk/index.html

그 후 디렉터리 내에 있는 SDK Manager.exe를 수행시켜 API들을 설치합니다. 설치할 API들을 선택하고 Install packages를 눌러서 설치를 진행하면 됩니다. Tools, 4.0(API14), 2.3.3(API10), 2.2(API8)를 선택하여 설치합니다. API14는 안드로이드에서 권장하는 버전이고 API10은 타겟을 API14로 설정 시 사용 가능한 최소 레벨입니다. API8은 사실상 현존하는 최저 레벨입니다.

NDK 설치

그 후 NDK(Navite Development Kit)를 설치합니다. 

안드로이드는 달빅가상머신(dalvik virtual machine, DVM)상에서 JAVA 코드를 돌립니다. NDK는 C/C++같은 네이티브 코드 언어를 이 가상머신에서 사용할 수 있도록 해주는 툴셋입니다. cocos2d-x는 C++로 개발하므로 NDK가 필수로 필요합니다. 

역시 다음 사이트에서 다운로드 후 적당한 위치에 압축을 풀어줍시다. 아마 ADT가 설치 된 후에야 다운로드가 가능 할 겁니다.

http://developer.android.com/tools/sdk/ndk/index.html

예전에는 NDK 빌드를 하기 위해서는 cygwin을 설치해서 쉘스크립트를 실행하여야했습니다. 하지만 cygwin은 V.3 beta가 되면서 필요가 없어졌습니다. 어쨌든 cygwin은 필요가 없어지긴 했지만 여러모로 쓸모가 많으므로 설치해둬서 나쁠건 없어요 :-) 

http://cygwin.com/install.html

ANT 설치

NDK까지 설치를 마쳤으면 이제 apache ANT를 설치하여야 합니다. 다른 글들에서는 이클립스(eclipse)를 이용하는데, 이 글에서는 일단 건너뛰겠습니다.(사실 이미 앞서 설치한 ADT에 이클립스도 포함되어있습니다.) 안드로이드 네이티브 기능 연동을 개발 시에는 이클립스가 필요하긴 하지만 일단 당장은 ANT만 설치해도 apk(Android Package) 빌드가 가능합니다. 

ANT는 크로스 플랫폼에 대응하여 만들어진 JAVA 기반의 빌드 커맨드 툴입니다. 안드로이드의 apk 역시 ANT로 빌드가 가능하며 cocos2d-x 프로젝트에서도 이를 사용할 수 있게 구성되어있습니다. 다음 링크로 가서 current Release of Ant에서 압축 파일을 받아 풀면 됩니다. 재차 언급하는것이지만 이름이 한글로 된 디렉터리나 바탕화면은 피해야 합니다. 

http://ant.apache.org/bindownload.cgi

환경 변수 설정

JDK, ADT, NDK, ANT 등의 설치를 모두 마쳤으면 이제 이들이 서로 유기적으로 돌아갈 수 있도록 환경변수를 설정해줘야합니다. 빌드과정에서 환경변수들을 사용하므로 셋팅이 되어 있지 않으면 빌드가 제대로 이루어지지 않습니다.

앞서 파이썬 패스 등록 시 열었던 환경변수창을 다시 엽니다. Path 변수에다가 JDK의 bin폴더, NDK폴더, ANT의 bin 폴더를 추가적으로 등록해줍니다. 저는 C:에 풀어놔서 다음과 같이 추가해줬습니다. 참고해서 각자의 설정에 맞게 추가해줍시다.

;C:\Java\jdk1.7.0_45\bin;C:\ndk;C:\ant\bin

ADT 디렉터리는 Path 변수가 아니라 전용 변수를 따로 추가해줍니다. 환경변수창에서 새로만들기를 누른 뒤 ADT의 sdk폴더를 ANDROID_HOME에 등록해줍니다.

이와 마찬가지로 다음 목록의 변수들을 추가해줍니다. 세부 폴더 위치는 참고해서 각자의 환경에 맞게 추가해주세요

ANDROID_HOME : C:\adt\sdk

CLASS_PATH :  ;(레알 이게 땡임)

JAVA_HOME : C:\Java\jdk1.7.0_45

NDK_MODULE_PATH : D:\cocos2d-x-3.0beta;D:\cocos2d-x-3.0beta\cocos\2d\platform\android

NDK_ROOT : C:\ndk

수고많으셨습니다. 이제 실제로 빌드를 해봅시다.

NDK 빌드

일단 명령프롬프트(윈도우버튼 > 프로그램파일검색 창에서 cmd)를 엽니다. 다음과 같이 cd 명령을 수행해서 앞서 새로 만든 프로젝트의 proj.android폴더로 이동합니다.(역시 폴더 이름은 각자의 것에 맞게)

이제 NDK 빌드를 하기 위해 파이썬 스크립트를 수행합니다.

> build_native.py

그럼 컴파일이 쫙쫙쫙 수행됩니다. 빌드 후 메시지가 다음과 같이 나오며 proj.android\libs\armeabi에libcocos2dcpp.so 파일이 생성되면 NDK 빌드가 완료 된 것입니다.

설정 파일 변경

이제 libcocos2dcpp.so를 Java와 연결하고 빌드하여 APK 파일을 생성하면 됩니다. 그 전에 설정 좀 바꿔줘야 할 것이 있습니다.

일단 AndroidManifest파일의 수정이 필요합니다. 안드로이드 프로젝트의 속성 파일이라고 생각하시면 됩니다. proj.android 디렉터리에 있는 AndroidManifest.xml 파일을 문서편집기로 열어 다음과 같이 sdk 버젼이 9로만 되어 있는 것을 

<uses-sdk android:minSdkVersion="9"/>

다음과 같이 target을 14로, min을 10으로 바꾸어줍시다.

<uses-sdk android:minSdkVersion="10" android:targetSdkVersion="14"/>

여기서 가리키는 SdkVersion은 앞서 ADT에서 설치했던 API 레벨을 의미합니다. 수정 전에 입력되어 있던 9는 전설속에만 존재하는 API고, 우린 전설을 믿지 않으니 수정해 주는겁니다. 기왕이면 target SDK를 구글에서 권장하는 14레벨로 설정합니다. API14는 4.0 아이스크림샌드위치인데 그럼 그 이하 버젼은 지원을 안하는 것이냐!? 그건 걱정하지 맙시다. 하위 OS 호환성을 위해서 targetSdkVersion과 minSdkVersion이 따로 있습니다. 최소 지원 SDK 값을 10으로 지정해줘서 2.3.3 생강빵 이상에서 돌아가게 해줍니다. 사실상 현존하는 최소 버젼은 API8 2.2 프로요이긴 하지만 target을 14로 설정하면 8의 설정과 충돌나는 부분이 있어서 애석하게도 사용하지 못합니다. 2.2 프로요는 아직 점유율이 2.7%나 되서 버리기에는 조금 아깝긴합니다. 하지만 타겟을 4.0 아이스크림샌드위치로 설정해야 태블릿에서 검색 가능하기때문에 살을 내주고 뼈를 취하는게 낫습니다.

configChanges도 건드려줘야 합니다. AndroidManifest.xml 파일에서 configChanges도 다음과 같이 되어있던 것을

android:configChanges="orientation|screenSize|smallestScreenSize"

다음과 같이 바꿔줍시다

android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|uiMode|screenSize|smallestScreenSize"

configChanges는 Activity가 직접 handle하는 configuration 변경에 대한 리스트입니다. 말이 조금 난해하네요. 안드로이드는 가로세로모드 변경 혹은 키보드 창 등 뭔가 변경이 일어나면 액티비티가 재생성됩니다. 하지만 이곳에 명시된 변경들은 액티비티가 직접 처리한다는 것입니다. cocos2d-x는 게임 렌더링이 하나의 activity에서 일어나는데 이것이 재생성되버리면 펑 하고 터져버립니다. 그렇기때문에 여기에 추가를 해줘야 합니다. 

keyboard|keyboardHidden는 키보드 입력에 관한 것입니다. cocos2d-x는 extension에서 키보드 입력을 지원해주는데 키보드에 대한 속성이 빠져있어서 추가해줍니다. 

uiMode|‌​screenSize|smallestScreenSize는 전원 버튼이 눌리어서 lock되었을때 발생하는 행위들입니다. 이걸 추가해주지 않으면 화면이 잠김상태로 간뒤 터져버립니다.

이제 proj.android 폴더에 있는 project.properties를 편집해줘야합니다. 이 파일은 ANT 빌드 시 사용되는 프로퍼티 파일입니다. 빌드 타겟이 10으로 되어있던 것을 다음과 같이 14로 바꿔줍시다.

target=android-14

ANT 빌드

자 이제 다왔습니다. 이제 ANT를 수행하면 됩니다. 명령프롬프트에서 위치가 proj.android인지 확인하고 다음과 같이 입력하여 최종 빌드를 수행합시다. 스토어에 올릴 apk를 빌드시에는 release로 하여야 하지만 일단은 폰에 띄워보는게 목적이므로 debug로 빌드합시다. release 빌드 시에는 키스토어 셋팅이 추가적으로 들어가야해서 귀챦습니다;; 

> ant -Dsdk.dir=%ANDROID_HOME% debug

다음과 같이 빌드 성공이라고 나오면 proj.android/bin 디렉터리에 프젝트명-debug-unaligned.apk 파일이 생성됩니다. 이것을 폰에 복사하고 설치하면 끝입니다.

마치며

정말 수고가 많으셨습니다. 빌드가 순탄치많은 않네요. 하지만 그나마 이클립스랑 cygwin이 생략되서 이정도입니다. ㅎ 시간이 지나면서 점점 개선이 되고 있고 통합 인스톨러도 개발중입니다.  얼마 후에는 이 글도 필요가 없어지겠네요.

cocoa china developer conference 중

생성한 프로젝트에서 기본적으로 사용하는 라이브러리 외 extension 기능 등을 사용하거나 라이브러리등을 추가하면 설정해줘야 하는 것 들이 또 발생하는데 그건 다음시간에 다루기로 합시다. iOS 빌드도요. 근데 사실 iOS빌드는 따로 다룰 필요가 있을까 싶을정도로 간단해서;;

일단 그럼