INSTALL

Requirements
============

The host machine should be a Linux box capable of building Yocto Poky
Linux.  Most of the distribution toolchain builds itself via
bootstrap, but a few tools need to be installed on the host.  Testing
on a fresh install of Ubuntu 12.04 (the author actually uses Fedora,
but this was the VM I had) shows that the following is sufficient:

   apt-get install build-essential git diffstat texinfo gawk chrpath

The Android device should have adb access working and a "su" binary
that works to achieve root access from an adb context.  Both AOSP su
and Cyanogenmod su have been tested, but note that AOSP-derived builds
only have root access with "eng" and "userdebug" configurations and
that CM 10.1 defaults to "non-developer" mode now (click on
Settings->About->Build number 7 times to enable, and set
Settings->Developer->Root access to "Apps and ADB").

Building
========

You will need a Poky linux tree in the local directory (a symlink
works fine) as "./poky".  Currently Yocdroid supports the 9.0 "Dylan"
release.  You can get this from the upstream git with:

    git clone git://git.yoctoproject.org/poky
    cd poky
    git checkout dylan

Building an image is broadly as simple as "make".  The target
architecture can be specified by passing a MACHINE variable to make.
Choices currently supported are "yd-arm" (most compatible, and
default), "yd-armv7" (for ARM Cortex A8 and later CPUs, basically all
modern devices) and "yd-x86" (for IA32 machines), e.g.:

    make MACHINE=yd-armv7

The build process will automatically download original source tarballs
for all the installed software (typically from high performance
mirrors run by yoctoproject.org).  The resulting files (about 6GB of
downloaded content) will be placed in the "oe-downloads" subdirectory
of the user's home directory and not (!) under the project build
directory.  This is so that repeated builds or "cleaned" trees don't
need to re-download source.  Do not delete this directory or its
contents or you will force a re-fetch.

The build takes about an hour on a quad core 3GHz machine, and
produces about 9GB of temporary data and a ~50MB output tarball.

Installing
==========

The tarball produced by the build (which you can find in
./tmp/deploy/images) expects to be unpacked under /data/y on the
target.  You can do this manually (as root), or use the "make install"
target that does this automatically over adb to the default connected
device, though it currently depends on finding an installed busybox
(for tar/bzip2).  If you lack busybox on your Android image, you can
get a static binary from http://busybox.net/downloads/binaries/ and
drop it in /data/ on your device (remember to "chmod 755
/data/busybox" too!).

Optionally, there is a "make install-ssh" target available to
bootstrap ssh authentication over adb using the current user's public
keys.  By default, all accounts have no password and sshd will not
allow access.

Running
=======

Once installed, at a root shell root on the device, run
"/data/y/sbin/yocdroid-start" to initialize the chroot environment.
Then "/data/y/sbin/yocdroid-run [command...]" will run the specified
command (by default a login shell) in the chroot.  Remember that the
path to the command must be a full path relative to the root of the
chroot. (Actually yocdroid-run will invoke yocdroid-start as needed
automatically.)

A very useful trick is running:

    adb shell /data/y/sbin/yocdroid-run /etc/init.d/rc 3

...to launch all the runlevel 3 daemons, including sshd.  There is a
"make start" convenience target which does exactly this.

If you want to shut down the yocdroid environment (for example, to
remove the files without manually unmounting all the bind mounts),
there is a /data/y/sbin/yocdroid-stop script to do this.  Note that it
must be run from *outside* the yocdroid environment (e.g. at an adb
shell or in a device terminal).

Hints
=====

The Avahi service uses the net.hostname property (settable on CM 10.1
under Developer options -- this is *not* the same a the kernel
host/domainname which is always "localhost.localdomain") as the
hostname.  So on a modern Linux distro you can find attached device on
your local network as "<hostname>.local" and ssh right to it without
trying to figure out an IP address.  Eventually Google will catch up
and enable mDNS by default...

A useful trick, if you use Jack Palevich's Terminal.apk for on-device
shells, is to set the shell command in preferences to "/system/xbin/su
-c /data/y/sbin/yocdroid-run" so you get the Yocdroid environment by
default.

Starting yocdroid at device boot has no single solution; the init.rc
configuration in the general case is fixed in the initrd and cannot be
modified without reflashing a kernel.  For the special case of
Cyanogenmod 10.1, the boot scripts run a /data/local/userinit.sh
script.  You can make this a symlink to /data/y/sbin/yocdroid-start or
call it as part of a larger script.

Hacking
=======

Yocdroid is based on the Yocto Project's Poky Linux distribution, and
uses openembedded-style (aside: yes, all three names get used to refer
to what is for most purposes the same code base) recipes that can be
modified as you expect.

If you want to work directly with bitbake (which is notoriously
sensitive to a correct build environment and working directory), the
Makefile will create a "bbwrap" wrapper script for you ("make bbwrap")
which sets up the environment correctly and then launches bitbake with
the supplied arguments.  So e.g. "./bbwrap -c devshell
my-package-name" does what you want.  The wrapper script will default
to the same MACHINE argument that make was invoked with, but this can
be overriden in the environment:

    MACHINE=yd-armv7 ./bbwrap [...]

You may edit the installed package list directly in
recipes/yocdroid-image/yocdroid-image.bb or with an IMAGE_INSTALL
setting in conf/local.conf:

    IMAGE_INSTALL_append = "package1 package2 ..."

The IMAGE_FEATURES mechanism from Yocto works as well, but be careful
with it because many of the existing default package lists tend to
pull in unwanted dependencies.