docs/setup/quickstart.soy

{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}

While there, you may also want to set up <a href="{ROOT}command/buckd.html"><code>buckd</code></a>:

<pre>sudo ln -s ${lb}PWD{rb}/bin/buckd /usr/bin/buckd</pre>

<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 "&lt;?xml version='1.0' encoding='utf-8' ?>
&lt;resources>
  &lt;string name='app_name'>Hello World&lt;/string>
&lt;/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.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 "&lt;?xml version='1.0' encoding='utf-8'?>
&lt;manifest xmlns:android='http://schemas.android.com/apk/res/android'
          package='com.example'
          >

  &lt;application
      android:label='@string/app_name'
      android:hardwareAccelerated='true'>
    &lt;activity android:name='.activity.MyFirstActivity'>
      &lt;intent-filter>
        &lt;action android:name='android.intent.action.MAIN' />
        &lt;category android:name='android.intent.category.LAUNCHER' />
      &lt;/intent-filter>
    &lt;/activity>
  &lt;/application>

&lt;/manifest>" > apps/myapp/AndroidManifest.xml
</pre>{/literal}

Now we define an {call buck.android_binary /} and {call buck.keystore /} rule in our build file:

{literal}<pre>
echo "android_binary(
  name = 'app',
  manifest = 'AndroidManifest.xml',
  target = 'Google Inc.:Google APIs:16',
  keystore = ':debug_keystore',
  deps = [
    '//java/com/example/activity:activity',
    '//res/com/example/activity:res',
  ],
)

keystore(
  name = 'debug_keystore',
  store = 'debug.keystore',
  properties = 'debug.keystore.properties',
)

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
/buck-cache
/buck-out
/.buckd
</pre>{/literal}

Now you can build your Android application from either IntelliJ or the command
line.

</div> // close overview

{call buck.footer /}

{/template}