| {namespace buck.quickstart} |
| |
| /***/ |
| {template .soyweb} |
| |
| {call buck.header} |
| {param title: 'Quick Start' /} |
| {/call} |
| |
| <div class="{css overview}"> |
| |
| {call buck.platformWarning /} |
| |
| This is a quick start guide for getting up and running with Buck. |
| This article is light on details, instead focusing on the commands |
| that you need to run to build your first Android application from scratch |
| using Buck. |
| You can find a more detailed explanation about each step in the development |
| process by reading the individual articles on more specific topics. |
| <p> |
| If you have built an Android application before, then you likely have |
| all of the tools required by Buck installed on your computer already. |
| For more detailed instructions for installing Buck, please see{sp} |
| <a href="install.html">Downloading and Installing Buck</a>. |
| <p> |
| <strong>Note:</strong> The commands in this guide are designed to be |
| copy-pasteable, idempotent, and usable on both Mac OS X and Linux. |
| Sometimes this results in some unusual constructions (such as using |
| {sp}<code>echo</code> instead of |
| {sp}<code>vi</code> or <code>emacs</code> to create a file). |
| Bear in mind that this is a <em>quick</em> start guide, |
| so few things are quicker than copy-and-paste! |
| |
| <h2>Install Buck</h2> |
| |
| Run the following commands to checkout Buck from GitHub, build it, and add it to your <code>$PATH</code>: |
| {call buck.installationInstructions}{param withAlias : true /}{/call} |
| |
| <em>Currently, there is no way to download a precompiled binary for Buck.</em> |
| |
| <p> |
| |
| Now that you have Buck installed on your machine, |
| let's use it to build a sample Android application. |
| We should start our project in an empty directory, |
| so create a new one and navigate to it: |
| |
| {literal}<pre> |
| mkdir -p ~/my-first-buck-project/ |
| cd ~/my-first-buck-project/ |
| </pre>{/literal} |
| |
| <strong>Note: the following instructions will now assume that all commands are run from |
| your <code>~/my-first-buck-project</code> directory.</strong> |
| |
| <h2>Compile Java</h2> |
| |
| Android applications are typically written in Java, so the first thing |
| we will do is configure Buck to compile Java code against the Android API. |
| To do so, Buck needs to know where your Android SDK is. Assuming that your |
| Android SDK is installed in <code>~/android-sdk-mac</code>, run the |
| following command to create a <code>local.properties</code> file that tells |
| Buck where to find your Android SDK: |
| |
| {literal}<pre> |
| echo -n sdk.dir= > local.properties && \ |
| echo ~/android-sdk-mac >> local.properties |
| </pre>{/literal} |
| |
| Now that Buck can locate your Android SDK, it is time to compile some Java |
| code. First, we create a simple <code>Activity</code> at{sp} |
| <code>java/com/example/activity/MyFirstActivity.java</code>: |
| |
| {literal}<pre> |
| mkdir -p java/com/example/activity/ |
| echo "package com.example.activity; |
| |
| import android.app.Activity; |
| import android.os.Bundle; |
| |
| public class MyFirstActivity extends Activity { |
| |
| @Override |
| public void onCreate(Bundle savedInstanceState) { |
| |
| } |
| }" > java/com/example/activity/MyFirstActivity.java |
| </pre>{/literal} |
| |
| Now we need a build file that defines a build rule to compile |
| this Java code, so we create an |
| {sp}<code><a href="rule/android_library.html">android_library()</a></code>{sp} |
| rule in <code>java/com/example/activity/BUCK</code>: |
| |
| {literal}<pre> |
| echo "android_library( |
| name = 'activity', |
| srcs = glob(['*.java']), |
| visibility = [ 'PUBLIC' ], |
| ) |
| |
| project_config( |
| src_target = ':activity', |
| )" > java/com/example/activity/BUCK |
| </pre>{/literal} |
| |
| Now we can compile our Java code using Buck: |
| |
| <pre>buck build{sp}//java/com/example/activity:activity</pre> |
| |
| <strong>Note:</strong> Buck generates its output in |
| the <code>buck-out</code> directory, |
| so this is a good time to specify <code>buck-out</code> as something that |
| should be ignored by your version control system. |
| |
| |
| <h2>Package Resources</h2> |
| |
| Android applications frequently contain resources, such as strings and images. |
| For this example, we will create a trivial Android resource bundle that contains |
| a single string: |
| |
| {literal}<pre> |
| mkdir -p res/com/example/activity/res/values/ |
| echo "<?xml version='1.0' encoding='utf-8' ?> |
| <resources> |
| <string name='app_name'>Hello World</string> |
| </resources>" > res/com/example/activity/res/values/strings.xml |
| </pre>{/literal} |
| |
| Buck needs a way to reference this collection of resources, so we need to |
| create a build file that defines an |
| {sp}<code><a href="rule/android_resource.html">android_resource()</a></code>{sp} |
| rule: |
| |
| {literal}<pre> |
| echo "android_resource( |
| name = 'res', |
| res = 'res', |
| package = 'com.example', |
| visibility = [ |
| '//apps/myapp:', |
| ], |
| ) |
| |
| project_config( |
| src_target = ':res', |
| )" > res/com/example/activity/BUCK |
| </pre>{/literal} |
| |
| <h2>Create a Keystore</h2> |
| |
| In practice, you will want to be able to test your Android app on a |
| physical Android device, which means that it needs to be signed. |
| <p> |
| We will create app-specific information, such as the key and manifest, |
| in its own directory to keep things tidy: |
| |
| <pre>mkdir -p apps/myapp/</pre> |
| |
| To keep things simple, we will create a self-signed certificate for |
| debugging. Unfortunately, this is not a one-liner because there is a |
| number of prompts from the <code>keytool</code> command: |
| |
| {literal}<pre> |
| keytool -genkey -keystore apps/myapp/debug.keystore -alias my_alias \ |
| -keyalg RSA -keysize 2048 -validity 10000 |
| </pre>{/literal} |
| |
| when prompted for a keystore password, just use <code>android</code>{sp} |
| (and then type it again to confirm it), and hit Enter to accept the |
| default values for name, organizational unit, etc. |
| |
| <p> |
| |
| Then create a <code>.properties</code> file that stores all of this information: |
| |
| {literal}<pre> |
| echo "key.store=debug.keystore |
| key.alias=my_alias |
| key.store.password=android |
| key.alias.password=android" > apps/myapp/debug.keystore.properties |
| </pre>{/literal} |
| |
| <h2>Build an APK</h2> |
| |
| An Android application needs a manifest named <code>AndroidManifest.xml</code>, |
| so we must create such a file: |
| |
| {literal}<pre> |
| echo "<?xml version='1.0' encoding='utf-8'?> |
| <manifest xmlns:android='http://schemas.android.com/apk/res/android' |
| package='com.example' |
| > |
| |
| <application |
| android:label='@string/app_name' |
| android:hardwareAccelerated='true'> |
| <activity android:name='.activity.MyFirstActivity'> |
| <intent-filter> |
| <action android:name='android.intent.action.MAIN' /> |
| <category android:name='android.intent.category.LAUNCHER' /> |
| </intent-filter> |
| </activity> |
| </application> |
| |
| </manifest>" > apps/myapp/AndroidManifest.xml |
| </pre>{/literal} |
| |
| Now we define an <code><a href="rule/android_binary.html">android_binary()</a></code> rule in our build file: |
| |
| {literal}<pre> |
| echo "android_binary( |
| name = 'app', |
| manifest = 'AndroidManifest.xml', |
| target = 'Google Inc.:Google APIs:16', |
| keystore_properties = 'debug.keystore.properties', |
| deps = [ |
| '//java/com/example/activity:activity', |
| '//res/com/example/activity:res', |
| ], |
| ) |
| |
| project_config( |
| src_target = ':app', |
| )" > apps/myapp/BUCK |
| </pre>{/literal} |
| |
| Building an <code>android_binary()</code> rule will produce an APK: |
| |
| <pre>buck build{sp}//apps/myapp:app</pre> |
| |
| Alternatively, if you have an Android device connected to your computer, |
| you can build and install the APK in one step: |
| |
| <pre>buck install{sp}//apps/myapp:app</pre> |
| |
| // TODO(mbolin): Add this section. |
| // <h2>Run a Test</h2> |
| |
| <h2>Create an Alias</h2> |
| |
| Typing <code>buck build{sp}//apps/myapp:app</code> every time |
| you want to rebuild your APK can be tedious. Fortunately, Buck makes it |
| possible to define an <em>alias</em> for a build target. An alias can always be |
| used in place of a build target when using Buck's command-line interface. |
| |
| <p> |
| |
| Aliases must be defined in a config file in the root of the project: |
| |
| {literal}<pre> |
| echo "[alias] |
| app = //apps/myapp:app" > .buckconfig |
| </pre>{/literal} |
| |
| With this alias in place, the command to build and install the APK is much |
| shorter and easier to remember: |
| |
| <pre>buck install app</pre> |
| |
| <h2>Create an IntelliJ Project</h2> |
| |
| You likely want to develop your Android app using an IDE. |
| Fortunately, Buck can generate an IntelliJ project from the |
| {sp}<code><a href="rule/project_config.html">project_config()</code></a>{sp} |
| rules you defined in your build files. |
| |
| <p> |
| |
| In order to ensure that IntelliJ recognizes where your Java folders are, |
| you need to specify the following in your <code>.buckconfig</code> file: |
| |
| {literal}<pre> |
| echo "[java] |
| src_roots = /java/" >> .buckconfig |
| </pre>{/literal} |
| |
| <p> |
| |
| Now you can create the IntelliJ project by running the following command: |
| |
| <pre>buck project</pre> |
| |
| Note that you will likely want to exclude these generated files from |
| version control, so add the following to your <code>.gitignore</code> file |
| (or <code>.hgignore</code> if you are using Mercurial) along with the |
| files generated by <code>buckd</code>: |
| |
| {literal}<pre> |
| echo "*.iml |
| /.idea/compiler.xml |
| /.idea/libraries/*.xml |
| /.idea/modules.xml |
| /.idea/runConfigurations/Debug_Buck_test.xml" > .gitignore |
| /.buckd |
| </pre>{/literal} |
| |
| Now you can build your Android application from either IntelliJ or the command |
| line. |
| |
| </div> // close overview |
| |
| {call buck.footer /} |
| |
| {/template} |