README.md
1# Host-side binary for Android Virtual Device
2
3## Launcher package
4
5This is the cuttlefish launcher implementation, that integrates following
6features:
7
8* `libvirt` domain configuration,
9* `ivshmem` server,
10* USB forwarding.
11
12## Overview
13
14### ivshmem
15
16We are breaking from the general philosophy of ivshmem-server inter-vm
17communication. In this prototype there is no concept of inter-vm communication;
18guests can only talk to daemons running on host.
19
20### Requirements
21
22Cuttlefish requires the following packages to be installed on your system:
23
24Compiling:
25
26* `libjsoncpp-dev`
27* `libudev-dev`,
28* `libvirt-dev`,
29* `libxml2-dev`
30
31Running:
32
33* `linux-image-extra-virtual` to supply `vhci-hcd` module (module must be
34 loaded manually)
35* `libvirt-bin`
36* `libxml2`
37* `qemu-2.8` (or newer)
38
39### Building and Installing debian package
40
41To build debian package:
42
43```sh
44host$ cd dist
45host$ debuild --no-tgz-check -us -uc
46host$ cd ..
47host$ scp cuttlefish-common*.deb ${USER}@123.45.67.89:
48```
49
50This will create file named `cuttlefish-common_0.1-1_amd64.deb` in the root
51folder of your workspace. You will have to manually upload this file to
52your remote instance and install it as:
53
54```sh
55host$ ssh 123.45.67.89
56gce$ sudo apt install -f --reinstall ./cuttlefish-common*.deb
57```
58
59`apt` will pull in all necessary dependencies. After it's done, support files
60will be ready to use.
61
62### Host Configuration
63
64All configuration and basic deployment is covered by scripts in the
65`host/deploy` folder. To configure remote instance for cuttlefish, execute:
66
67```sh
68host$ cd host/deploy
69host$ python main.py config -i 123.45.67.89
70```
71
72The script will automatically update libvirt configuration files and user group
73membership, as well as create necessary folder for Cuttlefish images.
74
75### Uploading images
76
77To deploy cuttlefish images from build server, execute:
78
79```sh
80host$ cd host/deploy
81host$ python main.py deploy -i 123.45.67.89
82```
83
84By default, the script will pull the latest build of `cf_x86_phone-userdebug`
85target from `oc-gce-dev` branch, and latest kernel from cuttlefish kernel
86target and branch. Both system and kernel locations can be tuned by supplying
87relevant arguments via command line.
88
89Optionally, files can be populated and uploaded manually. Please ensure that
90at all times user `libvirt-qemu` can access each of these files by specifying
91correct ACL permissions using `setfacl` command, eg:
92
93```sh
94gce$ setfacl -m u:libvirt-qemu:rw /path/to/system.img
95```
96
97### Starting Cuttlefish
98
99To start cuttlefish, assuming you executed all the above:
100
101```sh
102gce$ sudo modprobe vhci-hcd
103gce$ sudo cf -system_image_dir /srv/cf/latest/ \
104 -kernel /srv/cf/latest/kernel \
105 -data_image /srv/cf/latest/data.img \
106 -cache_image /srv/cf/latest/cache.img \
107 --logtostderr
108```
109
110Shortly after, you should be able to execute `adb devices` and see your device
111listed. If device is reported as `????????`, or as:
112
113```log
114CUTTLEFISHCVD01 no permissions (verify udev rules); see [http://developer.android.com/tools/device.html]
115```
116
117you may have to re-start adb as root (we don't have udev rules updating virtual
118usb permissions yet):
119
120```sh
121gce$ adb kill-server
122gce$ sudo adb devices
123```
124