rapidgame
Version:
A cross-platform commandline tool that prebuilds cocos2d-x libraries for Windows, Mac, Linux, Android and iOS. Also a game templating system.
1,139 lines (905 loc) • 41 kB
HTML
<html>
<!--Markdown to HTML: http://dillinger.io-->
<!--CSS found at: https://github.com/jasonlong/architect-theme/stylesheets/stylesheet.css-->
<head>
<meta charset="utf-8">
<title>Android README</title>
<style>
/*! normalize.css v3.0.2 | MIT License | git.io/normalize */
/**
* 1. Set default font family to sans-serif.
* 2. Prevent iOS text size adjust after orientation change, without disabling
* user zoom.
*/
html {
font-family: sans-serif; /* 1 */
-webkit-text-size-adjust: 100%; /* 2 */
-ms-text-size-adjust: 100%; /* 2 */
}
/**
* Remove default margin.
*/
body {
margin-left: 20px;
margin-right: 20px;
margin-bottom: 50px;
}
/* HTML5 display definitions
========================================================================== */
/**
* Correct `block` display not defined for any HTML5 element in IE 8/9.
* Correct `block` display not defined for `details` or `summary` in IE 10/11
* and Firefox.
* Correct `block` display not defined for `main` in IE 11.
*/
article,
aside,
details,
figcaption,
figure,
footer,
header,
hgroup,
main,
menu,
nav,
section,
summary {
display: block;
}
/**
* 1. Correct `inline-block` display not defined in IE 8/9.
* 2. Normalize vertical alignment of `progress` in Chrome, Firefox, and Opera.
*/
audio,
canvas,
progress,
video {
display: inline-block; /* 1 */
vertical-align: baseline; /* 2 */
}
/**
* Prevent modern browsers from displaying `audio` without controls.
* Remove excess height in iOS 5 devices.
*/
audio:not([controls]) {
display: none;
height: 0;
}
/**
* Address `[hidden]` styling not present in IE 8/9/10.
* Hide the `template` element in IE 8/9/11, Safari, and Firefox < 22.
*/
[hidden],
template {
display: none;
}
/* Links
========================================================================== */
/**
* Remove the gray background color from active links in IE 10.
*/
a {
background-color: transparent;
}
/**
* Improve readability when focused and also mouse hovered in all browsers.
*/
a:active,
a:hover {
outline: 0;
}
/* Text-level semantics
========================================================================== */
/**
* Address styling not present in IE 8/9/10/11, Safari, and Chrome.
*/
abbr[title] {
border-bottom: 1px dotted;
}
/**
* Address style set to `bolder` in Firefox 4+, Safari, and Chrome.
*/
b,
strong {
font-weight: bold;
}
/**
* Address styling not present in Safari and Chrome.
*/
dfn {
font-style: italic;
}
/**
* Address variable `h1` font-size and margin within `section` and `article`
* contexts in Firefox 4+, Safari, and Chrome.
*/
h1 {
margin: 0.67em 0;
font-size: 2em;
}
/**
* Address styling not present in IE 8/9.
*/
mark {
color: #000;
background: #ff0;
}
/**
* Address inconsistent and variable font size in all browsers.
*/
small {
font-size: 80%;
}
/**
* Prevent `sub` and `sup` affecting `line-height` in all browsers.
*/
sub,
sup {
position: relative;
font-size: 75%;
line-height: 0;
vertical-align: baseline;
}
sup {
top: -0.5em;
}
sub {
bottom: -0.25em;
}
/* Embedded content
========================================================================== */
/**
* Remove border when inside `a` element in IE 8/9/10.
*/
img {
border: 0;
}
/**
* Correct overflow not hidden in IE 9/10/11.
*/
svg:not(:root) {
overflow: hidden;
}
/* Grouping content
========================================================================== */
/**
* Address margin not present in IE 8/9 and Safari.
*/
figure {
margin: 1em 40px;
}
/**
* Address differences between Firefox and other browsers.
*/
hr {
height: 0;
-moz-box-sizing: content-box;
box-sizing: content-box;
}
/**
* Contain overflow in all browsers.
*/
pre {
overflow: auto;
}
/**
* Address odd `em`-unit font size rendering in all browsers.
*/
code,
kbd,
pre,
samp {
font-family: monospace, monospace;
font-size: 1em;
}
/* Forms
========================================================================== */
/**
* Known limitation: by default, Chrome and Safari on OS X allow very limited
* styling of `select`, unless a `border` property is set.
*/
/**
* 1. Correct color not being inherited.
* Known issue: affects color of disabled elements.
* 2. Correct font properties not being inherited.
* 3. Address margins set differently in Firefox 4+, Safari, and Chrome.
*/
button,
input,
optgroup,
select,
textarea {
margin: 0; /* 3 */
font: inherit; /* 2 */
color: inherit; /* 1 */
}
/**
* Address `overflow` set to `hidden` in IE 8/9/10/11.
*/
button {
overflow: visible;
}
/**
* Address inconsistent `text-transform` inheritance for `button` and `select`.
* All other form control elements do not inherit `text-transform` values.
* Correct `button` style inheritance in Firefox, IE 8/9/10/11, and Opera.
* Correct `select` style inheritance in Firefox.
*/
button,
select {
text-transform: none;
}
/**
* 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio`
* and `video` controls.
* 2. Correct inability to style clickable `input` types in iOS.
* 3. Improve usability and consistency of cursor style between image-type
* `input` and others.
*/
button,
html input[type="button"], /* 1 */
input[type="reset"],
input[type="submit"] {
-webkit-appearance: button; /* 2 */
cursor: pointer; /* 3 */
}
/**
* Re-set default cursor for disabled elements.
*/
button[disabled],
html input[disabled] {
cursor: default;
}
/**
* Remove inner padding and border in Firefox 4+.
*/
button::-moz-focus-inner,
input::-moz-focus-inner {
padding: 0;
border: 0;
}
/**
* Address Firefox 4+ setting `line-height` on `input` using `!important` in
* the UA stylesheet.
*/
input {
line-height: normal;
}
/**
* It's recommended that you don't attempt to style these elements.
* Firefox's implementation doesn't respect box-sizing, padding, or width.
*
* 1. Address box sizing set to `content-box` in IE 8/9/10.
* 2. Remove excess padding in IE 8/9/10.
*/
input[type="checkbox"],
input[type="radio"] {
box-sizing: border-box; /* 1 */
padding: 0; /* 2 */
}
/**
* Fix the cursor style for Chrome's increment/decrement buttons. For certain
* `font-size` values of the `input`, it causes the cursor style of the
* decrement button to change from `default` to `text`.
*/
input[type="number"]::-webkit-inner-spin-button,
input[type="number"]::-webkit-outer-spin-button {
height: auto;
}
/**
* 1. Address `appearance` set to `searchfield` in Safari and Chrome.
* 2. Address `box-sizing` set to `border-box` in Safari and Chrome
* (include `-moz` to future-proof).
*/
input[type="search"] {
-webkit-box-sizing: content-box; /* 2 */
-moz-box-sizing: content-box;
box-sizing: content-box;
-webkit-appearance: textfield; /* 1 */
}
/**
* Remove inner padding and search cancel button in Safari and Chrome on OS X.
* Safari (but not Chrome) clips the cancel button when the search input has
* padding (and `textfield` appearance).
*/
input[type="search"]::-webkit-search-cancel-button,
input[type="search"]::-webkit-search-decoration {
-webkit-appearance: none;
}
/**
* Define consistent border, margin, and padding.
*/
fieldset {
padding: 0.35em 0.625em 0.75em;
margin: 0 2px;
border: 1px solid #c0c0c0;
}
/**
* 1. Correct `color` not being inherited in IE 8/9/10/11.
* 2. Remove padding so people aren't caught out if they zero out fieldsets.
*/
legend {
padding: 0; /* 2 */
border: 0; /* 1 */
}
/**
* Remove default vertical scrollbar in IE 8/9/10/11.
*/
textarea {
overflow: auto;
}
/**
* Don't inherit the `font-weight` (applied by a rule above).
* NOTE: the default cannot safely be changed in Chrome and Safari on OS X.
*/
optgroup {
font-weight: bold;
}
/* Tables
========================================================================== */
/**
* Remove most spacing between table cells.
*/
table {
border-spacing: 0;
border-collapse: collapse;
}
td,
th {
padding: 0;
}
/* LAYOUT STYLES */
body {
font-family: 'Helvetica Neue', Helvetica, Arial, serif;
font-size: 15px;
font-weight: 400;
line-height: 1.5;
color: #666;
background: #fafafa url(../images/body-bg.jpg) 0 0 repeat;
}
p {
margin-top: 0;
}
a {
color: #2879d0;
}
a:hover {
color: #2268b2;
}
header {
padding-top: 40px;
padding-bottom: 40px;
font-family: 'Architects Daughter', 'Helvetica Neue', Helvetica, Arial, serif;
background: #2e7bcf url(../images/header-bg.jpg) 0 0 repeat-x;
border-bottom: solid 1px #275da1;
}
header h1 {
width: 540px;
margin-top: 0;
margin-bottom: 0.2em;
font-size: 72px;
font-weight: normal;
line-height: 1;
color: #fff;
letter-spacing: -1px;
}
header h2 {
width: 540px;
margin-top: 0;
margin-bottom: 0;
font-size: 26px;
font-weight: normal;
line-height: 1.3;
color: #9ddcff;
letter-spacing: 0;
}
.inner {
position: relative;
width: 940px;
margin: 0 auto;
}
#content-wrapper {
padding-top: 30px;
border-top: solid 1px #fff;
}
#main-content {
float: left;
width: 690px;
}
#main-content img {
max-width: 100%;
}
aside#sidebar {
float: right;
width: 200px;
min-height: 504px;
padding-left: 20px;
font-size: 12px;
line-height: 1.3;
background: transparent url(../images/sidebar-bg.jpg) 0 0 no-repeat;
}
aside#sidebar p.repo-owner,
aside#sidebar p.repo-owner a {
font-weight: bold;
}
#downloads {
margin-bottom: 40px;
}
a.button {
width: 134px;
height: 58px;
padding-top: 22px;
padding-left: 68px;
font-family: 'Architects Daughter', 'Helvetica Neue', Helvetica, Arial, serif;
font-size: 23px;
line-height: 1.2;
color: #fff;
}
a.button small {
display: block;
font-size: 11px;
}
header a.button {
position: absolute;
top: 0;
right: 0;
background: transparent url(../images/github-button.png) 0 0 no-repeat;
}
aside a.button {
display: block;
width: 138px;
padding-left: 64px;
margin-bottom: 20px;
font-size: 21px;
background: transparent url(../images/download-button.png) 0 0 no-repeat;
}
code, pre {
margin-bottom: 30px;
font-family: Monaco, "Bitstream Vera Sans Mono", "Lucida Console", Terminal, monospace;
font-size: 13px;
color: #222;
}
code {
padding: 0 3px;
background-color: #f2f8fc;
border: solid 1px #dbe7f3;
}
pre {
padding: 20px;
overflow: auto;
text-shadow: none;
background: #fff;
border: solid 1px #f2f2f2;
}
pre code {
padding: 0;
color: #db0000;
background-color: #fff;
border: none;
}
ul, ol, dl {
margin-left: 15px;
margin-bottom: 20px;
}
/* COMMON STYLES */
hr {
height: 0;
margin-top: 1em;
margin-bottom: 1em;
border: 0;
border-top: solid 1px #ddd;
}
table {
width: 100%;
border: 1px solid #ebebeb;
}
th {
font-weight: 500;
}
td {
font-weight: 300;
text-align: center;
border: 1px solid #ebebeb;
}
form {
padding: 20px;
background: #f2f2f2;
}
/* GENERAL ELEMENT TYPE STYLES */
#main-content h1 {
margin-top: 0;
margin-bottom: 0;
font-family: 'Architects Daughter', 'Helvetica Neue', Helvetica, Arial, serif;
font-size: 2.8em;
font-weight: normal;
color: #474747;
text-indent: 6px;
letter-spacing: -1px;
}
#main-content h1:before {
padding-right: 0.3em;
margin-left: -0.9em;
color: #9ddcff;
content: "/";
}
#main-content h2 {
margin-bottom: 8px;
font-family: 'Architects Daughter', 'Helvetica Neue', Helvetica, Arial, serif;
font-size: 22px;
font-weight: bold;
color: #474747;
text-indent: 4px;
}
#main-content h2:before {
padding-right: 0.3em;
margin-left: -1.5em;
content: "//";
color: #9ddcff;
}
#main-content h3 {
margin-top: 24px;
margin-bottom: 8px;
font-family: 'Architects Daughter', 'Helvetica Neue', Helvetica, Arial, serif;
font-size: 18px;
font-weight: bold;
color: #474747;
text-indent: 3px;
}
#main-content h3:before {
padding-right: 0.3em;
margin-left: -2em;
content: "///";
color: #9ddcff;
}
#main-content h4 {
margin-bottom: 8px;
font-family: 'Architects Daughter', 'Helvetica Neue', Helvetica, Arial, serif;
font-size: 15px;
font-weight: bold;
color: #474747;
text-indent: 3px;
}
h4:before {
padding-right: 0.3em;
margin-left: -2.8em;
content: "////";
color: #9ddcff;
}
#main-content h5 {
margin-bottom: 8px;
font-family: 'Architects Daughter', 'Helvetica Neue', Helvetica, Arial, serif;
font-size: 14px;
color: #474747;
text-indent: 3px;
}
h5:before {
padding-right: 0.3em;
margin-left: -3.2em;
content: "/////";
color: #9ddcff;
}
#main-content h6 {
margin-bottom: 8px;
font-family: 'Architects Daughter', 'Helvetica Neue', Helvetica, Arial, serif;
font-size: .8em;
color: #474747;
text-indent: 3px;
}
h6:before {
padding-right: 0.3em;
margin-left: -3.7em;
content: "//////";
color: #9ddcff;
}
p {
margin-bottom: 20px;
}
a {
text-decoration: none;
}
p a {
font-weight: 400;
}
blockquote {
padding: 0 0 0 30px;
margin-bottom: 20px;
font-size: 1.6em;
border-left: 10px solid #e9e9e9;
}
ul {
list-style-position: inside;
list-style: disc;
padding-left: 20px;
}
ol {
list-style-position: inside;
list-style: decimal;
padding-left: 3px;
}
dl dd {
font-style: italic;
font-weight: 100;
}
/* MISC */
.clearfix:after {
display: block;
height: 0;
clear: both;
visibility: hidden;
content: '.';
}
.clearfix {display: inline-block;}
* html .clearfix {height: 1%;}
.clearfix {display: block;}
/* #Media Queries
================================================== */
/* Smaller than standard 960 (devices and browsers) */
@media only screen and (max-width: 959px) { }
/* Tablet Portrait size to standard 960 (devices and browsers) */
@media only screen and (min-width: 768px) and (max-width: 959px) {
.inner {
width: 740px;
}
header h1, header h2 {
width: 340px;
}
header h1 {
font-size: 60px;
}
header h2 {
font-size: 30px;
}
#main-content {
width: 490px;
}
#main-content h1:before,
#main-content h2:before,
#main-content h3:before,
#main-content h4:before,
#main-content h5:before,
#main-content h6:before {
padding-right: 0;
margin-left: 0;
content: none;
}
}
/* All Mobile Sizes (devices and browser) */
@media only screen and (max-width: 767px) {
.inner {
width: 93%;
}
header {
padding: 20px 0;
}
header .inner {
position: relative;
}
header h1, header h2 {
width: 100%;
}
header h1 {
font-size: 48px;
}
header h2 {
font-size: 24px;
}
header a.button {
position: relative;
display: inline-block;
width: auto;
height: auto;
padding: 5px 10px;
margin-top: 15px;
font-size: 13px;
line-height: 1;
color: #2879d0;
text-align: center;
background-color: #9ddcff;
background-image: none;
border-radius: 5px;
-moz-border-radius: 5px;
-webkit-border-radius: 5px;
}
header a.button small {
display: inline;
font-size: 13px;
}
#main-content,
aside#sidebar {
float: none;
width: 100% ! important;
}
aside#sidebar {
min-height: 0;
padding: 20px 0;
margin-top: 20px;
background-image: none;
border-top: solid 1px #ddd;
}
aside#sidebar a.button {
display: none;
}
#main-content h1:before,
#main-content h2:before,
#main-content h3:before,
#main-content h4:before,
#main-content h5:before,
#main-content h6:before {
padding-right: 0;
margin-left: 0;
content: none;
}
}
/* Mobile Landscape Size to Tablet Portrait (devices and browsers) */
@media only screen and (min-width: 480px) and (max-width: 767px) { }
/* Mobile Portrait Size to Mobile Landscape Size (devices and browsers) */
@media only screen and (max-width: 479px) { }
</style>
</head>
<body>
<h1 id="building-android">Building Android README</h1>
<p><strong>Author's Note</strong>: The following gives a detailed overview for everything needed in order to build a RapidGame project for Android. Most of this README is about what is required for Android development in general. As such, there will be redundant information for those who are already familiar with the topic. If that is the case, it is still recommended that you still skim through this README. - <a href="https://github.com/samoersnaes" target="_blank">Samuel Ørsnæs</a></p>
<h1 id="dont-forget">Don't Forget! (Windows only)</h1>
<p>Run <code>rapidgame prebuild android</code> in a <strong>Cygwin shell</strong> to make sure the Android libraries are prebuilt.</p>
<h1 id="index">Index</h1>
<ol>
<li><a href="#tl-dr">TL;DR</a></li>
<li><a href="#prefer-video">Prefer a video instead?</a></li>
<li><a href="#prerequisite-downloads-">Prerequisite Downloads</a></li>
<li><a href="#setup-environment-variables-">Setup Environment Variables</a></li>
<li><a href="#building-your-project">Building Your Project</a></li>
<li><a href="#modifying-for-your-needs">Modifying for Your Needs</a></li>
<li><a href="#building-for-different-architectures">Building for Different Architectures</a></li>
<li><a href="#useful-tools">Useful Resources and Tools</a></li>
<li><a href="#environment-variables-intro">Environment Variables Intro</a></li>
<li><a href="#help">Help!</a></li>
</ol>
<h1 id="tl-dr">TL;DR</h1>
<ul>
<li>Make sure you have all the programs that are under <a href="#prerequisite-downloads-">Prequisite Downloads</a></li>
<li>Check your environment variables against the list in <a href="#setup-environment-variables-">Setup Environment Variables</a></li>
<li><code>cd [APPNAME]/Projects/android && make</code></li>
<li><a href="http://www.kingoapp.com/root-tutorials/how-to-enable-usb-debugging-mode-on-android.htm" target="_blank">Enable USB debugging</a> for your Android device</li>
<li>Plug in your Android device via USB</li>
<li><code>make run</code></li>
<li>Find the app on your device and launch it</li>
</ul>
<p>You can create, delete, and edit source files under <code>[APPNAME]/Projects</code> and assets under <code>[APPNAME]/Assets</code> as you wish. Changes in these folders will be included in the Android build automatically.</p>
<h1 id="prefer-video">Prefer a video instead?</h1>
<iframe width="560" height="315" src="https://www.youtube.com/embed/5PWEtjvhX1k" frameborder="0" allowfullscreen></iframe>
<h1 id="prerequisite-downloads-">Prerequisite Downloads</h1>
<ul>
<li><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html" target="_blank">JDK</a> (Java Development Kit)</li>
<li><a href="http://developer.android.com/sdk/index.html" target="_blank">Android Studio</a> (includes the Android SDK and many other tools)</li>
<li><a href="https://developer.android.com/ndk/downloads/index.html" target="_blank">Android NDK</a> (native Android development: C and C++)</li>
<li><a href="http://ant.apache.org/bindownload.cgi" target="_blank">Apache Ant</a> (needed to build .apk's)</li>
<li><a href="https://www.python.org/downloads" target="_blank">Python</a> (<strong>2.7.x required</strong>)</li>
<li><a href="https://www.cygwin.com/" target="_blank">Cygwin</a> (<strong>only required for Windows users</strong>; download the `Devel` packages as well in setup)</li>
</ul>
<p>As the Android NDK and Ant are compressed folders (not something you install), you choose where you want to unpack them. According to the NDK, the path to it may not contain any spaces (e.g. <code>/path to my/ndk</code> is not allowed).</p>
<p>After downloading Android Studio, you will need to download the APIs for the OS version that you want to target. You could for example choose Android 4.3.1 (API 18) as your target OS. It turns out that the template project that comes with RapidGame targets API 18, while cocos2d-x/js itself targets API 10. This means that you must download these particular APIs before you can build the template project. In order to do so, you go to Android Studio > Configure > SDK Manager > [Select and install appropriate packages]. If you had previously created a project in Android Studio, then launching Android Studio will open up directly to the IDE. To navigate to the SDK Manager from there, you go to Tools > Android > SDK Manager.</p>
<p><strong>(Windows only)</strong> Cygwin must be installed for all users (this is the recommended option in Cygwin's setup), which installs Cygwin in your root directory (<code>C:\Cygwin</code> or <code>C:\Cygwin64</code>). You should of course install the 64-bit version if you have a 64-bit machine. After you download the setup program found on their front page, you should keep this file stored somewhere safe in case you want to add packages or update Cygwin later. It is recommended that you use a Cygwin shell anytime you need to interact with the command line for your project. When you create a cocos2d-x/js project with RapidGame (<code>rapidgame create</code>), you must run Cygwin as administrator (right-click on `Cygwin Terminal` > `Run as administrator`). This is to ensure that the <code>lib</code> symlink is properly created. If you find installing Cygwin to be a bit intimidating, check out the <a href="#help">Help!</a></p>
<h1 id="setup-environment-variables-">Setup Environment Variables</h1>
<p>Before building your first project, you should make sure all the necessary environment variables are set. If you don't know what that means, refer to <a href="#environment-variables-intro">Environment Variables Intro</a>.</p>
<pre><code>ANDROID_SDK_ROOT = /path/to/sdk
ANT_HOME = /path/to/ant
ANT_ROOT = /path/to/ant/bin
JAVA_HOME = /path/to/jdk
NDK_ROOT = /path/to/ndk
PATH = $PATH,
/path/to/python,
/path/to/jdk/bin,
/path/to/ndk,
/path/to/sdk/build-tools/[VERSION],
/path/to/sdk/platform-tools,
/path/to/sdk/tools
</code></pre>
<p>The above is a generic representation of the environment variables and not proper syntax. It up to you to format the information for your system.</p>
<p><strong>(Windows only)</strong> In addition to setting the above environment variables for your host OS, you must also set <code>ANDROID_SDK_ROOT</code> and <code>NDK_ROOT</code> in Cygwin's <code>~/.bash_profile</code> as you would on <a href="#mac">Mac</a>. The formatting should be as follows:</p>
<pre><code>export ANDROID_SDK_ROOT=C:/path/to/sdk
export NDK_ROOT=C:/path/to/ndk
</code></pre>
<p><strong>Windows defaults:</strong></p>
<ul>
<li>Python <code>C:\PythonXX</code></li>
<li>JDK <code>C:\Program Files\Java\jdk1.X</code></li>
<li>Android SDK <code>C:\Users\[USERNAME]\AppData\Local\Android\sdk</code></li>
</ul>
<h1 id="building-your-project">Building Your Project</h1>
<pre><code>MyGame = example root project directory</code></pre>
<ul>
<li>You can edit your source files however you like, whether in an IDE or in a plain text editor.</li>
<li>You must save your source files in <code>MyGame/Projects</code> and your assets in <code>MyGame/Assets</code>.</li>
<li>To build your project, you must execute one of the commands listed below.</li>
<li>Before you run these commands, make sure you change your working directory (<code>cd</code>) to <code>MyGame/Projects/android</code>.</li>
<li>When you run <code>make</code>, your entire project will be built and packaged into an .apk file (the file that goes on your Android device).</li>
<li><code>make</code> will intelligently keep track of new and deleted files, so you don't have to.</li>
<li><code>make</code> will only keep track of the C and C++ (<code>.c</code>, <code>.cpp</code>, <code>.cc</code>, <code>.cxx</code>) source files in <code>MyGame/Projects</code>. This means if you have Objective-C (<code>.m</code>, <code>.mm</code>) files specific to iOS and Mac, <code>make</code> will ignore them when building your Android project.</li>
<li>You can add C/C++ files that you want to exclude from the Android build, one file per line, in <code>MyGame/Projects/android/makeignore</code>.</li>
<li>Your C/C++ filenames must not contain any spaces in them (e.g. <code>my cpp file.cpp</code> is not allowed).</li>
<li>You can change the behavior of <code>make</code> (such as what sort of output is logged to the console) by editing <code>MyGame/Projects/android/makefile</code>. Be careful of your changes, as they could adversely affect the build process or prevent you from building your project.</li>
</ul>
<h3>Commands</h3>
<ol>
<li>
<code>make</code>: Builds the debug version of your game and signs the .apk with the debug key (produces <code>APPNAME-debug.apk</code>). If you have never signed an Android application before and are prompted to enter information pertaining to the debug key, here is the info you need:
<p></p>
<pre><code>Absolute path:
(Mac) /Users/[USERNAME]/.android/debug.keystore
(Win) C:/Users/[USERNAME]/.android/debug.keystore
Keystore name: debug.keystore
Keystore password: android
Key alias: androiddebugkey
Key password: android
CN: CN=Android Debug,0=Android,C=US
</code></pre>
</li>
<li><code>make release</code>: Builds the release version of your game but creates the .apk file using the debug key (produces <code>APPNAME-debug.apk</code>).</li>
<li><code>make distribution</code>: Builds the release version of your game and signs the .apk with the release key (produces <code>APPNAME-release-aligned.apk</code>). For info on how to create a release key and sign your app, refer to <a href="http://developer.android.com/tools/publishing/app-signing.html" target="_blank">this page</a>. If you prefer to do everything on the command line, <a href="http://developer.android.com/tools/publishing/app-signing.html#signing-manually" target="_blank">take a look here</a>. The commands are OS-agnostic, so they are the same on Mac and Windows.</li>
<li><code>make run</code>: You need to have run one of the above commands first. Your Android device must also have <a href="http://www.kingoapp.com/root-tutorials/how-to-enable-usb-debugging-mode-on-android.htm" target="_blank">USB debugging enabled</a> and be plugged in via USB. Installs <code>APPNAME-debug.apk</code> on your Android device and begins printing log output to the console. <code>make run</code> does not launch your app after installing it. As for the log output, the default settings--specified in the <code>makefile</code>--print debug output from your app and fatal errors from everywhere else. For more about how logging works, refer to <a href="http://developer.android.com/tools/debugging/debugging-log.html" target="_blank">this page</a>. If you want all future projects to keep a particular setting, you can <a href="https://github.com/NatWeiss/RapidGame#create-your-own-templates" target="_blank">create your own RapidGame template</a>.</li>
<li><code>make run-relase</code>: Installs <code>APPNAME-debug.apk</code> on your device and logs output to the console, exactly as <code>make run</code> does. However, you can modify the makefile to change what kind of logs you will see when you execute one command versus the other.</li>
<li><code>make run-distribution</code>: Installs <code>APPNAME-release-aligned.apk</code> on your device and logs output to the console. You need to have run <code>make distribution</code> first.</li>
<li><code>make clean</code>: Removes all the files and folders that are created when you build your game. Run this to clean up your Android project before you rebuild it.</li>
<li><code>make start-emulator</code>: You will first need to create an Android Virtual Device (AVD) using AVD Manager, which can be found at <code>$ANDROID_SDK_ROOT/AVD Manager</code>, or by opening Android Studio and navigating to Tools > Android > AVD Manager. The AVD you create should be set to use the ARM architecture, because 1) RapidGame Android projects can only build for ARM, and 2) an emulated x86 device requires you to download and configure several things before you can emulate that architecture. You will then need open the <code>makefile</code> and uncomment <code>#emulator -avd [device_name]</code> by removing the <code>#</code> and then replacing <code>[device_name]</code> with the name of the AVD you want to use for testing. In addition, uncomment the lines under <code>run-emulator</code>. Although the emulator is useful for testing your game in different environments, you should thoroughly test your game on at least a few physical Android devices before you release it. Take a look <a href="https://www.genymotion.com" target="_blank">here</a> as well if you want to try a faster Android emulation solution.</li>
<li><code>make run-emulator</code>: Installs <code>APPNAME-debug.apk</code> on your chosen AVD. The selected AVD must already be running (<code>make start-emulator</code>).</li>
</ol>
<h1 id="modifying-for-your-needs">Modifying for Your Needs</h1>
<p>If you are new to Android development, you may have questions about all the files that are in <code>MyGame/Projects/android</code>. First off, these files do not need to be changed in any way in order to get the template project running. However, they are needed in order to specify the metadata of your game, such as what the target Android OS version is, or whether your game starts in portrait or landscape, or what kind of permissions you want access to and what kind of hardware features your game requires. The following is a summary of the files you may want to modify for some reason or another in order to fit your needs. If you want a good starting point for better understanding of Android metadata files, <a href="http://developer.android.com/guide/components/fundamentals.html" target="_blank">this page</a> is a place to start.</p>
<ul>
<li><code>.identifier</code>: The package identifier for your game.</li>
<li><code>.name</code>: The name of your game.</li>
<li><code>AndroidManifest.xml</code>: This is the main file you will need to muck around with if you want to change any metadata about your game. Refer to the page mentioned above to see what's contained in the file itself and how to modify it.</li>
<li><code>ant.properties</code>: Add your keystore information to this file so that you are automatically prompted for the release key's password when you run <code>make distribution</code>. Refer <a href="http://developer.android.com/tools/publishing/app-signing.html" target="_blank">here</a> if you don't know what a keystore is or how to make one.</li>
<li><code>makefile</code>: Tells <code>make</code> what to do to build your project for each of the possible targets. You could for example change how verbose you want <code>adb logcat</code> to be when printing output to the console.</li>
<li><code>makeignore</code>: The list of C/C++ source files under <code>MyGame/Projects</code> that you don't want included in the Android build of your game.</li>
</ul>
<h1 id="building-for-different-architectures">Building for Different Architectures</h1>
<p>As your app is built using what Android considers native code (C++), your final .apk will contain code compiled for a specific architecture. If you were writing a pure Java app, that app would run on any device without needing to compile for each architecture thanks to the JVM. By default, your Android game is set to build for the ARM (armeabi) architecture, which a huge majority of Android devices use (think the equivalent to Intel's dominance in desktop computing). However, there is another version of ARM known as ARMv7, which is an architecture that is backwards compatitable with ARM, so you can just build your app for ARM and it will run on newer ARMv7 devices just fine. The main advantage of ARMv7 is faster floating point operations, so you may find your game performs better on newer devices. For more specific info on the different architectures, <a href="https://chromium.googlesource.com/android_tools/+/master-backup/ndk/docs/CPU-ARCH-ABIS.html" target="_blank">refer here</a>. You can find out much more extensive documentation about the NDK in general by going to <code>$NDK_ROOT/docs/Start_Here.html</code>.</p>
<p>In order to actually get your project to compile for both ARM and ARMv7, you can edit <code>APP_ABI</code> in <code>MyGame/Projects/android/Application.mk</code> to read <code>APP_ABI := armeabi armeabi-v7a</code>. When you rebuild your project with <code>make</code>, the .apk will now contain the files for both ARM and ARMv7, and when the .apk is installed on a device, the necessary files will be used depending on the processor. One thing that must be noted is that when you build for ARMv7, you will get a long list of warning messages, and these messages will continue scrolling on the screen for several minutes until finally your game finishes building. There is nothing that can be done to prevent these warning messages (if you discover a way, please let us know on <a href="https://github.com/NatWeiss/RapidGame/issues" target="_blank">RapidGame's issues page</a> (requires a Github account)), but they are harmless. Your game will still compile and run without issue. However, to speed up build time, you should only build for ARM during the development stage of your game. If your .apk gets to be over 50MB and you are considering submitting multiple .apk's for your game, then there are <a href="http://developer.android.com/google/play/publishing/multiple-apks.html" target="_blank">certain rules</a> you must be aware of.</p>
<h1 id="useful-tools">Useful Resources and Tools</h1>
<ul>
<li><a href="http://wizardfu.com/book/cocos2d-x/" target="_blank">Cocos2d-x Book</a>: Free book for learning cocos2d-x and game design from the author of RapidGame.</li>
<li><a href="https://github.com/NatWeiss/EntityFu" target="_blank">EntityFu</a>: A C++ Entity Component System, also written by Nathanael. See the project's README for a guide on component-based programming if you are unfamiliar with it.</li>
<li><a href="https://game-development.zeef.com/david.arcila" target="_blank">Game Development Resources</a>: Tools, assets, and other info galore. Look here if you need a free tool to do something for your game.</li>
<li><a href="http://ds.arm.com/ds-5-community-edition/" target="_blank">ARM DS-5 Community Edition</a>: As you are using the Android NDK and a language other than Java to build your app, the profiling and debugging tools that come with Android Studio will not work for your game. However, ARM offers free tools that you can use to optimize performance, find memory leaks, and profile your app in different ways. This tool comes standard in <a href="http://www.cocos2d-x.org/download" target="_blank">Cocos Code IDE</a>.</li>
<li><a href="https://www.genymotion.com" target="_blank">GenyMotion</a>: Emulate different Android environments on your computer; faster than the emulator solution that comes with Android Studio.</li>
</ul>
<h1 id="environment-variables-intro">Environment Variables Intro</h1>
<p>If you're not familiar with environment variables, they are variables that are accessible by any program on your computer, which makes them very powerful and important. One example of this usefulness is that when you type a command like <code>python</code> in your console, your computer doesn't automatically know where to find it. However, all major operating systems have a variable called <code>PATH</code>, that is a list of directories, which your computer searches in to find if there's something related to what you typed on the command line. So when you type <code>python</code> in your shell, the OS looks in all the directories listed in <code>PATH</code> and when it finds an executable named <code>python</code>, it executes that program. The following will explain how to properly set environment variables for your particular OS.</p>
<h3 id="mac">Mac</h3>
<p>Environment variables can be set in a plain text file known as <code>~/.bash_profile</code> (<code>~</code> signifies your home directory, which is <code>/Users/[USERNAME]</code> on Mac). You can check that the file exists by running <code>cd ~ && ls -a</code>. To open the file, use your preferred text editor, such as <code>nano .bash_profile</code>. You will find other code written in the file already, which you should ignore. Go to the bottom of the file to add your specific environment variables. The format is as follows:</p>
<pre><code>export var1=/path/to/var1
export var2=/path/to/var2
# We want to keep the original variable and append new paths to it
export PATH=$PATH:/path/to/something/else:/path/to/another/thing
</code></pre>
<p>When you are done editing the file, save and close it and then run <code>cd ~ && source .bash_profile</code> and you're good to go. If you want to double-check that the variable has the correct value, you can type <code>echo $VAR</code>, which will print the value of <code>VAR</code> back to you.</p>
<h3 id="windows">Windows</h3>
<p>For Windows, the easiest way to edit your environment variables is by pressing the Windows button, searching "environment variables", and clicking on the link that comes up. A window should open that is divided into user and system variables, and we are only interested in editing user variables. Be sure to check if the variable already exists before trying to create a new one. Each variable has a name and a value, so if we were setting <code>ANDROID_SDK_ROOT</code>, then that would be the name, and the value might be <code>C:\Users\John\AppData\Local\Android\sdk</code>. If you want to add to an already existing variable, then you add the path to add to the beginning of the value and then place a <code>;</code> between the path you added and the rest of the value, e.g. we want to add Python's path to some other paths, so the final result would look like: <code>C:\Python27;C:\Program Files\Directory Containing MyProgram;C:\other\things</code>.</p>
<h1 id="help">Help!</h1>
<pre><code>MyGame = example root project directory</code></pre>
<h3>Where do I save my code/assets?</h3>
<p>You save your source files in <code>MyGame/Projects</code> and your assets in <code>MyGame/Assets</code>. You can see what goes into the .apk by running <code>unzip -l MyGame/Projects/android/bin/[APKNAME]</code>.</p>
<h3>I'm having trouble with the NDK!</h3>
<p>Move the NDK folder to a path without any spaces.</p>
<h3>How do I install Cygwin?</h3>
<ol>
<li>Launch setup program</li>
<li>(Welcome page) > Next</li>
<li>Install from Internet > Next</li>
<li>Install for `All Users` > Next</li>
<li>Choose a safe directory > Next</li>
<li>Direct connection > Next</li>
<li>Choose a mirror (anyone but the first) > Next</li>
<li>Click the icon to the right of `Devel` to change it from `Default` to `Install` > Next</li>
<li>`Select required packages` should be checked > Next</li>
<li>Wait... > Finish</li>
</ol>
<h3>I ran <code>make run</code> and all I get is `waiting for device`!</h3>
<p>Have you <a href="http://www.kingoapp.com/root-tutorials/how-to-enable-usb-debugging-mode-on-android.htm" target="_blank">enabled USB debugging for your device</a>? Is your device plugged in via USB? Type <code>adb devices</code> to see if your device has been recognized. If you don't see your device, close the shell you are using and open a new one. Type <code>adb devices</code> one more time and your device should appear. Now you can execute <code>make run</code>.</p>
<h3>Where do I ask a question/submit an issue?</h3>
<p><a href="https://github.com/NatWeiss/RapidGame/issues" target="_blank">Here.</a> You need a GitHub account first.</p>
</body>
</html>